Sco Admin Guide
Uploaded by
Velmurugan Gurusamy PandianSco Admin Guide
Uploaded by
Velmurugan Gurusamy PandianIBM SmartCloud Orchestrator
Version 2.3
User's Guide
IBM SmartCloud Orchestrator
Version 2.3
User's Guide
Note
Before using this information and the product it supports, read the information in Notices on page 1127.
Edition notice
This edition applies to IBM SmartCloud Orchestrator Version 2 Release 3 Fix Pack 1 (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 SmartCloud Orchestrator 2.3 information center and is
provided for convenience. This document should be used in conjunction with the information center.
Copyright IBM Corporation 2013, 2014.
US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
Contents
Tables. . . . . . . . . . . . . . . xiii
Preface . . . . . . . . . . . . . . xv
Who should read this information. . . . . . . xv
Chapter 1. Overview . . . . . . . . . 1
What is new in this release . . . . . . . . . 1
Product architecture . . . . . . . . . . . . 2
Product features . . . . . . . . . . . . . 5
Custom extensions . . . . . . . . . . . . 7
Overview of OpenStack. . . . . . . . . . . 8
Chapter 2. Installing . . . . . . . . . 9
Planning your installation . . . . . . . . . . 9
Installation overview . . . . . . . . . . 9
Installation scenarios . . . . . . . . . . 10
Manage vCenter scenario . . . . . . . . 11
Manage VMControl scenario . . . . . . 12
Scale-out KVM scenario . . . . . . . . 12
SmartCloud Orchestrator Enterprise
installation . . . . . . . . . . . . 12
Hardware prerequisites . . . . . . . . . 13
Software prerequisites . . . . . . . . . . 15
Supported operating systems . . . . . . . 16
Preparing the central server and the region server 17
Preparing the installation media . . . . . . . 21
Preparing the installation based on electronic
download packages. . . . . . . . . . . 21
Preparing the installation based on DVD images 22
Installing the central server . . . . . . . . . 23
Installing the region server . . . . . . . . . 26
List of the RPM packages added during installation 30
Installing a compute node . . . . . . . . . 44
Installing a KVM compute node by PXE. . . . 44
Installing a KVM compute node by script . . . 45
Installing a multiple-region environment . . . . 47
Verifying the installation . . . . . . . . . . 47
Performing advanced configuration tasks . . . . 49
Setting up virtual machines to install Central
Server and Region Server. . . . . . . . . 49
Managing networks . . . . . . . . . . 54
Creating a network for a KVM region . . . 54
Creating a VLAN-based network . . . . 54
Creating a flat network . . . . . . . 57
Creating a network for a VMware or Power
region . . . . . . . . . . . . . . 59
Configuring DNS for the Workload Deployer
IP groups . . . . . . . . . . . . . 61
Deleting the existing networks . . . . . . 62
Shutting down or starting Central Servers and
Region Servers . . . . . . . . . . . . 62
Integrating SmartCloud Orchestrator with
VMware vCenter . . . . . . . . . . . 63
Integrating SmartCloud Orchestrator with
VMControl . . . . . . . . . . . . . 66
Setting NTP servers . . . . . . . . . . 71
Configuring Memcached cache size . . . . . 72
Configuring Virtual Image Library proxies . . . 72
Removing a Compute Node . . . . . . . . 74
Removing a region . . . . . . . . . . . 75
Configuring LDAP authentication . . . . . . 77
Configuring LDAP authentication
independently of the domain . . . . . . 77
Configuring LDAP authentication on a
domain-by-domain basis . . . . . . . . 80
Using external Directory Integration tools with
LDAP authentication . . . . . . . . . 81
LDAP Keystone configuration file reference . 82
Modifying project quotas . . . . . . . . . 86
Preparing to install additional Enterprise
components . . . . . . . . . . . . . 87
Quick start guide for metering and billing . . 87
Confirming the creation of offerings and
categories . . . . . . . . . . . . . . 88
Changing the language settings for the vSys
offerings and categories . . . . . . . . 89
Changing the various passwords . . . . . . 89
Replacing the existing certificates . . . . . . 97
Archiving historical data . . . . . . . . 100
Content Pack installation . . . . . . . . . 101
Upgrading to Fix Pack 1. . . . . . . . . . 101
Upgrading from SmartCloud Provisioning 2.3 . . 103
High Availability . . . . . . . . . . . . 104
Using vSphere HA clusters . . . . . . . . 105
Configuring vSphere DRS . . . . . . . 106
Using System Automation Application Manager 107
Installing System Automation Application
Manager . . . . . . . . . . . . . 107
Starting System Automation Application
Manager . . . . . . . . . . . . . 108
Planning for System Automation Application
Manager configuration . . . . . . . . 109
Modifying the sample configuration files . . 110
Configuring System Automation Application
Manager . . . . . . . . . . . . . 117
(Optional) Post configuring System
Automation Application Manager with
SmartCloud Orchestrator . . . . . . . 121
Controlling the management stack . . . . 124
Troubleshooting System Automation
Application Manager . . . . . . . . . 125
Ports used by SmartCloud Orchestrator . . . . 126
Chapter 3. Getting started . . . . . . 131
Chapter 4. Administering . . . . . . 135
Starting or stopping SmartCloud Orchestrator . . 135
Accessing SmartCloud Orchestrator user interfaces 135
Managing the services . . . . . . . . . . 137
Managing services with SCOrchestrator.py . . 137
Copyright IBM Corp. 2013, 2014 iii
Running the SCOrchestrator.py script . . . 138
Running the SCOrchestrator.py script with
non-root user . . . . . . . . . . . 138
Example SCOComponents.xml . . . . . . 140
Example SCOEnvironment.xml . . . . . . 141
Backing up and restoring the services . . . . 141
Managing settings . . . . . . . . . . . . 142
Managing email delivery . . . . . . . . 142
Configuring email delivery with the user
interface . . . . . . . . . . . . . 143
Virtual Image Library configuration files . . . 143
Configuring the scalable web infrastructure
server . . . . . . . . . . . . . . . 145
Configuring session timeout value . . . . . 146
Configuring timeout value for Ajax calls . . . 146
Configuring OpenStack synchronization . . . 146
Configuring OpenStack connection . . . . . 148
Configuring OpenStack to support thin
provisioning. . . . . . . . . . . . . 149
Configuring memory and CPU overcommitment 149
Managing users, projects, and domains. . . . . 149
User roles in SmartCloud Orchestrator . . . . 151
Managing users . . . . . . . . . . . 153
Managing projects . . . . . . . . . . . 155
Managing domains . . . . . . . . . . 158
Using the Public Cloud Gateway . . . . . . . 159
Public Cloud Gateway overview . . . . . . 160
Capabilities and limitations. . . . . . . 160
Managing Amazon EC2 using the Public Cloud
Gateway . . . . . . . . . . . . . . 161
Prerequisites. . . . . . . . . . . . 161
Configuring the Public Cloud Gateway. . . 162
Managing non-IBM supplied OpenStack using
the Public Cloud Gateway . . . . . . . . 168
Prerequisites. . . . . . . . . . . . 168
Configure the Public Cloud Gateway to
manage non-IBM supplied OpenStack . . . 169
Configure the Public Cloud Gateway
regions for non-IBM supplied OpenStack . 170
Configure non-IBM supplied OpenStack
flavors. . . . . . . . . . . . . 171
Configure non-IBM supplied OpenStack
EC2 credentials . . . . . . . . . . 172
Configure IaaS Gateway and restart the
Public Cloud Gateway . . . . . . . 174
Post configuration tasks . . . . . . . . 175
Create a supported image . . . . . . 175
Troubleshooting . . . . . . . . . . . 176
Loss of functionality in Public Cloud
Gateway cloud groups . . . . . . . . 177
Loss of functionality in Public Cloud
Gateway cloud groups (2) . . . . . . . 178
Region names displayed incorrectly in the
Virtual Image page . . . . . . . . . 178
Unable to connect to a public cloud due to
missing credentials . . . . . . . . . 179
Unable to deploy instance to non-IBM
supplied OpenStack . . . . . . . . . 180
Inconsistencies in deployed instance names 180
MAC address field is empty . . . . . . 180
Reference. . . . . . . . . . . . . . 181
Key pairs. . . . . . . . . . . . . 181
Command-line interface scripts . . . . . 181
Password authentication on Amazon EC2
images . . . . . . . . . . . . . 181
Configuring the Public Cloud Gateway
regions to use a proxy server . . . . . . 182
Building the cloud with topology resources . . . 183
Managing cloud resources . . . . . . . . 183
Administering cloud groups . . . . . . 184
Managing availability zones in OpenStack 185
Fields on the Cloud Groups window . . 186
Administering hypervisors . . . . . . . 187
vCenter management . . . . . . . . 188
Restricting access to vCenter . . . . . 190
VMware administrative user minimum
rights . . . . . . . . . . . . . 190
Fields on the Hypervisors window . . . 191
Administering virtual machines . . . . 194
Administering networks. . . . . . . 203
Administering storage . . . . . . . 206
Hypervisor states . . . . . . . . . 207
Administering IP groups and IP addresses 208
IP groups. . . . . . . . . . . . 209
Administering IP groups and IP addresses
with the user interface . . . . . . . 210
Managing environment profiles . . . . . . 220
Environment profiles overview . . . . . 221
Managing environment profiles in the user
interface . . . . . . . . . . . . . 222
Creating an environment profile . . . . 223
Cloning an environment profile . . . . 227
Editing an environment profile . . . . 228
Environment Profiles window fields . . . 230
Populating the catalog . . . . . . . . . . 233
Managing script packages . . . . . . . . 234
Script packages overview . . . . . . . 235
Example script package to install an
application . . . . . . . . . . . 236
Example script to configure the trace
levels . . . . . . . . . . . . . 238
Example script package to create a server 239
Example script package to create a
WebSphere Application Server cluster . . 240
Using script packages with the user interface 242
Adding a script package. . . . . . . 243
Cloning a script package . . . . . . 245
Making script packages read-only . . . 246
Associating a script package with a
pattern . . . . . . . . . . . . 247
Deleting a script package . . . . . . 248
Windows sample to check if a file already
exists . . . . . . . . . . . . . 249
Configuring a script package using a JSON
object . . . . . . . . . . . . . . 250
Script package environment variables . . . 251
Properties variable syntax . . . . . . . 253
Managing add-ons . . . . . . . . . . 254
Add-ons in the catalog . . . . . . . . 255
Managing add-ons with the user interface 257
Adding add-ons to the catalog . . . . 258
Cloning an add-on . . . . . . . . 259
iv IBM SmartCloud Orchestrator 2.3: User's Guide
Editing an add-on . . . . . . . . . 261
Making add-ons read-only . . . . . . 262
Associating an add-on with a pattern . . 263
Deleting an add-on . . . . . . . . 264
Fields on the Add-Ons user interface . . 265
Managing key pairs . . . . . . . . . . . 268
Monitoring the task queue . . . . . . . . . 269
Auditing . . . . . . . . . . . . . . . 270
Audit events . . . . . . . . . . . . 271
Audit event record attributes and usage tips . . 272
Download options for audit event records . . . 277
Retrieving audit data with the user interface 278
Retrieving audit data with the REST API . . 279
Monitoring the status of audit data storage . . 283
Deleting audit data to free storage . . . . . 284
Chapter 5. Managing virtual images 287
Managing virtual images with the user interface 288
Importing a virtual image to the catalog . . . 289
Registering a virtual image . . . . . . . . 290
Removing a virtual image from the catalog . . 291
Virtual image fields on the user interface . . . 292
Adding images to OpenStack . . . . . . . . 294
Working with Virtual Image Library. . . . . . 295
Overview. . . . . . . . . . . . . . 295
Virtual Image Library basics . . . . . . 296
Installing and configuring . . . . . . . . 299
Installing . . . . . . . . . . . . . 299
Installing the proxy component . . . . 301
Configuring . . . . . . . . . . . . 303
Configuring Virtual Image Library server
and remote proxy components . . . . 303
Configuring Virtual Image Library proxies
with slow connectivity . . . . . . . 304
Configuring Virtual Image Library for
VMware . . . . . . . . . . . . 305
Uninstalling . . . . . . . . . . . . 306
Uninstalling Virtual Image Library . . . 306
Uninstalling the distributed proxy . . . 307
Best practices . . . . . . . . . . . 307
Managing reference images. . . . . . 307
Managing the remote proxy . . . . . 309
Changing the WebSphere account
password. . . . . . . . . . . . 310
Backing up and restoring the proxy . . . 310
Getting started . . . . . . . . . . . . 311
User roles and requirements . . . . . . 312
Assigning a role to a user . . . . . . 313
Adding an operational repository . . . . 314
Changing server access credentials . . . 316
Removing an operational repository . . . 316
Indexing an image. . . . . . . . . . 317
Enabling the Keystone user registry . . . . 318
Managing Virtual Image Library . . . . . . 318
Managing the resource access control list . . 319
Copying an image to the reference repository 320
Importing an image . . . . . . . . . 321
Copying an image from the reference
repository . . . . . . . . . . . . 322
Removing an image from the reference
repository . . . . . . . . . . . . 323
Tracking image version and provenance . . 323
Moving an image to a different version
chain . . . . . . . . . . . . . 325
Searching for images . . . . . . . . . 326
Comparing images . . . . . . . . . 326
Finding similar images . . . . . . . . 327
Synchronizing repositories . . . . . . . 328
Using the plug-in for vSphere Client . . . . 328
Troubleshooting . . . . . . . . . . . 330
Log files . . . . . . . . . . . . . 330
Changing the time zone . . . . . . . . 332
Known problems and limitations . . . . . 333
Limitations . . . . . . . . . . . 333
Cannot check in a deployed virtual
machine . . . . . . . . . . . . 334
Cannot connect to the HBase database . . 334
NoClassDefFoundError exception . . . 334
rbagent component does not start . . . 335
Error 404 - Too many open files . . . . 335
Cannot create HBase tables . . . . . . 336
Disk space lower than the safe threshold
value . . . . . . . . . . . . . 336
Configuring WebSphere Application
Server . . . . . . . . . . . . . 337
Modifying the default check out settings 337
Image checkout fails . . . . . . . . 338
Domain status is out of sync . . . . . 338
New region, new repository, or new
image does not appear . . . . . . . 339
Virtual Image Library fails with message
java.lang.NoClassDefFoundError . . . . 339
After moving a Linux image, you have
problems starting the image . . . . . 339
REST API reference . . . . . . . . . . 340
ImageManager API reference . . . . . . 341
Administration REST API . . . . . . 341
Analytics REST API . . . . . . . . 343
Connector REST API . . . . . . . . 350
Domain REST API. . . . . . . . . 358
Image log REST API . . . . . . . . 361
Location REST API . . . . . . . . 362
Operational repository REST API . . . . 364
Operational images REST API . . . . . 365
Users REST API . . . . . . . . . 381
Version chain REST API . . . . . . . 381
IaaS API reference . . . . . . . . . . 385
Glance API . . . . . . . . . . . 385
OVF metadata REST API . . . . . . 386
Working with IBM Image Construction and
Composition Tool . . . . . . . . . . . . 387
Installing, upgrading, and uninstalling Image
Construction and Composition Tool . . . . . 389
Installing IBM Image Construction and
Composition Tool on Linux. . . . . . . 390
Upgrading the Image Construction and
Composition Tool . . . . . . . . . . 393
Upgrading from a previous version . . . 393
Upgrading silently from a previous
version . . . . . . . . . . . . 394
Uninstalling the product. . . . . . . . 395
Uninstalling a fix pack . . . . . . . 395
Contents v
Uninstalling the Image Construction and
Composition Tool . . . . . . . . . 395
Uninstalling the Image Construction and
Composition Tool silently . . . . . . 396
Getting started . . . . . . . . . . . . 396
The basics . . . . . . . . . . . . 396
Universal identifiers . . . . . . . . . 397
System requirements . . . . . . . . . 398
Changing your user password. . . . . . 398
Managing the Image Construction and
Composition Tool server. . . . . . . . 399
Managing the firewall . . . . . . . . 399
Configuring cloud providers . . . . . . 399
Configuring the OpenStack cloud provider 400
Working with virtual images . . . . . . . 400
Importing base images from OpenStack . . 401
Building virtual images . . . . . . . . 401
Extending virtual images . . . . . . 403
Adding software bundles to virtual
images . . . . . . . . . . . . 403
Adding licenses to virtual images . . . 405
Adding personalities to virtual images 405
Synchronizing virtual images . . . . . 407
Capturing virtual images . . . . . . 409
Creating virtual images from a template 409
Managing software bundles . . . . . . 410
Preparing to create software bundles . . 411
Creating software bundles . . . . . . 412
Searching for bundles . . . . . . . 417
Extending software bundles . . . . . 417
Uploading large files when creating
software bundles . . . . . . . . . 418
Sharing software bundles . . . . . . 418
Using the command-line interface . . . . . 419
Command-line interface high-level procedure 420
Command-line interface overview . . . . 421
Downloading and configuring the
command-line interface . . . . . . . . 422
Invoking the command-line interface . . . 423
Invoking in interactive mode . . . . . 425
Invoking in batch mode . . . . . . . 426
Command-line interface resource object
reference . . . . . . . . . . . . . 428
Bundles reference . . . . . . . . . 428
Cloud providers reference . . . . . . 449
Images reference . . . . . . . . . 452
Users reference . . . . . . . . . . 461
Problem determination reference for the
command-line interface . . . . . . . 463
Getting help on the command-line interface 465
Troubleshooting issues with Image Construction
and Composition Tool . . . . . . . . . 466
Log files for troubleshooting . . . . . . 466
Setting logging levels for troubleshooting . . 467
Adjusting the configuration timeout settings 468
Log files for virtual image synchronization 469
Troubleshooting problems during VM
activation. . . . . . . . . . . . . 470
Working with enablement bundles . . . . 471
Updating Activation Engine in a virtual
image . . . . . . . . . . . . . . 472
Image Construction and Composition Tool
does not respond . . . . . . . . . . 473
Image Construction and Composition Tool
does not start after installation . . . . 473
Image Construction and Composition Tool
returns EOFException . . . . . . . 474
Install executable launcher error during
installation . . . . . . . . . . . . 474
Exec error 1 during installation . . . . . 475
Universal ID and version must be unique 475
Cancel - use the current file link does not
work . . . . . . . . . . . . . . 475
Failure during OVA disk conversion. . . . 476
Import or export of the OVA file fails . . . 476
Error occurs during OVA export . . . . . 476
Virtual image capture fails . . . . . . . 477
Extending an image fails . . . . . . . 477
Virtual images that contain old versions of
the activation engine cannot be deployed . . 479
Files are not replaced correctly . . . . . 479
The user interface stops responding while
uploading files . . . . . . . . . . . 479
Limitation when performing concurrent
updates . . . . . . . . . . . . . 480
Cannot remove software bundles from a
personality . . . . . . . . . . . . 480
Bundles are not displayed in the list of
compatible images. . . . . . . . . . 480
Limitation when adding bundles to a
personality . . . . . . . . . . . . 480
Limitation when deleting images that are
synchronizing . . . . . . . . . . . 481
Time lag when deleting virtual images . . . 481
Virtual image synchronization takes a long
time . . . . . . . . . . . . . . 481
Virtual image synchronization fails after five
hours for images . . . . . . . . . . 482
SSL exception . . . . . . . . . . . 483
Cannot pass characters for arguments on the
command line . . . . . . . . . . . 483
Deploying a pattern with parts created by
Image Construction and Composition Tool
might not work . . . . . . . . . . 483
Import fails using OpenStack cloud provider 484
New password is not set after upgrade or
reinstallation . . . . . . . . . . . 484
Virtual image synchronization problems . . 484
Synchronization fails for a virtual image
imported from a running virtual machine . 484
Virtual image synchronization fails
because of return code value . . . . . 485
Virtual image synchronization fails and
troubleshooting is not possible . . . . 487
Windows image synchronization fails . . 487
Synchronization fails on a Linux operating
system . . . . . . . . . . . . 488
Image management . . . . . . . . . . . 488
Creating new images or using existing images 488
Creating new AIX or Linux images or using
existing ones . . . . . . . . . . . 488
Prerequisites for KVM or VMware images 488
vi IBM SmartCloud Orchestrator 2.3: User's Guide
Creating new images or using existing
images on KVM . . . . . . . . . 490
Creating new images or using existing
images on VMware . . . . . . . . 492
Creating new images or using existing
images on VMControl . . . . . . . 492
Creating new Windows images or using
existing ones . . . . . . . . . . . 494
Prerequisites for KVM or VMware images 494
Creating new images or using existing
images on KVM . . . . . . . . . 497
Creating new images or using existing
images on VMware . . . . . . . . 498
Importing images . . . . . . . . . . . 498
Registering images . . . . . . . . . . 500
Deploying images . . . . . . . . . . . 501
Deploying an image through a pattern in
OpenStack . . . . . . . . . . . . 501
Deploying an image through a pattern in
vCenter or VMControl . . . . . . . . 503
Extending images . . . . . . . . . . . 505
Extending images in OpenStack . . . . . 505
Extending images in vCenter . . . . . . 507
Image management on Power . . . . . . . 509
Chapter 6. Managing and deploying
virtual patterns. . . . . . . . . . . 511
Virtual pattern types . . . . . . . . . . . 511
Working with virtual system patterns . . . . . 511
Supported virtual system patterns . . . . . 512
Working with virtual system patterns in the
user interface . . . . . . . . . . . . 513
Selecting a virtual system pattern. . . . . 514
Using a predefined virtual system pattern 516
Cloning an existing virtual system pattern 517
Creating a virtual system pattern. . . . 519
Editing a virtual system pattern . . . . . 521
Virtual system pattern editing views and
parts . . . . . . . . . . . . . 522
Ordering parts to run at deployment . . 526
Configuring parts . . . . . . . . . . 527
Configuring advanced options. . . . . . 529
Configuring advanced options for cluster
virtual system patterns . . . . . . . 532
Configuring advanced options for
Intelligent Management Pack . . . . . 536
Configuring advanced messaging for
databases. . . . . . . . . . . . 541
Configuring advanced options for single
server virtual system patterns . . . . . 543
Configuring database implemented
session persistence for Derby . . . . . 545
Making virtual system patterns read-only 546
Deploying a virtual system pattern . . . . 547
Deploying a pattern with additional
actions . . . . . . . . . . . . 551
Deleting a virtual system pattern . . . . . 551
Virtual system pattern windows . . . . . 552
Fields on the Virtual System Patterns
window . . . . . . . . . . . . 554
Fields on the Pattern Editor window . . 556
Virtual system pattern processing . . . . . 559
Creating new flavors in OpenStack . . . . . 560
Customizing flavors for Power features. . . . 561
Managing virtual system instances . . . . . 562
Managing virtual system instances with the
user interface . . . . . . . . . . . 563
Starting a persistent virtual system
instance . . . . . . . . . . . . 565
Stopping a persistent virtual system
instance . . . . . . . . . . . . 566
Removing a virtual system instance . . . 567
Creating a snapshot image . . . . . . 569
Restoring virtual system instances from a
snapshot image. . . . . . . . . . 570
Deleting snapshot images . . . . . . 571
Virtual Systems fields on the user
interface . . . . . . . . . . . . 572
Accessing virtual machines in your virtual
system instance. . . . . . . . . . 573
Expanding disk on deployed virtual
machines . . . . . . . . . . . . 574
Viewing the details for your virtual
machines . . . . . . . . . . . . 575
Working with virtual applications . . . . . . 581
Virtual application pattern components. . . . 583
Managing pattern types . . . . . . . . . 585
Viewing pattern types . . . . . . . . 586
Viewing the plug-ins in the pattern types . . 587
Importing pattern types . . . . . . . . 587
Removing a pattern type . . . . . . . 588
Upgrading pattern types . . . . . . . 588
Upgrading a deployed pattern type . . . . 589
Pattern type packaging reference . . . . . 590
Managing virtual applications . . . . . . . 591
Creating virtual application patterns. . . . 592
Editing virtual application patterns . . . . 593
Cloning virtual application patterns . . . . 594
Deleting virtual application patterns. . . . 595
Creating virtual application layers . . . . 595
Editing virtual application layers . . . . . 596
Deleting virtual application pattern layers 597
Importing virtual application pattern layers 598
Working with reusable application
components . . . . . . . . . . . . 598
Working with virtual application templates 599
Creating a virtual application template 600
Creating virtual applications from
templates. . . . . . . . . . . . 601
Cloning a virtual application template . . 602
Editing virtual application templates . . 603
Importing a virtual application template 603
Exporting a virtual application template 604
Removing a virtual application template 604
Working with virtual application pattern
plug-ins . . . . . . . . . . . . . . 605
Managing system plug-ins . . . . . . . 606
Plug-ins shipped with pattern types . . . 606
Adding system plug-ins to the catalog . . 607
Deleting plug-ins from the catalog . . . 607
Virtual application pattern components. . . 607
Application components. . . . . . . 609
Contents vii
Database components . . . . . . . 623
User Registry components . . . . . . 633
Messaging components . . . . . . . 643
OSGi components . . . . . . . . . 648
Transaction processing components . . . 653
Other components. . . . . . . . . 658
Policies . . . . . . . . . . . . 660
Developing plug-ins . . . . . . . . . 666
Plug-in Development Kit . . . . . . 671
Plug-in development guide. . . . . . 676
Samples . . . . . . . . . . . . 723
Deploying virtual applications. . . . . . . 735
Deploying virtual application patterns . . . 736
Terminating virtual machines and
reclaiming IP addresses . . . . . . . 740
Deploying virtual application templates . . 741
Securing virtual applications . . . . . . 744
Securing virtual application instances with
SSL. . . . . . . . . . . . . . 744
Configuring SSH key-based access during
application deployment . . . . . . . 746
Configuring SSH key-based access in the
user interface . . . . . . . . . . 747
LTPA keys . . . . . . . . . . . 748
Working with virtual application instances . . 749
Monitoring virtual application instances . . 751
Viewing virtual application instance logs 752
Using the command-line interface for
applications . . . . . . . . . . . . . 753
Working with shared services . . . . . . . . 754
Deploying shared services . . . . . . . . 754
Monitoring shared services . . . . . . . . 755
Deploying a monitoring shared service . . . 756
Enabling TOSCA support for SmartCloud
Orchestrator . . . . . . . . . . . . . . 757
Configuring the RPM repository for the
deployment of TOSCA patterns . . . . . . 757
Configuring an RPM repository of type ISO
Image on NFS . . . . . . . . . . . 758
Configuring an RPM repository of type FTP 759
Configuring an RPM repository of type
HTTP . . . . . . . . . . . . . . 759
Disabling the configuration of an RPM
repository . . . . . . . . . . . . 760
Configuring Chef support for TOSCA based
virtual application patterns . . . . . . . . 760
Chapter 7. Managing orchestration
workflows . . . . . . . . . . . . . 763
Orchestration workflows . . . . . . . . . 763
Self-service offerings . . . . . . . . . . 764
User actions . . . . . . . . . . . . . 764
Event-triggered actions . . . . . . . . . 765
Samples and standard extensions for orchestration
workflows . . . . . . . . . . . . . . 765
Working with Business Process Manager . . . . 766
Setting up IBM Process Designer . . . . . . 766
Adding users to IBM Process Designer . . . 767
Creating a process application in Process
Designer . . . . . . . . . . . . . . 767
Reusing processes and human services in a
process application . . . . . . . . . 769
Editing process applications and toolkits . . 769
Creating a process . . . . . . . . . . . 769
User input required at service request time 771
Making a new process available as a self-service
offering . . . . . . . . . . . . . . 771
Making a process available as an orchestration
action . . . . . . . . . . . . . . . 772
Upgrading a process on a development system
or production system. . . . . . . . . . 773
Configuring development mode . . . . . 774
Configuring production mode . . . . . . 774
Guidelines for working with Business Process
Manager . . . . . . . . . . . . . . 775
Guidelines for naming and documenting
your toolkit or process application . . . . 775
Guidelines for creating artifacts in a toolkit 776
Guidelines to structure your solution . . . 777
Guidelines for handling errors. . . . . . 777
Chapter 8. Working with self-service 779
Managing self-service offerings . . . . . . . 779
Adding offerings . . . . . . . . . . . 779
Categorizing self-service offerings . . . . . 779
Modifying self-service offerings . . . . . . 780
Using self-service . . . . . . . . . . . . 780
Navigating the Self-Service panel . . . . . . 780
Submitting a self-service request . . . . . . 781
Viewing the status of your requests . . . . . 781
Completing an assignment in My Inbox . . . 782
Chapter 9. Integrating . . . . . . . . 783
Integrating with IBM Tivoli Monitoring . . . . 783
Preparing a base operating system . . . . . 783
Database setup . . . . . . . . . . . . 784
Installing IBM Tivoli Monitoring . . . . . . 784
Packages used for installation . . . . . . 785
Creating a warehouse database . . . . . . 786
Monitoring Agent for Linux . . . . . . . 787
Monitoring Agent for Kernel-based virtual
machines . . . . . . . . . . . . . . 787
OpenStack hypervisors . . . . . . . . . 788
Installing Image Construction and Composition
Tool bundle to deploy Tivoli Monitoring agents . 788
Integrating with IBM Endpoint Manager . . . . 790
Installing Endpoint Manager agent to existing
computers . . . . . . . . . . . . . 790
Installing Endpoint Manager agents during
virtual machine deployment . . . . . . . 790
Chapter 10. Reporting. . . . . . . . 799
Machine activity reporting . . . . . . . . . 800
User activity reporting . . . . . . . . . . 801
Tivoli Common Reporting . . . . . . . . . 802
Installing Jazz for Service Management and Tivoli
Common Reporting . . . . . . . . . . . 802
Installing Jazz for Service Management in the
silent mode . . . . . . . . . . . . . 803
viii IBM SmartCloud Orchestrator 2.3: User's Guide
Installing Tivoli Common Reporting in the silent
mode . . . . . . . . . . . . . . . 804
Chapter 11. Reference. . . . . . . . 805
Using the command-line interface . . . . . . 805
Command-line interface overview . . . . . 806
Core functions . . . . . . . . . . . . 807
Command-line interface resource object
reference . . . . . . . . . . . . . . 808
AddOn command-line interface reference . . 810
Audit logging command-line interface
reference . . . . . . . . . . . . . 813
Cloud group command-line interface
reference . . . . . . . . . . . . . 815
Domain Name System (DNS) server
command-line interface reference. . . . . 817
Environment profiles command-line interface
reference . . . . . . . . . . . . . 819
Environment profiles on the
command-line interface . . . . . . . 820
Environment profile clouds on the
command-line interface . . . . . . . 824
Environment profile cloud IP groups on
the command-line interface. . . . . . 827
Hypervisor command-line interface reference 830
Image command-line interface reference . . 833
IP command-line interface reference . . . . 834
IP group command-line interface reference 838
Mail delivery command-line interface
reference . . . . . . . . . . . . . 841
Maintenance command-line interface
reference . . . . . . . . . . . . . 841
Network command-line interface reference 843
Pattern command-line interface reference . . 844
Importing and exporting virtual system
patterns . . . . . . . . . . . . 846
Patterns on the command-line interface 848
Pattern parts on the command-line
interface . . . . . . . . . . . . 855
Pattern scripts on the command-line
interface . . . . . . . . . . . . 861
Parts on the command-line interface. . . 867
Pattern type command-line interface . . . 870
Plug-in command-line interface reference . . 872
Problem determination command-line
interface reference . . . . . . . . . . 874
Script package command-line interface
reference . . . . . . . . . . . . . 876
Snapshots on the command-line interface . . 880
Storage command-line interface reference . . 882
Virtual application instance command-line
interface reference . . . . . . . . . . 883
Virtual application pattern command-line
interface reference . . . . . . . . . . 886
Virtual images command-line interface
reference . . . . . . . . . . . . . 893
Virtual machines on the command-line
interface . . . . . . . . . . . . . 899
Virtual system instances command-line
interface reference . . . . . . . . . . 902
Downloading and configuring the
command-line interface . . . . . . . . . 909
Invoking the command-line interface . . . . 911
Using the command-line interface for
applications . . . . . . . . . . . . . 913
Getting help on the command-line interface . . 913
Resources, resource collections, and methods 914
Resources on the command line . . . . . 916
Resource collections on the command line 920
Resource methods on the command-line
interface . . . . . . . . . . . . . 921
Resource collections methods on the
command-line interface . . . . . . . . 927
Wizard objects on the command-line interface 933
ACL object . . . . . . . . . . . . 935
Additional command-line interface utilities . . 938
REST API reference . . . . . . . . . . . 940
REST API frameworks . . . . . . . . . 941
Application patterns REST API . . . . . . 942
Auditing REST API . . . . . . . . . . 950
Certificates REST API . . . . . . . . . 952
Cloud groups REST API . . . . . . . . . 954
diagnostics.zip file REST API . . . . . . 961
Environment profiles REST API . . . . . . 962
Hypervisors REST API . . . . . . . . . 966
IP addresses REST API . . . . . . . . . 973
IP groups REST API . . . . . . . . . . 977
Log viewer manager REST API . . . . . . 983
Logging REST API . . . . . . . . . . 985
Monitoring REST API . . . . . . . . . 987
Networks REST API . . . . . . . . . . 991
Pattern types REST API . . . . . . . . . 994
Patterns REST API. . . . . . . . . . . 997
Plug-ins REST API . . . . . . . . . . 1002
Shared services REST API . . . . . . . . 1004
Storage REST API . . . . . . . . . . 1006
Version REST API . . . . . . . . . . 1009
Virtual appliance instances REST API . . . . 1010
Virtual applications REST API . . . . . . 1014
Virtual images REST API . . . . . . . . 1019
Virtual machines REST API . . . . . . . 1025
Virtual system instances REST API . . . . . 1030
OpenStack and IaaS REST API . . . . . . 1040
Using REST APIs to manage users, projects,
roles, and domains . . . . . . . . . 1041
Orchestration actions REST API . . . . . . 1043
List all orchestration action entries . . . . 1043
Retrieve an orchestration action entry . . . 1044
Add or update an entry in the orchestration
actions . . . . . . . . . . . . . 1045
Delete an orchestration action entry . . . 1046
Get entries for a specific virtual system 1046
Business Process Manager Invoker REST API 1047
Retrieve available BPM Business Processes 1047
List all BPM Business Processes . . . . 1047
Get entries for a specific BPM Business
Process . . . . . . . . . . . . 1048
Retrieve available human services . . . . 1048
List all human services . . . . . . . 1048
Get entries for a specific human service 1049
Retrieve My Inbox . . . . . . . . . 1050
Contents ix
List all My Inbox items. . . . . . . 1050
Get entries for a specific My Inbox item 1052
Service instance REST API. . . . . . . . 1053
Get entries for a specific service instance 1054
Metadata parameters REST APIs . . . . . 1057
Get parameters of specific metadata . . . 1057
Post metadata parameters . . . . . . . 1058
Delete parameters of specific metadata . . 1058
Virtual machines parameters REST API . . . 1059
Get parameters of a specific virtual machine 1059
Post virtual machine parameters . . . . 1059
Delete parameters of specific virtual
machines . . . . . . . . . . . . 1060
Task engine REST API . . . . . . . . . 1060
List all currently running and recently
completed tasks . . . . . . . . . . 1060
Get entries for a specific task. . . . . . 1061
Deployment parameters REST API . . . . . 1062
Get deployment parameters for a specific
instance . . . . . . . . . . . . . 1063
Post deployment parameters for a specific
instance . . . . . . . . . . . . . 1064
Self-service offering REST API . . . . . . 1064
List all self-service offerings . . . . . . 1064
Get entries for a specific self-service offering 1066
Delete a specific self-service offering . . . 1068
Update a specific self-service offering . . . 1068
Executing a self-service offering . . . . . 1069
Chapter 12. Troubleshooting . . . . 1077
Finding the log files . . . . . . . . . . . 1077
Problem determination with pdcollect tool . . . 1078
Running the pdcollect tool . . . . . . . 1079
Running the pdcollect tool with non-root user 1080
Example Components.xml . . . . . . . . 1081
Example Environment.xml . . . . . . . . 1083
Example Environment_work.xml . . . . . . 1083
Setting logging levels . . . . . . . . . . 1084
Controlling the size of the IaaS gateway log file 1086
Workload Deployer log files . . . . . . . . 1087
Known errors and limitations . . . . . . . 1088
Product limitations . . . . . . . . . . 1089
Installation errors . . . . . . . . . . 1089
Region Server installation failure with error:
Region already exists. . . . . . . . 1089
Installation fails because the chef-server is
down. . . . . . . . . . . . . . 1089
Installation fails to deploy central servers 1090
Installation fails to deploy central servers (2) 1091
Region Server deployment completes with
network configuration warning . . . . . 1092
Error when upgrading the Region Server 1092
Upgrade Central Server fails while re-run
deploy_central_server.sh . . . . . . 1093
Hypervisor errors and scenarios that can cause
them . . . . . . . . . . . . . . . 1094
Image errors . . . . . . . . . . . . 1096
Instance errors. . . . . . . . . . . . 1100
Deployment errors . . . . . . . . . . 1100
Setting the host name when deploying a
Windows system . . . . . . . . . . 1100
Unable to deploy a virtual system pattern
with a non-admin user . . . . . . . . 1101
Error displayed when deploying a virtual
system pattern. . . . . . . . . . . 1102
Unable to deploy a virtual machine in a
VMware multi-region environment . . . . 1102
Unable to deploy a virtual machine due to
insufficient resources . . . . . . . . 1103
Deployment might hang . . . . . . . 1103
Unable to deploy IBM DB2 Enterprise or
WebSphere MQ OVA image . . . . . . 1104
Unable to deploy WebSphere Application
Server OVA image . . . . . . . . . 1104
Unable to deploy WebSphere Portal 8.0.0.1
pattern . . . . . . . . . . . . . 1105
Unable to deploy IBM InfoSphere
Information Server Enterprise Edition 9.1
pattern . . . . . . . . . . . . . 1106
Unable to deploy IBM Integration Bus
Hypervisor Edition pattern . . . . . . 1106
Unable to deploy or to delete virtual
machines . . . . . . . . . . . . 1107
Deployment of the virtual system pattern
fails due to the name of the virtual machine. 1110
Script execution does not report failing
condition . . . . . . . . . . . . 1111
nova command errors and limitations . . . . 1111
Security limitations . . . . . . . . . . 1112
User interface errors . . . . . . . . . . 1112
Fixing command-line interface errors when
using multi-byte character sets . . . . . . 1113
SmartCloud Entry does not function properly 1114
Command nova-cloud-create fails with an error 1114
Unable to change the flavor of VMware virtual
machines . . . . . . . . . . . . . 1114
Error message displayed after launching a
virtual system . . . . . . . . . . . . 1115
Unable to list keystone endpoints on the
Region Server . . . . . . . . . . . . 1116
Unable to log in by using an LDAP user . . . 1118
Must remove hosts that are not eligible for
cloud . . . . . . . . . . . . . . . 1118
Hotplug is not fully supported . . . . . . 1119
Unable to capture a NIM-based image in
VMControl . . . . . . . . . . . . . 1119
Troubleshooting Workload Deployer . . . . . 1122
Failure to deploy a virtual system or
application when a linked clone is enabled . . 1122
Increasing the default timeout if hypervisor
fails . . . . . . . . . . . . . . . 1122
Troubleshooting virtual applications . . . . . 1122
Setting runtime trace in the Agent process . . 1123
Deployment stops during middleware setup in
VMware. . . . . . . . . . . . . . 1123
Troubleshooting Business Process Manager . . . 1123
Troubleshooting Virtual Image Library . . . . 1124
Troubleshooting Image Construction and
Composition Tool . . . . . . . . . . . 1125
x IBM SmartCloud Orchestrator 2.3: User's Guide
Notices . . . . . . . . . . . . . 1127
Glossary . . . . . . . . . . . . . 1129
A . . . . . . . . . . . . . . . . . 1129
B . . . . . . . . . . . . . . . . . 1130
C . . . . . . . . . . . . . . . . . 1130
E . . . . . . . . . . . . . . . . . 1130
H . . . . . . . . . . . . . . . . . 1130
K . . . . . . . . . . . . . . . . . 1130
O . . . . . . . . . . . . . . . . . 1131
P . . . . . . . . . . . . . . . . . 1131
R . . . . . . . . . . . . . . . . . 1132
S . . . . . . . . . . . . . . . . . 1132
T . . . . . . . . . . . . . . . . . 1132
V . . . . . . . . . . . . . . . . . 1133
Trademarks and service marks . . . 1135
Privacy policy considerations . . . . 1137
Accessibility features for SmartCloud
Orchestrator . . . . . . . . . . . 1139
Contents xi
xii IBM SmartCloud Orchestrator 2.3: User's Guide
Tables
1. Summary of SmartCloud Orchestrator
installation scenarios . . . . . . . . . 10
2. The minimum Manage-from requirements 13
3. KVM Compute Nodes . . . . . . . . . 14
4. VMware Compute Nodes . . . . . . . . 14
5. Power Compute Nodes . . . . . . . . 15
6. Host and guest operating systems supported
by the standard installation . . . . . . . 16
7. Host and guest operating systems supported
by the hypervisors . . . . . . . . . . 16
8. Compulsory attributes . . . . . . . . . 24
9. Compulsory configurations . . . . . . . 27
10. Configuration file options in ldap_pre_auth
section . . . . . . . . . . . . . . 82
11. Configuration file options in auto-population
section . . . . . . . . . . . . . . 85
12. Environment configuration in sample files 109
13. Ports used by SmartCloud Orchestrator 126
14. Object level access definitions . . . . . . 153
15. Ports used by Public Cloud Gateway 161
16. Parameters that are used in the admin.json
file . . . . . . . . . . . . . . . 163
17. Parameters used in the config.json file 164
18. Parameters that are used in the
credentials.json file . . . . . . . . . 165
19. Ports used by Public Cloud Gateway 169
20. Parameters used in the cacheCounter tag
section of the config.json file . . . . . . 178
21. The minimum rights of a VMware
administrative user . . . . . . . . . 190
22. Events that are tracked by audit data 271
23. Universal event record attributes . . . . . 273
24. Attribute name-value pairs . . . . . . . 273
25. Download options for audit data . . . . . 277
26. Overview of sample scripts . . . . . . . 280
27. User roles. . . . . . . . . . . . . 297
28. User roles. . . . . . . . . . . . . 312
29. Creating an image using Image Construction
and Composition Tool . . . . . . . . 388
30. Main Image Construction and Composition
Tool pages . . . . . . . . . . . . 397
31. Specify the software to install on your
instances . . . . . . . . . . . . . 414
32. Incoming connectable components . . . . 609
33. Policy components for enterprise applications 611
34. Incoming connectable components . . . . 611
35. Outgoing connectable components . . . . 612
36. Incoming connectable components . . . . 616
37. Incoming connectable components . . . . 617
38. Policy components for web applications 618
39. Incoming connectable components . . . . 619
40. Outgoing connectable components . . . . 619
41. Incoming connectable components . . . . 625
42. Incoming connectable components . . . . 626
43. Incoming connectable components . . . . 628
44. Incoming connectable components . . . . 630
45. Incoming connectable components . . . . 631
46. Incoming connectable components . . . . 634
47. Incoming connectable components . . . . 637
48. Incoming connectable components . . . . 640
49. Incoming connectable components . . . . 644
50. Incoming connectable components . . . . 645
51. Incoming connectable components . . . . 647
52. Incoming connectable components . . . . 649
53. Incoming connectable components . . . . 650
54. Outgoing connectable components . . . . 650
55. Incoming connectable components . . . . 654
56. Incoming connectable components . . . . 657
57. Incoming connectable components . . . . 659
58. Outgoing connectable components . . . . 661
59. Outgoing connectable components . . . . 662
60. Outgoing connectable components . . . . 663
61. Outgoing connectable components . . . . 664
62. Role state and status . . . . . . . . . 689
63. Logtypes . . . . . . . . . . . . . 709
64. Custom logtypes . . . . . . . . . . 709
65. Monitoring collector types. . . . . . . . 714
66. Monitoring collector types. . . . . . . . 715
67. Monitor types . . . . . . . . . . . 717
68. Chart types . . . . . . . . . . . . 717
69. Possible status values for a deployed virtual
application . . . . . . . . . . . . 738
70. Possible status values for a deployed virtual
application . . . . . . . . . . . . 742
71. Possible status values for a deployed virtual
application . . . . . . . . . . . . 749
72. Editing process applications and toolkits 769
73. List all application patterns.. . . . . . . 942
74. Create an application pattern with specific
attributes details. . . . . . . . . . . 942
75. Create an application pattern from an existing
application or template (clone) details. . . . 943
76. List application pattern with various filters
details. . . . . . . . . . . . . . . 944
77. Update application pattern details. . . . . 945
78. Return detailed information about the
application pattern. . . . . . . . . . 946
79. Download the application pattern zip file,
including all artifacts and the json file details.. 946
80. Update application pattern access right
details. . . . . . . . . . . . . . . 947
81. Delete a specified application pattern details. 947
82. List all artifact of a given application pattern
details. . . . . . . . . . . . . . . 947
83. Upload an artifact file details. . . . . . . 948
84. Download an artifact file details. . . . . . 949
85. Get the detail of the artifact. . . . . . . 949
86. Delete an artifact file details. . . . . . . 949
87. REST API for working with audit event
records. . . . . . . . . . . . . . 950
88. REST API for Certificates . . . . . . . 953
89. REST API for Clouds . . . . . . . . . 954
Copyright IBM Corp. 2013, 2014 xiii
90. REST API for diagnostics.zip. . . . . . 961
91. REST API for environment profiles . . . . 962
92. REST API for hypervisors . . . . . . . 967
93. REST API for IP addresses . . . . . . . 973
94. REST API for IpGroups . . . . . . . . 977
95. REST API for LogViewerMgr . . . . . . 984
96. List all the logs on a specific virtual machine 985
97. Get the content of a specific log file . . . . 986
98. Get the overall monitoring status of a given
virtual application . . . . . . . . . . 987
99. Get the virtual machine monitoring status for
a given virtual application instance . . . . 988
100. Get the middleware monitoring status for a
given virtual application instance . . . . . 989
101. Get virtual machine level monitoring metrics
of a specific virtual machine . . . . . . 989
102. Get middleware level monitoring metrics of a
specific middleware . . . . . . . . . 990
103. REST API for Networks . . . . . . . . 991
104. List all pattern types with version format "vr"
or "vmf" details . . . . . . . . . . . 994
105. Create a pattern type details . . . . . . 995
106. List detail information of one pattern type 995
107. List plugin list of one pattern type details 996
108. Accept the license agreement of a pattern
type. . . . . . . . . . . . . . . 996
109. Delete a pattern type details . . . . . . 997
110. REST API for Patterns . . . . . . . . 997
111. Retrieve all plug-ins details . . . . . . 1002
112. Create a plug-in details . . . . . . . . 1002
113. Delete a plug-in details . . . . . . . . 1003
114. Retrieve plug-in information details 1003
115. List all patterns of shared services . . . . 1004
116. Deploy a shared services pattern into a
cloud group . . . . . . . . . . . 1005
117. REST API for Storage . . . . . . . . 1006
118. REST API for versions . . . . . . . . 1009
119. REST API for VirtualApplianceInstances 1010
120. Retrieve all virtual application details 1014
121. Retrieve the virtual applications with filter 1014
122. Deploy a virtual application details 1015
123. Retrieve virtual application instance status 1016
124. Updated virtual application status details 1017
125. Delete a virtual application details 1018
126. Update application access right for the
specified user name or group name. . . . 1018
127. REST API for VirtualMachines . . . . . 1019
128. REST API for virtual machines . . . . . 1025
129. REST API for VirtualSystems . . . . . . 1030
130. List all orchestration action entries REST API
call . . . . . . . . . . . . . . 1043
131. Retrieve an orchestration action entry REST
API call . . . . . . . . . . . . . 1044
132. Add or update an entry in the orchestration
actions REST API call . . . . . . . . 1045
133. Delete an orchestration action entry REST
API call . . . . . . . . . . . . . 1046
134. Get entries for a specific virtual system
REST API call . . . . . . . . . . . 1046
135. Get list of all BPM Business Processes 1047
136. Get information about a specific BPM
Business Process . . . . . . . . . . 1048
137. Get list of all human services . . . . . . 1048
138. Get information about a specific human
service . . . . . . . . . . . . . 1049
139. Get list of all My Inbox items . . . . . . 1050
140. Get information about a specific My Inbox
item . . . . . . . . . . . . . . 1052
141. Get entries for a specific service instance
entry with a specified deployment ID REST
API call . . . . . . . . . . . . . 1054
142. Get metadata parameters of a specific
service instance REST API call . . . . . 1057
143. Post metadata parameters of a specific
service instance REST API call . . . . . 1058
144. Delete metadata parameters of a specific
service instance REST API call . . . . . 1058
145. Get virtual machine parameters of a specific
service instance REST API call . . . . . 1059
146. Post virtual machine parameters of a specific
service instance REST API call . . . . . 1059
147. Delete virtual machines parameters of a
specific service instance REST API call . . . 1060
148. List all currently running and recently
completed tasks REST API call . . . . . 1060
149. Get information about a specific task 1061
150. Get deployment parameters for a specific
service instance REST API call . . . . . 1063
151. Post deployment parameters for a specific
service instance REST API call . . . . . 1064
152. Get list of all self-service offerings . . . . 1064
153. Get entries for a specific self-service offering
REST API call . . . . . . . . . . . 1066
154. Delete a self-service offering REST API call 1068
155. Update a self-service offering REST API call 1068
156. Log files . . . . . . . . . . . . . 1077
xiv IBM SmartCloud Orchestrator 2.3: User's Guide
Preface
This publication documents how to use IBM
SmartCloud Orchestrator.
Who should read this information
This information is intended for cloud administrators who install and configure
IBM SmartCloud
Orchestrator, and for users who work with this product.
Copyright IBM Corp. 2013, 2014 xv
xvi IBM SmartCloud Orchestrator 2.3: User's Guide
Chapter 1. Overview
IBM SmartCloud Orchestrator offers many
functionalities related to managing your
cloud infrastructure.
SmartCloud 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 also facilitates
integration with customer-specific service management processes, such as those
defined in the IT infrastructure library (ITIL).
SmartCloud Orchestrator provides 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. You use the intuitive, graphical tool in SmartCloud 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.
SmartCloud 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: SmartCloud Orchestrator and SmartCloud
Orchestrator Enterprise which also includes Monitoring and Cost Management.
What is new in this release
The following enhancements were introduced in the current release.
Multitenancy
SmartCloud Orchestrator supports multi-tenant cloud environments by
introducing a 3-tier hierarchy of entities as supported in Keystone V3. In
SmartCloud Orchestrator a tenant is reflected by a domain which represents
the high-level container for users and projects. An user is a pair of
credentials that is used for authentication and authorization. A project
authorizes a set of users to a set of cloud resources. Therefore a project
owns in cloud resources like images, pattern, environment profiles, and
self-service offerings. A user and project exist within one single domain.
However, within the same domain, a user can be member of multiple
projects which authorizes the users to the resources that are granted to the
project. For more information, see Managing users, projects, and
domains on page 149.
Copyright IBM Corp. 2013, 2014 1
High availability
A new high availability solution helps to reduce the downtime of the
SmartCloud Orchestrator management stack. It includes a new component,
the System Automation Application Manager, which helps to recover from
application failures and which simplifies to control the SmartCloud
Orchestrator management stack for the operating team. For more
information, see High Availability on page 104.
LDAP authentication
In addition to the Keystone authentication, SmartCloud Orchestrator
supports authentication to an external corporate directory (such as LDAP
or Active Directory). In a multidomain configuration, SmartCloud
Orchestrator also extends the authentication capability to allow any
corporate directory details to be specified on a domain-by-domain basis.
For more information, see Configuring LDAP authentication on page 77.
PowerVM
hypervisors
SmartCloud Orchestrator supports PowerVM hypervisors managed by IBM
Systems Director VMControl
.
Importing virtual machine
You can import virtual machines that were not provisioned by SmartCloud
Orchestrator and that already exist on your hypervisors. After you import
a virtual machine, you can manage it by using the SmartCloud
Orchestrator user interface. For more information, see Importing virtual
machines on page 197.
Product architecture
IBM SmartCloud Orchestrator is a comprehensive product that integrates the
capabilities of several other IBM solutions. It adds several components and
functionalities to IBM SmartCloud Provisioning.
The main components of IBM SmartCloud Orchestrator are the process engine and
the corresponding modeling user interface, which is used to create processes. For
this purpose, SmartCloud 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.
SmartCloud Orchestrator bundles all these products and components and provides
processes that are required to implement the domain-specific functionalities. Both
the self-service user interface and the administrative user interface of SmartCloud
Provisioning are extended to reflect the new functions that are provided by
SmartCloud Orchestrator.
2 IBM SmartCloud Orchestrator 2.3: User's Guide
Cloud Marketplace
Development
tools
IaaS gateway
Storage
(Cinder)
Public
Cloud
Compute
(Nova)
Network
(Nova Networks)
Infrastructure-as-a-Service (IaaS)
Workflow
Image
management
Patterns Software stacks
Service management
- Monitor
- Backup and Restore
- Security and patch compliance
The following is a description of the role each major component plays in
SmartCloud 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.
IaaS Gateway
The IaaS Gateway provides a routing mechanism that allows two
important configurations. Firstly, it allows multi-geographical deployments
in which multiple IaaS/OpenStack instances can be deployed in multiple
sites and then federated together within SmartCloud Orchestrator.
Secondly, it allows for connectivity to public clouds such as Amazon EC2
and other public clouds compatible with OpenStack.
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.
Chapter 1. Overview 3
Image management
The Image Management component has two major functional areas. The
first one is the Image Construction and Composition Tool, which allows a
user to describe a base image and set of software stacks, and then capture
that fully deployed system into an image that can be reused. The second
one is the Virtual Image Library, which allows a user to manage images
similar to other assets, providing check-in and check-out options,
versioning, indexing and searching facilities so that corporate compliance
rules can be followed even when the images are offline.
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
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.
Cloud Marketplace
The Cloud Marketplace is a publicly accessible website where various
forms of automation can be downloaded and used within SmartCloud
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 SmartCloud Orchestrator release schedules.
Service management
This box represents optional additional management functions that are
included in SmartCloud Orchestrator Enterprise. 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 SmartCloud
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 SmartCloud
Orchestrator, but more information about them can be found on ibm.com.
4 IBM SmartCloud Orchestrator 2.3: User's Guide
Product features
Read about the main features that are available with SmartCloud Orchestrator
version 2.3.
Pattern-based cloud delivery
SmartCloud Orchestrator provides capabilities for multi-domain orchestration
(virtual system and virtual application) and a graphical orchestrator for simple
composition of cloud automation.
SmartCloud Orchestrator is a new private cloud offering based on the open
sourced OpenStack software that significantly speeds and simplifies managing an
enterprise-grade cloud. You have a core set of open source-based technologies to
build enterprise-class cloud services that can be ported across hybrid cloud
environments.
SmartCloud 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 lining up the
compute, storage and network resources with an easy-to-use graphical interface.
Designing business processes
SmartCloud Orchestrator is integrated with IBM Business Process Manager, a
workflow engine with graphical tooling. It provides a possibility to create and edit
complex workflows through simple drag and drop. you can extend the capabilities
of SmartCloud Orchestrator and design your own workflows. For more
information see Custom extensions on page 7.
Self-service user interface
Intuitive self-service user interface containing a customizable catalog of offerings is
available for users. Offerings can be group into categories which are created by
administrators to fit the needs of work environment. For more information about
self-service, see Managing self-service offerings on page 779.
OpenStack adoption
OpenStack is a cloud operating system that controls large pools of compute,
storage, and networking resources throughout a data center, all managed through a
dashboard that gives administrators control while empowering their users to
provision resources through a web interface. For more information see Overview
of OpenStack on page 8.
Image management
SmartCloud Orchestrator provides two components that simplify image
management: Image Construction and Composition Tool, and Virtual Image
Library.
You can use the Image Construction and Composition Tool to build virtual images
for deployment into cloud environments. Experts can build particular software
bundles for reuse by others. This simplifies the complexity of image creation and
Chapter 1. Overview 5
reduces errors. You can reuse and manage images and software in a cloud
environment and build and share images that are self-descriptive, customizable,
and manageable.
The Virtual Image Library component provides extended services for image
management. It supports VMware and OpenStack operational image repositories.
After you define the operational repository to Virtual Image Library and index the
images that it contains, all the information about the images is stored in the Virtual
Image Library database. You can use a local image store, called the reference
repository, to save copies of key images from any operational repository or to
replicate copies of images from the reference repository to any operational
repository. You can also import images from the Virtual Image Library file system
to the reference repository to perform image management operations on the
imported images.
For more information about managing virtual images, see Chapter 5, Managing
virtual images, on page 287.
Cost management
The IBM SmartCloud Cost Management component 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 SmartCloud Orchestrator metering is primarily driven from the OpenStack
layer to capture all virtual machine provisioning requests. For more information,
see the OpenStack Collector topic.
TOSCA support
SmartCloud 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.
Monitoring
In SmartCloud 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 783.
Reporting
SmartCloud Orchestrator provides a diverse set of reports that provide specific
data you can use for planning purposes. System usage reports are generated to
track both physical and virtual resource utilization. You can also access reports to
track the user activity in the clouds that are managed by SmartCloud Orchestrator.
For more information about reports, see Chapter 10, Reporting, on page 799.
6 IBM SmartCloud Orchestrator 2.3: User's Guide
Custom extensions
You create custom extensions to SmartCloud 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.
SmartCloud Orchestrator delivers a Business Process Manager toolkit called
SCOrchestrator_Toolkit. This toolkit provides many useful 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
SmartCloud Orchestrator. The SCOrchestrator_Toolkit also contains numerous
samples that show how to define custom extensions.
You can download more Business Process Manager toolkits from the online
marketplace. These toolkits provide more content for different areas, such as
networking or storage, and you can also use them to build SmartCloud
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 SmartCloud Orchestrator.
Related tasks:
Chapter 7, Managing orchestration workflows, on page 763
Create custom orchestration workflows in the Business Process Manager user
interface and run them in your SmartCloud Orchestrator environment.
Chapter 1. Overview 7
Overview of OpenStack
SmartCloud Orchestrator is based on OpenStack (the Grizzly 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.
SmartCloud Orchestrator uses the following components and services of
OpenStack:
v Image (codenamed Glance) that provides a catalog and repository for virtual disk
images. The virtual disk images are mostly used in the OpenStack Compute
service component.
v Compute (codenamed Nova) that provides virtual servers on demand.
v Identity (codenamed Keystone) that provides authentication and authorizations
for all OpenStack services.
v Block Storage (codenamed Cinder) that provides persistent block storage to guest
virtual machines.
SmartCloud Orchestrator does not use the Object Store (codenamed Swift) service
component, nor the Network (codenamed Neutron) service component for network
management, nor the Dashboard (codenamed Horizon) service component for the
web-based user interface.
SmartCloud Orchestrator uses the nova-network of OpenStack as a networking
option (see networking with nova-network).
To configure and administer SmartCloud Orchestrator, you must learn to use the
OpenStack command-line interface. 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.
8 IBM SmartCloud Orchestrator 2.3: User's Guide
Chapter 2. Installing
Follow this procedure to install SmartCloud 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 SmartCloud Orchestrator so that you can
properly plan your installation.
The main components of SmartCloud Orchestrator installation topology are the
Central Server and the Region Server, The Central Server represents the core
SmartCloud Orchestrator management components. The Region Server represents
the component that is used to communicate with a specific hypervisor
management infrastructure (KVM, VMware, or PowerVM).
The Central Server and the Region Server must run on KVM or VMware virtual
machines. Central Server is a set of components that are grouped into four virtual
machines. An additional virtual machine is required if you want to use the high
availability solution. For more information, see High Availability on page 104.
Region Server is set up on a single virtual machine. Additional Region Servers can
be added to enable a multiple-region environment. If you are using a KVM region,
a KVM Compute Server is required and it must be installed on a physical machine.
The key components of the installation are:
Central Server
Is installed on the following virtual machines:
Central Server 1
DB2 plus tooling (yum, chef) for installing components on the other
central servers
Central Server 2
IaaS Gateway, Public Cloud Gateway, Keystone, and Virtual Image
Library
Central Server 3
Workload Deployer and SmartCloud UI
Central Server 4
Business Process Manager
Region Server
Is installed on a single virtual machine:
Region Server -1
The following key components are installed:
v OpenStack
v DB2 (optional, it is installed only if you want this region server
use its own DB2)
Copyright IBM Corp. 2013, 2014 9
v SmartCloud Entry driver (optional, it is installed only on
VMware and Power regions)
v yum
v chef
v PXE (optional, it is installed only for KVM region servers so that
additional KVM compute nodes can be installed)
KVM Compute Server
Only for KVM region. This server must be associated with a KVM Region
Server and have VM work load running on it. The KVM compute server
must be installed on bare metal.
The central servers must be located in the same network, while the region server
can be distributed, as long as it has network connectivity to the central servers
Typically, a customers corporate DNS can be used as SmartCloud Orchestrator
upstream DNS. Central server has a DNS, while each region server also has one.
This means that they are connected hierarchically. As a result, you can delegate a
subdomain to SmartCloud Orchestrator when the installation is complete.
Meanwhile, it is also possible that SmartCloud Orchestrator fully relies on
customers corporate DNS without deploying any embedded DNS, if all
prerequisites are satisfied.
For more information about the SmartCloud Orchestrator topology, you can refer
to the SmartCloud Orchestrator product wiki.
Installation scenarios
Before you proceed with the installation of SmartCloud Orchestrator, you must
choose one of the installation scenarios.
SmartCloud Orchestrator 2.3 supports the following basic installation scenarios:
v Manage vCenter
v Manage VMControl
v Scale-out KVM
The following table presents a brief summary of these scenarios:
Table 1. Summary of SmartCloud Orchestrator installation scenarios
Scenario Description
Manage-from
environment
Manage-to
hypervisor
Distribution of
manage-to and
manage-from
Manage vCenter Installing all
components on
several virtual
machines. Then
connecting to
one or more
existing vCenter
instances.
KVM or
VMware virtual
machines
One or more
vCenter-
managed ESXi
nodes
v Manage-from
not
distributed
v Manage-to
distributed via
vCenter
mechanisms
10 IBM SmartCloud Orchestrator 2.3: User's Guide
Table 1. Summary of SmartCloud Orchestrator installation scenarios (continued)
Scenario Description
Manage-from
environment
Manage-to
hypervisor
Distribution of
manage-to and
manage-from
Manage
VMControl
Installing all
components on
several virtual
machines. Then
connecting to the
existing
VMControl
instance.
KVM or
VMware virtual
machines
One or more
VMControl-
managed Power
systems or Flex
Chasis with
Power nodes
v Manage-from
not
distributed
v Manage-to
distributed via
VMControl
server-pool
mechanisms
Scale-out KVM Installing all
components on
several virtual
machines. Then
adding
manage-to KVM
hypervisors to
increase capacity
as user demand
grows.
KVM or
VMware virtual
machines
One or more
KVM nodes
v Manage-from
not
distributed
v Manage-to
distributed via
additional
KVM nodes
Manage vCenter scenario
Plan for this installation scenario if you want to connect your SmartCloud
Orchestrator environment to already existing vCenter instances.
You can connect the manage-from components to one or more existing vCenter
instances so that the existing vCenter/ESXi infrastructure can be used as a
manage-to environment. The graphic presents the default topology for this
scenario: see Figure 1 at https://www.ibm.com/developerworks/community/
wikis/home?lang=en#!/wiki/IBM%20SmartCloud%20Orchestrator/page/IBM
%20SmartCloud%20Orchestrator%202.3%20Network%20Topology
Management Network
In the default topology, the management network is used to set up
connectivity with vCenters and Virtual Image Library proxies as well as to
permit IBM Workload Deployer, Business Process Manager, and virtual
machine communication. It is also used to grant user access to the
SmartCloud Orchestrator user interface. Upon initial setup, you can change
the SmartCloud Orchestrator configuration to have physical and logical
segregation between this traffic.
VMware internal management network
This network allows for communication between vCenter and ESX. Virtual
Image Library proxy must be located in this network because it requires
network access to ESX servers.
Important: If a datastore cluster is configured in vCenter, then DRS must
be enabled as well. Deployments fail without DRS enabled when
provisioning to a datastore cluster.
To enable DRS, check Turn on Storage DRS under General, when you
create or edit a Datastore Cluster in vCenter.
Chapter 2. Installing 11
Manage VMControl scenario
Plan for this installation scenario if you want to connect your SmartCloud
Orchestrator environment to already existing VMControl instances.
The graphic presents the default topology for this scenario: see Figure 2 at
https://www.ibm.com/developerworks/community/wikis/home?lang=en#!/
wiki/IBM%20SmartCloud%20Orchestrator/page/IBM%20SmartCloud
%20Orchestrator%202.3%20Network%20Topology
Scale-out KVM scenario
Plan for this installation scenario if you want to add manage-to KVM nodes to
increase the capacity of your SmartCloud Orchestrator environment.
You can connect the manage-from components to additional manage-to KVM
compute nodes as user demand requires additional capacity. The graphic presents
the default topology for this scenario: see Figure 3 at https://www.ibm.com/
developerworks/community/wikis/home?lang=en#!/wiki/IBM%20SmartCloud
%20Orchestrator/page/IBM%20SmartCloud%20Orchestrator%202.3%20Network
%20Topology
SmartCloud Orchestrator Enterprise installation
To give you more control over your cloud environment, SmartCloud Orchestrator
Enterprise bundles three additional products: Jazz
for Service Management, IBM
Tivoli
Monitoring, and IBM SmartCloud Cost Management.
The products are responsible for the following additional functionalities:
v Jazz for Service Management - reporting
v IBM Tivoli Monitoring - monitoring
v IBM SmartCloud Cost Management - metering and billing
Installation flow
The first part of the SmartCloud Orchestrator Enterprise installation is exactly the
same as of the base version. Then you need to install the additional products on
separate machines:
1. Refer to the installation procedure in the Chapter 2, Installing, on page 9
section to install SmartCloud Orchestrator and its services.
2. Install Jazz for Service Management. For the instructions, refer to Installing
Jazz for Service Management and Tivoli Common Reporting on page 802.
3. Install IBM Tivoli Monitoring. For the instructions, refer to Installing IBM
Tivoli Monitoring on page 784.
4. Install IBM SmartCloud Cost Management. For the instructions, refer to Quick
start guide for metering and billing on page 87.
12 IBM SmartCloud Orchestrator 2.3: User's Guide
Hardware prerequisites
Review the hardware prerequisites to make sure that your environment meets
them.
Manage-from requirements
The SmartCloud Orchestrator management components need to be installed on the
following VMware or KVM virtual machines that must run Red Hat Enterprise
Linux 6.3 or 6.4 :
v Four virtual machines for installing the Central Server management components.
They are referred as Central Server 1, Central Server 2, Central Server 3, and
Central Server 4.
v One optional virtual machine for High Availability solution. It is referred as
Central Server 5. For more information, see High Availability on page 104.
v One virtual machine for each Region Server. The first Region Server is referred
as Region Server 1.
For more information on creating the virtual machines on VMware or KVM, see
Setting up virtual machines to install Central Server and Region Server on page
49.
Table 2. The minimum Manage-from requirements
Machine
Role
Processor
(vCPU)
Memory
(Free
value, GB)
Overall
Volume
Requirements
(GB)
Free Space:
"/"
Free Space:
"/home"
Free Space:
Other
Partitions
Central
Server 1
2 6 100 75 19
Central
Server 2
2 8 141 55 30 /opt 10
/tmp 40
Central
Server 3
2 4 80 70 4
Central
Server 4
2 6 50 40 4
Central
Server 5
(optional)
2 4 20 20 N/A
Region
Server
2 4 76 40 30
Disk planning considerations:
v The specified hard disk space is the minimum free space required on the machine before
the SmartCloud Orchestrator installation. Be sure that there is sufficient space for the
required partitions.
For Central Server 1 and the Region server, additional disk size (about 14 GB) is
required considering where the SmartCloud Orchestrator package locates.
For Central Server 1 and Central Server 2, additional space on /home may be required
over time based on database and image management practices. Monitoring is
recommended.
v You must attach, without mounting it, an additional raw disk of 5 GB to Central Server
2. You need the disk label of this disk during the installation of the Central Server.
v For all Servers, /tmp needs read, write, and execute permissions.
Chapter 2. Installing 13
Capacity planning considerations:
v The minimum and recommended levels are a function of the number of users,
managed virtual machines, and managed images. For the minimum values, the
expectation is a small cloud on the order of 5 users, 100 managed virtual
machines, and 10 managed images. The system allocations should progress to
the recommended values as these values are increased. Storage requirements
might increase based on image management approaches. Standard volume
management is recommended.
Manage-to requirements
KVM compute nodes:
You can add Red Hat Enterprise Linux 6.3 or 6.4 nodes to the SmartCloud
Orchestrator environment. The compute node must be a physical machine, and
will be deployed from repositories on the manage-from server. All KVM compute
nodes must use the same interface to connect to the Region Server, for example,
eth0, eth1, or eth2. The minimum configuration for KVM servers is as follows:
Table 3. KVM Compute Nodes
Machine Role
Number of
NICs Processor Memory
Hard Dish
Space
KVM
Hypervisor
1 VT enabled At least 20 GB At least 200 GB
VMware compute nodes:
The VMware vCenter managed infrastructures might be connected to the
SmartCloud Orchestrator environment. The physical minimum configuration for
the ESXi servers is as follows:
Table 4. VMware Compute Nodes
Machine role
Number of
NICs Processor Memory
Hard Disk
Space
ESXi Hypervisor 1 VT enabled At least 20 GB At least 200 GB
Power compute nodes:
VMControl 2.4.3 managed infrastructures might be connected to the SmartCloud
Orchestrator environment. The minimum configuration for Power systems
managed by VMControl is as follows:
14 IBM SmartCloud Orchestrator 2.3: User's Guide
Table 5. Power Compute Nodes
Machine Role
Number of
NICs Processor Memory
Hard Disk
Space
Power
Hypervisor
At least 1 for
single VIOS, at
least 2 for dual
VIOS
Any # of
Power5, Power6
or Power7
At least 16 GB,
additional 8 GB
are required if
hosting
Director/
VMControl
At least 200 GB
are highly
recommended to
use SAN
infrastructure
(V5000, V7000 or
SVC) for Storage
Copy Services
support.
Network requirements
SmartCloud Orchestrator uses MTU standards in all network devices, that is MTU
= 1500. For given networks with different MTU size, make sure that the MTU of all
management servers has the same value, otherwise packages might be too big and
cannot be transferred.
Software prerequisites
Review the software prerequisites for your environment.
Required packages
SmartCloud Orchestrator runs on top of Red Hat Enterprise Linux 6.3 or 6.4 64-bit.
The following packages are required:
v RHEL6.3*.iso or RHEL6.4*.iso
Note: Before installing SmartCloud Orchestrator, prepare an ISO file of Red Hat
Enterprise Linux 6.3 or 6.4 x86_64 and place it on Central Server 1 and on the
Region Servers, for example, in the /opt directory.
Note: You must use the base Red Hat Enterprise Linux 6.3 or 6.4 image when
installing SmartCloud Orchestrator. You cannot use an image that contains any
Red Hat Enterprise Linux patch. After installing SmartCloud Orchestrator, you
can install Red Hat Enterprise Linux patches, if needed.
v rubygems-*.el6.noarch.rpm (<= 1.3.7-1)
v libguestfs-winsupport-*.el6.x86_64.rpm (<= 1.0-7)
Make sure that the rubygems-*.el6.noarch.rpm (<= 1.3.7-1) and
libguestfs-winsupport-*.el6.x86_64.rpm (<= 1.0-7)RPM packages are copied into
the /data/repos/scp directory on Central Server 1 and on the Region Servers.
You can download the libguestfs package from https://rhn.redhat.com/network/
software/packages/name_overview.pxt?package_name=libguestfs-winsupport
&archIdList=&archLabelList=&search_subscribed_channels=yes using your Red
Hat login credentials.
Note: To download the libguestfs package, you must have the Red Hat
Enterprise Virtualization license.
You can download the rubygems package from https://rhn.redhat.com/network/
software/packages/name_overview.pxt%3Fpackage_name=rubygems
Chapter 2. Installing 15
%26archIdList=%26archLabelList=%26search_subscribed_channels=yes.
Supported operating systems
This topic describes the operating systems that are supported in a SmartCloud
Orchestrator environment.
Manage-from requirements
SmartCloud Orchestrator services can be installed on KVM or VMware virtual
machines.
The following table describes the host and guest operating systems supported for
installing SmartCloud Orchestrator.
Table 6. Host and guest operating systems supported by the standard installation
Hypervisor Host operating system Guest operating system Reference
KVM Red Hat Enterprise Linux 6.3,
6.4 x86_64
Red Hat Enterprise Linux 6.3,
6.4 x86_64
Managing guests with the
Virtual Machine Manager
(virt-manager)
VMware VMware vCenter Server 4.1 u1,
5.0, 5.1
VMware vSphere 4.1 u1, 5.0, 5.1
Red Hat Enterprise Linux 6.3,
6.4 x86_64
vSphere Virtual Machine
Administration
Manage-to requirements
The following table describes the host and guest operating systems supported by
each type of hypervisor in a SmartCloud Orchestrator environment.
Table 7. 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.3, 6.4
x86_64
SLES 11 SP1 and SP2, 32-bit and 64-bit
RHEL 5.x, RHEL 6.1, 6.2, 6.3, and 6.4, 32-bit and 64-bit
CentOS 6.3 and 6.4, 64-bit
Windows 2008 R2 64-bit, Windows 7 64-bit, Windows
Server 2012 64-bit
VMware VMware vCenter Server 4.1 u1, 5.0,
5.1
VMware vSphere 4.1 u1, 5.0, 5.1
SLES 11 SP1 and SP2, 32-bit and 64-bit
RHEL 5.x, RHEL 6.1, 6.2, 6.3, and 6.4, 32-bit and 64-bit
CentOS 6.3 and 6.4, 64-bit
Windows 2008 R2 64-bit, Windows 7 64-bit, Windows
Server 2012 64-bit
Power IBM Systems Director 6.3.3.1 and
VMControl 2.4.3.1
VIOS 2.2.2.2 on the Power systems
NIM server is required for non-SCS
environments or for importing
mksysb images
AIX 6.x and AIX 7.x
RHEL 6.3, 6.4 for Power (ppc64)
SLES 11 for Power (ppc64)
Activation Engine is required for these images.
Note:
v The image imported or created in VMControl must have the VMControl
Activation Engine. For information, see Installing the VMControl activation
engine on AIX and Linux.
v For more information about image management, see Image management on
page 488.
16 IBM SmartCloud Orchestrator 2.3: User's Guide
Preparing the central server and the region server
To start the installation process, you must prepare four Central Server virtual
machines and at least one Region Server virtual machine.
Before you begin
In this topic, the Central Server virtual machines are called Central Server 1,
Central Server 2, Central Server 3, and Central Server 4. The fist Region Server
virtual machine is called Region Server 1.
You can use VMware or KVM virtual machines to run the Central Server and
Region Server services. To manage KVM virtual machines, it is recommended to
use the virt-manager application. To manage VMware virtual machines, it is
recommended to use the VMware vCenter application. If you want to use the high
availability solution in your SmartCloud Orchestrator environment, use VMware
virtual machines to run your SmartCloud Orchestrator environment. For more
information about high availability, see High Availability on page 104.
If the virtual machines are already available, run the following procedure. If you
need to create the virtual machines, follow the procedure described in Setting up
virtual machines to install Central Server and Region Server on page 49.
About this task
During this task, you repeat the described procedure for each of the Central Server
and Region Server virtual machines to prepare them for the installation process.
Note: For a VMware region, the Region Server network configuration must be
such that the Region Server can contact the ESXi hosts using the host name or IP
address that has been used to register those servers with the vCenter. Even if the
ESXi hosts have multiple IP addresses and one or more of them can be reached
from the Region Server, the only way for the vilProxy service (Virtual Image
Library service, for details refer to Configuring Virtual Image Library server and
remote proxy components on page 303) to index images on those hosts is to
connect to them using exactly the same IP addresses (or host names) that are
displayed in the vCenter.
Note: To exploit best performance of Virtual Image Library and Virtual Image
Library proxy, when they are installed on virtual machines on VMware 5.1, the
virtual machines (Central Server 2 and Region Server) must have nested
virtualization enabled. It is not required if the system is not a virtual machine but
bare metal system. For information about enabling nested virtualization, see
http://pubs.vmware.com/vsphere-51/topic/com.vmware.vsphere.vm_admin.doc/
GUID-2A98801C-68E8-47AF-99ED-00C63E4857F6.html.
Note: If the manage to VMware environment is a cluster environment, the vSphere
DRS must be enabled in the vCenter to which the SmartCloud Entry will connect,
and make sure that the automation level is not Manual (Fully or Partially
Automated is OK). This is a prerequisite before adding a VMware vCenter in a
SmartCloud Orchestrator environment, otherwise you have to delete it after you
enable the DRS and recreate it again. You can find more information regarding the
vSphere DRS enablement at http://pubs.vmware.com/vsphere-51/index.jsp?topic=
%2Fcom.vmware.vsphere.resmgmt.doc%2FGUID-8ACF3502-5314-469F-8CC9-
4A9BD5925BC2.html
Chapter 2. Installing 17
Procedure
1. Make sure that the virtual machines meet the hardware prerequisites described
in Hardware prerequisites on page 13.
2. Install Red Hat Enterprise Linux V6.3 or V6.4 64-bit on the virtual machines.
a. Make sure that all Central Server virtual machines and Region Server
virtual machines have the same kernel version installed and is consistent
with the ISO file you prepared.
b. Make sure that all Central Server virtual machines have the same root user
password.
c. When installing the Red Hat Enterprise Linux V6.3 or V6.4 64-bit operating
system for the Central or Region servers, the Basic Server package group is
sufficient, because the Central and Region servers deploy script installs the
SmartCloud Orchestrator required packages from the corresponding Red
Hat ISO files.
Note: Make sure that the RHEL installation includes the bind-utils RPM.
3. Edit the /etc/selinux/config file and set the parameter SELINUX=disabled.
Reboot the computer.
4. Make sure the SSHD is enabled on the virtual machine.
5. Make sure that the network is configured for the virtual machine (static IP is
recommended):
v All Central Server virtual machines must be in the same network.
v All Central Server virtual machines and the Region Server virtual machines
must have network connectivity to Central Server 1.
v Make sure that /etc/hosts on each Central Server or Region Server virtual
machine has no records associated with the IP addresses of any Central
Server or Region Server Virtual machine.
6. Choose a Domain Name Server (DNS) configuration option. For each option,
additional steps might be needed.
Option A:
SmartCloud Orchestrator uses a built-in DNS (stand-alone environment). In this
case, the installation process performs a hierarchical DNS deployment on
Central Server 1 and each Region Server. Each Region Server is a subdomain of
Central Server 1 and each Region Server forwards DNS requests to Central
Server 1.
Additional setup steps needed: none.
The following graphic shows the topology for a built-in DNS stand-alone
environment.
Option B:
18 IBM SmartCloud Orchestrator 2.3: User's Guide
SmartCloud Orchestrator uses a built-in DNS, but the corporate DNS is the
parent DNS. In this case, the installation process performs a hierarchical DNS
deployment on Central Server 1 and each Region Server. The corporate DNS is
used as an upstream forwarder of Central Server 1. Central Server 1 forwards
DNS requests to the upstream DNS while each Region Server forwards DNS
requests to Central Server 1.
Additional setup steps needed:
The required steps are described here using an example where the corporate
DNS uses named with IP 198.51.100.50 and the Search Domain is company.com:
a. Ensure each Central Server and Region Server is not included in the reverse
lookup of the corporate DNS. Check file /var/named/reverse-lookup.db and
remove any entries related with the Central Servers and Region Servers.
b. Edit the /etc/resolv.conf file on each Central Server and Region Server
and add a nameserver entry that points to the corporate DNS, as shown in
the following example:
cat /etc/resolv.conf
nameserver 198.51.100.50
c. After installation finishes, modify the corporate DNS zone file to delegate
the subdomain to central-server-1.
The following graphic shows the topology for a built-in DNS environment
where the corporate DNS is the parent DNS.
Option C:
SmartCloud Orchestrator uses the corporate DNS and no built-in DNS. In this
case, the installation process will not deploy any DNS server.
Additional setup steps needed:
The required steps are illustrated here using an example, where the corporate
DNS IP is 198.51.100.50 and the Search Domain is company.com:
a. Register new DNS entries for each Central Server and Region Server into
the corporate DNS, and ensure that both forward lookup and reverse
lookup work for all domain users, for example:
Forward lookup: Add the following entries to a forward file named
/var/named/forward-lookup.db:
central-server-1 A 198.51.100.51
central-server-2 A 198.51.100.52
central-server-3 A 198.51.100.53
central-server-4 A 198.51.100.54
region-server-1 A 198.51.100.55
region-server-2 A 198.51.100.56
Chapter 2. Installing 19
Reverse lookup: Add the following entries to a reverse file named
/var/named/reverse-lookup.db:
$ORIGIN 100.51.198.in-addr.arpa.
51 PTR central-server-1.cloud.company.com.
52 PTR central-server-2.cloud.company.com.
53 PTR central-server-3.cloud.company.com.
54 PTR central-server-4.cloud.company.com.
55 PTR region-server-1.cloud.company.com.
56 PTR region-server-2.cloud.company.com.
...
b. Register new DNS entries for provisioned virtual machines into the
corporate DNS. The corresponding IP range must be specified in the
region-server.conf configuration file when performing the procedure to
install the Region Server. See Installing the region server on page 26.
Forward lookup: Add the following entries to a forward file named
/var/named/forward-lookup.db:
SC-198-51-100-80 A 198.51.100.80
SC-198-51-100-81 A 198.51.100.81
SC-198-51-100-82 A 198.51.100.82
SC-198-51-100-83 A 198.51.100.83
SC-198-51-100-84 A 198.51.100.84
SC-198-51-100-85 A 198.51.100.85
SC-198-51-100-86 A 198.51.100.86
SC-198-51-100-87 A 198.51.100.87
SC-198-51-100-88 A 198.51.100.88
SC-198-51-100-89 A 198.51.100.89
SC-198-51-100-90 A 198.51.100.90
Reverse lookup: Add the following entries to a reverse file named
/var/named/reverse-lookup.db:
80 PTR SC-198-51-100-80.company.com.
81 PTR SC-198-51-100-81.company.com.
82 PTR SC-198-51-100-82.company.com.
83 PTR SC-198-51-100-83.company.com.
84 PTR SC-198-51-100-84.company.com.
85 PTR SC-198-51-100-85.company.com.
86 PTR SC-198-51-100-86.company.com.
87 PTR SC-198-51-100-87.company.com.
88 PTR SC-198-51-100-88.company.com.
89 PTR SC-198-51-100-89.company.com.
90 PTR SC-198-51-100-90.company.com.
c. Edit the /etc/resolv.conf file on each Central Server and Region Server
and add a nameserver entry that points to the corporate DNS, as shown in
the following example:
cat /etc/resolv.conf
nameserver 198.51.100.50
d. To verify that the DNS resolution is correctly configured, run the following
commands for all Central Servers and Region Servers:
1) host <IP_address>
This command must return the Fully Qualified Domain Name (FQDN)
of the server.
2) hostname --fqdn
This command must return the same FQDN as in the previous
command.
3) hostname
This command must return the first part of the FQDN.
The following graphic shows the topology for using the corporate DNS and no
built-in DNS.
20 IBM SmartCloud Orchestrator 2.3: User's Guide
7. Single Sign On is automatically configured and enabled by the SmartCloud
Orchestrator deployment. Make sure that the resolv.conf and DNS configuration
on the machine is correctly updated to be able to resolve each central and
region server's fully-qualified domain name.
a. If you choose option A in previous step, the installer uses "dns_suffix"
which must be specified in the configuration file central-server.conf when
performing the procedure to install the central server to generate the Single
Sign On domain. See Installing the central server on page 23. This option
means that for client nodes where the web browser is running to connect to
the SmartCloud Orchestrator UI, the configuration file must have the name
server pointing to Central Server 1.
b. If you choose option B or option C in the previous step, make sure that the
client nodes where the web browser is running on to connect to SmartCloud
Orchestrator UI has the name server pointing to the corporate DNS.
8. Optional: If the central and region servers are running on virtual machines, a
snapshot is highly recommended to back up a copy of the virtual machine disk
file of each central and region server before you start the installation procedure.
Snapshots provide a change log for the virtual disk and they are used to restore
a virtual machine to a specific status, so that, when an installation fails, all the
central and region servers can be reverted to the fresh status.
What to do next
When all systems and configurations are ready, proceed as documented in
Installing the central server on page 23.
Preparing the installation media
Before installation, prepare the installation media.
Preparing the installation based on electronic download
packages
To install SmartCloud Orchestrator from electronic download packages, you must
first prepare the images. Note: These images must be copied to Central Server 1
and to each Region server that is being installed.
Procedure
1. Download the packages from the Passport Advantage
website:
For SmartCloud Orchestrator, download the following packages:
CIQ3VML.tar
CIQ6EML.tar
CIQ6FML.tar
CIQ6GML.tar
Chapter 2. Installing 21
For SmartCloud Orchestrator Enterprise, download the following packages:
CIQ3XML.tar
CIQ6EML.tar
CIQ6FML.tar
CIQ6GML.tar
Note: The packages CIQ6EML.tar, CIQ6FML.tar and CIQ6GML.tar are used for
both types of installation.
2. Use the following command to extract the content of the TAR files into the
installation directory of your choice. In this example of installation, the
directory is called /install_images:
tar xvf <tar file>
Replace <tar file> with respective file names from the list.
Important: Extract all TAR files into the same installation directory.
3. Central Server only: Download the tar files for the following Business Process
Manager part numbers:
CIL73ML
CIL74ML
CIL75ML
Copy the following files to the install_images/bpm 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
Do not extract the contents of the tar.gz files.
Preparing the installation based on DVD images
To install SmartCloud Orchestrator from DVDs, you must first prepare the images.
Note: These images must be copied to Central Server 1 and to each Region server
that is being installed.
Procedure
1. Copy the following TAR files from the DVDs to one directory:
For SmartCloud Orchestrator V2.3, copy the files from the following DVDs:
IBM SmartCloud Orchestrator V2.3.0
IBM SmartCloud Provisioning V2.3.0 Base 1 of 3 for Linux RHEL
IBM SmartCloud Provisioning V2.3.0 Base 2 of 3 for Linux RHEL
IBM SmartCloud Provisioning V2.3.0 Base 3 of 3 for Linux RHEL
For SmartCloud Orchestrator V2.3, Fix Pack 1, copy the files from the
following DVDs:
IBM SmartCloud Orchestrator V2.3.0.1 for Multiplatform
IBM SmartCloud Provisioning V2.3.0.1 Base 1 of 4 for Linux RHEL
IBM SmartCloud Provisioning V2.3.0.1 Base 2 of 4 for Linux RHEL
IBM SmartCloud Provisioning V2.3.0.1 Base 3 of 4 for Linux RHEL
IBM SmartCloud Provisioning V2.3.0.1 Base 4 of 4 for Linux RHEL
For SmartCloud Orchestrator Enterprise V2.3, copy the files from the
following DVDs:
IBM SmartCloud Orchestrator Enterprise V2.3.0
IBM SmartCloud Provisioning V2.3.0 Base 1 of 3 for Linux RHEL
IBM SmartCloud Provisioning V2.3.0 Base 2 of 3 for Linux RHEL
IBM SmartCloud Provisioning V2.3.0 Base 3 of 3 for Linux RHEL
22 IBM SmartCloud Orchestrator 2.3: User's Guide
2. Use the following command to extract the content of the TAR files into the
installation directory of your choice. In this example of installation, the
directory is called /install_images:
tar xvf <tar file>
Replace <tar file> with respective file names from the list.
Important: Extract all TAR files into the same installation directory.
3. Central Server only: For Business Process Manager, copy the files from the
following DVDs into the install_images/bpm directory:
IBM Business Process Manager Standard V8.5 for Linux 32bit/64bit (1 of 3)
[BPM_Std_V85_Linux_x86_1_of_3.tar.gz]
IBM Business Process Manager Standard V8.5 for Linux 32bit/64bit (2 of 3)
[BPM_Std_V85_Linux_x86_2_of_3.tar.gz]
IBM Business Process Manager Standard V8.5 for Linux 32bit/64bit (3 of 3)
[BPM_Std_V85_Linux_x86_3_of_3.tar.gz]
Do not extract the contents of the tar.gz files.
Installing the central server
The central server represents the set of machines where the core SmartCloud
Orchestrator components are running, and are grouped into four virtual machines.
Before you begin
Before you start this installation procedure, make sure that you have completed the
preparation steps required for each of the central server virtual systems. For more
information, see Preparing the central server and the region server on page 17.
When you start the installation of the Central Server 1, the virtual machines for all
the other Central Servers must be up and running and must be accessible.
About this task
The following virtual machines are components of the central server:
Central Server 1
DB2 plus tooling (yum, chef) for installing components on the other central
servers
Central Server 2
IaaS Gateway, Public Cloud Gateway, Keystone, and Virtual Image Library
Central Server 3
Workload Deployer and SmartCloud UI
Central Server 4
Business Process Manager
Procedure
1. Log on to Central Server 1.
2. Make sure that the software on Central Server 1 meets the software
prerequisites. See Software prerequisites on page 15.
3. Prepare the installation media on Central Server 1. See Preparing the
installation media on page 21.
Chapter 2. Installing 23
4. If you are a SmartCloud Orchestrator Enterprise customer, copy swtag to
SmartCloud_Orchestrator-2.3.0.swtag by executing the following command:
cp /install_images/iwd/SmartCloud_Orchestrator_Enterprise-2.3.0.swtag /install_images/iwd/SmartCloud_Orchestrator-2.3.0.swtag
5. Edit the file central-server.cfg in folder /install_images/installer.
6. Customize the file so that it reflects your environment setup. The table below
describes the required parameters that you must customize:
Table 8. Compulsory attributes
Configuration Parameter = default value Description
iso_location=/opt/RHEL6.3-20120613.2-
Server-x86_64-DVD1.iso
Location of the Red Hat Enterprise Linux
Server 6 DVD ISO file
dns_suffix=example.com How to define dns_suffix:
v If you choose to use SmartCloud
Orchestrator built-in DNS, define a
domain name for your cloud.
v If you choose to use SmartCloud
Orchestrator built-in DNS with corporate
DNS as the parent DNS, define a sub
domain name for your cloud. For
example, if your company domain name
is company.com, then the sub domain is
cloud.company.com.
v If you choose to use corporate DNS with
no SmartCloud Orchestrator built-in DNS,
make sure that dns_suffix="", and make
sure that the entries which were
configured in step 6 of Preparing the
central server and the region server on
page 17 are correctly resolved on each
central server and region server.
management_network_device=eth0 This option works with the
central_server_ips of the following row,
which means that central_server_ips must be
the same network of this NIC's IP address
central_server_ips=
10.10.10.10,10.10.10.11,10.10.10.12
The IP addresses for Central Server 2,
Central Server 3 and Central Server 4 must
be in the same network with Central Server
1. The FQDN is used for single sign on if
these IP addresses can be resolved from
upstream DNS, so /etc/resolv.conf
hbase-disk=/dev/sdb Specify the name of the 5GB disk you
attached to central server 2 machine as
described in the hardware requirement for
central server 2. The disk is used by Virtual
Image Library to deploy HBase.
central_server_domain_names=central-
server-1,central-server-2,central-
server-3,central-server-4
The hostname of the central servers used to
register into SmartCloud Orchestrator DNS.
Used for Single Sign On only when
central_server_ips cannot be resolved.
7. To install Central Server, run the following command on Central Server 1 (this
command will install also the other central servers):
/install_images/installer/deploy_central_server.sh [-h] [-a]
[-p <os-root-password>] [-P <smartcloud-password>]
where:
24 IBM SmartCloud Orchestrator 2.3: User's Guide
-h Shows usage.
-a Accepts license by default.
-p <os-root-password>
Defines the password of the root user on all central servers. Assign the
same password to all your central servers. This parameter is optional
and, if not indicated it, the command prompts you for it.
-P <smartcloud-password>
Defines the password of the SmartCloud user admin. This parameter is
optional and, if not indicated it, the command prompts you for it.
Important: The password can only contain 0-9,a-z,A-Z, special
characters (for example: -/* @ # ) are not allowed.
Note: It is not supported to rerun deploy_central_server.sh in case of
any installation failures. The Central Server images must either be
recreated or reverted to the previous snapshot.
Note: The install process uses SmartCloud user admin as the OpenStack
administrative user and the OpenStack service users. It is used in the internal
communication between different subcomponents, and used to log into
SmartCloud services, Workload Deployer, and Virtual Image Library. A domain
with domain name Default is generated automatically, and is used to log into
SmartCloud services, Workload Deployer, and Virtual Image Library.
Note: The Central Server IP addresses can only be configured before running
deploy_central_server.sh. Otherwise, the reconfiguration of Central Server IP
addresses will have a high risk to break the existing SmartCloud Orchestrator
environment.
8. Important: If you are a SmartCloud Orchestrator Enterprise customer, login to
Central Server 3 and rename the SmartCloud_Orchestrator-2.3.0.swtag file by
executing the following command:
cd /opt/ibm/SmartCloud_Orchestrator/properties/version/
mv SmartCloud_Orchestrator-2.3.0.swtag SmartCloud_Orchestrator_Enterprise-2.3.0.swtag
Results
You can find the installation logs in /var/log/smartcloud/.
What to do next
After all central servers are successfully installed, add the region server to the
environment. See Installing the region server on page 26. If you want to reboot
the central servers before you install the region server, refer to Shutting down or
starting Central Servers and Region Servers on page 62.
Chapter 2. Installing 25
Installing the region server
A region server represents the component needed to communicate with a specific
hypervisor management infrastructure, including KVM, VMware, or Power.
Before you begin
A SmartCloud Orchestrator environment requires at least one region server
installed, however, additional region servers can be successively installed and can
point to any of the supported hypervisor management infrastructures.
The components representing a region server are installed on a single virtual
machine and are:
v OpenStack
v DB2 (optional, it is installed only if you want this region server use its own
DB2)
v SmartCloud Entry driver (optional, it is installed only on VMware and Power
regions)
v yum
v chef
v PXE (optional, it is installed only for KVM region servers so that additional
KVM compute nodes can be installed)
Before you start this installation procedure, complete the following steps:
1. Complete the preparation steps required for the region server virtual machine.
See Preparing the central server and the region server on page 17.
2. The DB2 in the region server is used to store the OpenStack data. You can have
a single DB2 shared between the central servers and the region servers. It is
suggested to have a separate DB2 for improving the performance especially in
production environments or in the environments where the region servers are
geographically dispersed.
Decide whether this region server uses its own DB2 or shares the central server
DB2. If you want this region to use its own DB2, skip this step and proceed to
the next section. If you want this region server to share the same DB2 used by
the central server, an authorized central server DB2 administrator must run a
command provided by the installation to prepare the DB2 to be used by this
region sever:
a. Log on to Central Server-1 and locate the /install_images/installer/
directory.
b. Run the command:
/install_images/installer/deploy create-region-db --region_name <region-name>
where:
--region_name <region-name>
Defines the name representing this region and that you later use as
input for the region server installation procedure. This parameter is
required.
26 IBM SmartCloud Orchestrator 2.3: User's Guide
About this task
The installation procedure can be repeated as is for each additional region server to
install. The procedure refers to the region server virtual machine as Region
server-n.
Procedure
1. Log on to the Region Server-n machine.
2. Make sure that the software on Region Server meets the software prerequisites
described in Software prerequisites on page 15.
3. Prepare the installation media on Region Server-n. See Preparing the
installation media on page 21.
4. Edit the file region-server.cfg in folder /install_images/installer.
Customize the file to reflect your environment setup. The following table
describes the required parameters that you must customize:
Table 9. Compulsory configurations
Configuration Parameter = default value Description
iso_location=/opt/RHEL6.3-20120613.2-
Server-x86_64-DVD1.iso
The location of the Red Hat Enterprise
Linux Server 6 DVD ISO file.
management_network_device=eth0 The management NIC device name. If your
machine has multiple NICs, the parameter
specifies which NIC is used to as the
manage from network.
vm_ip_range=10.10.10.100-10.10.10.200 IP address range for provisioned virtual
machines.
Restriction: the vm_ip_range must match the
subnet for the PowerVM network (network
where the VIOS's reside on). It must be in
the same subnet with the region server, and
in the same network of the compute node.
vm_ip_netmask=255.255.255.0 Netmask of the vm_ip_range.
vm_gateway=10.10.10.0 The gateway address for provisioned virtual
machines.
share_central_db=no Specify no if the region server uses its own
DB2. Specify yes if the region must share the
same DB2 of the central server.
Note: If you specify yes, make sure that you
have completed Step 2 in the section Before
you begin.
region_type=kvm Region type that you want to deploy to
configure the product to an hypervisor
management infrastructure for that type.
The value can be KVM, VMware, or Power.
If VMware or Power is specified, further
connection configuration parameters are
required for the relative virtual environment.
Chapter 2. Installing 27
Table 9. Compulsory configurations (continued)
Configuration Parameter = default value Description
region_name=RegionOne Region name that you want to use to deploy,
it will be also used as the prefix of the
domain name for the DNS that will be
deployed on the region server when you
choose the build-in DNS or build-in DNS
with the cooperate DNS as the parent DNS
mode.
Note: The region name only use
0-9,a-z,A-Z and it cannot contain special
characters (for example: -/*).
Note: If you specified yes for the
share_central_db option, make sure that
you use a region name that matches the one
you used as input to the command in Step 2
in the Before you begin section.
vcenter_host=""
vcenter_username=""
vcenter_network="""
vcenter_port="443"
The configuration of your vCenter. Only
effective if region_type=vmware.
vcenter_host:
The host name or IP address of
vCenter, for
example:"172.16.102.200".
vcenter_username:
The user name of the administrator
of vCenter, for
example:"Administrator".
Note: SmartCloud Orchestrator
does not support Domain User
Account for vCenter.
vcenter_network:
The network name defined in
vCenter, for example:"VM
Network".
Note: The vcenter_network
parameter is used for the virtual
machine and it is not used to
configure the region server. The
requirement for this network is that
it must be accessible from the
region server. The network
requirement of the region server
depends on the requirement and
network topology of your
environment. To simplify the
topology, you can use the same port
group (network) as the virtual
machine which is defined by the
vcenter_network parameter. If you
use a different port group, make
sure that those two port groups
(network) are accessible.
vcenter_port:
The port to connect to vCenter
(defaults: 443).
28 IBM SmartCloud Orchestrator 2.3: User's Guide
Table 9. Compulsory configurations (continued)
Configuration Parameter = default value Description
vmcontrol_host=""
vmcontrol_username=""
vmcontrol_network=""
vmcontrol_port="8422"
The configuration of your VMControl. Only
applicable if region_type=power.
vmcontrol_host:
The host name or IP address of
VMControl, for
example:"172.16.102.210".
vmcontrol_username:
The user name of the administrator
of VMControl, for example: "root".
vmcontrol_network:
The network name defined in
VMControl, for example:
"Discovered/1/0/ETHERNET0". It
will be used for provisioned virtual
machines.
vmcontrol_port:
The port to connect to VMControl
(defaults: 8422).
Note: The parameter vmcontrol_network is
combined with two VMControl discovered
network device names:
v From the Systems Director Network
Management or Network Control "Logical
Networks" view, select the network name
planned for SmartCloud Orchestrator
instances, like Discovered/1/0.
v To determine the switch device name for
the network, select "Power Systems
Management" from the System Director,
then "X Power Systems Hosts (Physical
Servers)" where "X" is indicating a number
of Power systems hosts, go into the target
host link. You will see a device like
ETHERNET0-IBM*8205-E6D*068840T with a
type of Switch in its properties. Then
ETHERNET0 would be device name of the
network.
So the full vmcontrol_network is the "Logical
Networks" + "/" + switch device name, here
is Discovered/1/0/ETHERNET0
5. If the region server shares a database with the central server, make sure that
the configuration is share_central_db=yes and that you have completed Step 2
in the section Before you begin.
6. Install the Region Server by running the following command on Region
Server-n:
/install_images/installer/deploy_region_server.sh [-h] [-a]
[-p <os-root-password>] -C <central-server-1-ip-address>
[-P <vcenter/vmcontrol-password>]
where:
-h Shows usage
Chapter 2. Installing 29
-a Accepts license by default
-p <os-root-password>
Defines the root password of the Region Server. This parameter is
optional. If it is not indicated here, the command will prompt you for
it.
-C <central-server-1-ip-address>
Defines the IP address of Central Server 1. This parameter is required.
-P <vcenter/vmcontrol-password>
Defines the password of the user name that you specified for your
vCenter or VMControl. This parameter is optional and it applies only
when you are not deploying a KVM region server. If it is not indicated
here, the command will prompt you for it.
Note: In case of any issues, the region can be removed and added again. For
details, refer to Removing a region on page 75.
Results
You can find the installation logs in /var/log/smartcloud/.
What to do next
After one region server has been setup:
v If the region type is VMware or Power, a SmartCloud Orchestrator with the
specific region was setup successfully. If multiple region are required, see
Installing a multiple-region environment on page 47, otherwise see Verifying
the installation on page 47.
v If the region type is KVM , you need add an extra machine to set up the
hypervisor, see Installing a compute node on page 44.
Note: For subsequent KVM compute nodes on the same subnet as the first
compute node, a new region server is not required, as the existing region server
can be reused. See Installing a compute node on page 44.
List of the RPM packages added during installation
This topic provides the list of the RPM packages that are added during the
installation of the Central Servers and Region Servers.
RPM packages added during the installation of Central Server 1
> apr-1.3.9-5.el6_2.x86_64
> apr-util-1.3.9-3.el6_0.1.x86_64
> apr-util-ldap-1.3.9-3.el6_0.1.x86_64
> audit-libs-2.2-2.el6.i686
> bind-9.8.2-0.17.rc1.el6.x86_64
> cloog-ppl-0.15.7-1.2.el6.x86_64
> compat-libstdc++-296-2.96-144.el6.i686
> compat-libstdc++-33-3.2.3-69.el6.i686
> compat-libstdc++-33-3.2.3-69.el6.x86_64
> compat-readline5-5.2-17.1.el6.x86_64
> cpp-4.4.7-3.el6.x86_64
> cracklib-2.8.16-4.el6.i686
> createrepo-0.9.9-17.el6.noarch
> dapl-2.0.34-1.el6.x86_64
> db4-4.7.25-17.el6.i686
> deltarpm-3.5-0.5.20090913git.el6.x86_64
30 IBM SmartCloud Orchestrator 2.3: User's Guide
> dhcp-4.1.1-34.P1.el6.x86_64
> ebtables-2.0.9-6.el6.x86_64
> gcc-4.4.7-3.el6.x86_64
> gcc-c++-4.4.7-3.el6.x86_64
> glibc-2.12-1.107.el6.i686
> glibc-devel-2.12-1.107.el6.x86_64
> glibc-headers-2.12-1.107.el6.x86_64
> httpd-2.2.15-26.el6.x86_64
> httpd-tools-2.2.15-26.el6.x86_64
> ibm-java-x86_64-sdk-6.0-10.0.x86_64
> jss-4.2.6-24.el6.x86_64
> kernel-headers-2.6.32-358.el6.x86_64
> ksh-20100621-19.el6.x86_64
> libgcc-4.4.7-3.el6.i686
> libibverbs-1.1.6-5.el6.x86_64
> librdmacm-1.0.17-0.git4b5c1aa.el6.x86_64
> libselinux-2.0.94-5.3.el6.i686
> libstdc++-4.4.7-3.el6.i686
> libstdc++-devel-4.4.7-3.el6.x86_64
> mpfr-2.4.1-6.el6.x86_64
> nss-softokn-freebl-3.12.9-11.el6.i686
> pam-1.1.1-13.el6.i686
> ppl-0.10.2-11.el6.x86_64
> python-deltarpm-3.5-0.5.20090913git.el6.x86_64
> rsct.64bit-3.1.4.4-13032.x86_64
> rsct.basic-3.1.4.4-13032.i386
> rsct.basic.msg.de_DE-3.1.1.2-11266.i386
> [email protected]
> rsct.basic.msg.de_DE.ISO-8859-1-3.1.1.2-11266.i386
> rsct.basic.msg.de_DE.UTF-8-3.1.1.2-11266.i386
> rsct.basic.msg.es_ES-3.1.1.2-11266.i386
> [email protected]
> rsct.basic.msg.es_ES.ISO-8859-1-3.1.1.2-11266.i386
> rsct.basic.msg.es_ES.UTF-8-3.1.1.2-11266.i386
> rsct.basic.msg.fr_FR-3.1.1.2-11266.i386
> [email protected]
> rsct.basic.msg.fr_FR.ISO-8859-1-3.1.1.2-11266.i386
> rsct.basic.msg.fr_FR.UTF-8-3.1.1.2-11266.i386
> rsct.basic.msg.it_IT-3.1.1.2-11266.i386
> [email protected]
> rsct.basic.msg.it_IT.ISO-8859-1-3.1.1.2-11266.i386
> rsct.basic.msg.it_IT.UTF-8-3.1.1.2-11266.i386
> rsct.basic.msg.ja_JP.eucJP-3.1.1.2-11266.i386
> rsct.basic.msg.ja_JP.UTF-8-3.1.1.2-11266.i386
> rsct.basic.msg.ko_KR.eucKR-3.1.1.2-11266.i386
> rsct.basic.msg.ko_KR.UTF-8-3.1.1.2-11266.i386
> rsct.basic.msg.pt_BR-3.1.1.2-11266.i386
> rsct.basic.msg.pt_BR.UTF-8-3.1.1.2-11266.i386
> rsct.basic.msg.zh_CN.GB18030-3.1.1.2-11266.i386
> rsct.basic.msg.zh_CN.GB2312-3.1.1.2-11266.i386
> rsct.basic.msg.zh_CN.GBK-3.1.1.2-11266.i386
> rsct.basic.msg.zh_CN.UTF-8-3.1.1.2-11266.i386
> rsct.basic.msg.zh_TW-3.1.1.2-11266.i386
> rsct.basic.msg.zh_TW.Big5-3.1.1.2-11266.i386
> rsct.basic.msg.zh_TW.eucTW-3.1.1.2-11266.i386
> rsct.basic.msg.zh_TW.UTF-8-3.1.1.2-11266.i386
> rsct.core-3.1.4.4-13032.i386
> rsct.core.msg.de_DE-3.1.1.2-11266.i386
> [email protected]
> rsct.core.msg.de_DE.ISO-8859-1-3.1.1.2-11266.i386
> rsct.core.msg.de_DE.UTF-8-3.1.1.2-11266.i386
> rsct.core.msg.es_ES-3.1.1.2-11266.i386
> [email protected]
> rsct.core.msg.es_ES.ISO-8859-1-3.1.1.2-11266.i386
> rsct.core.msg.es_ES.UTF-8-3.1.1.2-11266.i386
> rsct.core.msg.fr_FR-3.1.1.2-11266.i386
> [email protected]
Chapter 2. Installing 31
> rsct.core.msg.fr_FR.ISO-8859-1-3.1.1.2-11266.i386
> rsct.core.msg.fr_FR.UTF-8-3.1.1.2-11266.i386
> rsct.core.msg.it_IT-3.1.1.2-11266.i386
> [email protected]
> rsct.core.msg.it_IT.ISO-8859-1-3.1.1.2-11266.i386
> rsct.core.msg.it_IT.UTF-8-3.1.1.2-11266.i386
> rsct.core.msg.ja_JP.eucJP-3.1.1.2-11266.i386
> rsct.core.msg.ja_JP.UTF-8-3.1.1.2-11266.i386
> rsct.core.msg.ko_KR.eucKR-3.1.1.2-11266.i386
> rsct.core.msg.ko_KR.UTF-8-3.1.1.2-11266.i386
> rsct.core.msg.pt_BR-3.1.1.2-11266.i386
> rsct.core.msg.pt_BR.UTF-8-3.1.1.2-11266.i386
> rsct.core.msg.zh_CN.GB18030-3.1.1.2-11266.i386
> rsct.core.msg.zh_CN.GB2312-3.1.1.2-11266.i386
> rsct.core.msg.zh_CN.GBK-3.1.1.2-11266.i386
> rsct.core.msg.zh_CN.UTF-8-3.1.1.2-11266.i386
> rsct.core.msg.zh_TW-3.1.1.2-11266.i386
> rsct.core.msg.zh_TW.Big5-3.1.1.2-11266.i386
> rsct.core.msg.zh_TW.eucTW-3.1.1.2-11266.i386
> rsct.core.msg.zh_TW.UTF-8-3.1.1.2-11266.i386
> rsct.core.utils-3.1.4.4-13032.i386
> rsct.core.utils.msg.de_DE-3.1.1.2-11266.i386
> [email protected]
> rsct.core.utils.msg.de_DE.ISO-8859-1-3.1.1.2-11266.i386
> rsct.core.utils.msg.de_DE.UTF-8-3.1.1.2-11266.i386
> rsct.core.utils.msg.es_ES-3.1.1.2-11266.i386
> [email protected]
> rsct.core.utils.msg.es_ES.ISO-8859-1-3.1.1.2-11266.i386
> rsct.core.utils.msg.es_ES.UTF-8-3.1.1.2-11266.i386
> rsct.core.utils.msg.fr_FR-3.1.1.2-11266.i386
> [email protected]
> rsct.core.utils.msg.fr_FR.ISO-8859-1-3.1.1.2-11266.i386
> rsct.core.utils.msg.fr_FR.UTF-8-3.1.1.2-11266.i386
> rsct.core.utils.msg.it_IT-3.1.1.2-11266.i386
> [email protected]
> rsct.core.utils.msg.it_IT.ISO-8859-1-3.1.1.2-11266.i386
> rsct.core.utils.msg.it_IT.UTF-8-3.1.1.2-11266.i386
> rsct.core.utils.msg.ja_JP.eucJP-3.1.1.2-11266.i386
> rsct.core.utils.msg.ja_JP.UTF-8-3.1.1.2-11266.i386
> rsct.core.utils.msg.ko_KR.eucKR-3.1.1.2-11266.i386
> rsct.core.utils.msg.ko_KR.UTF-8-3.1.1.2-11266.i386
> rsct.core.utils.msg.pt_BR-3.1.1.2-11266.i386
> rsct.core.utils.msg.pt_BR.UTF-8-3.1.1.2-11266.i386
> rsct.core.utils.msg.zh_CN.GB18030-3.1.1.2-11266.i386
> rsct.core.utils.msg.zh_CN.GB2312-3.1.1.2-11266.i386
> rsct.core.utils.msg.zh_CN.GBK-3.1.1.2-11266.i386
> rsct.core.utils.msg.zh_CN.UTF-8-3.1.1.2-11266.i386
> rsct.core.utils.msg.zh_TW-3.1.1.2-11266.i386
> rsct.core.utils.msg.zh_TW.Big5-3.1.1.2-11266.i386
> rsct.core.utils.msg.zh_TW.eucTW-3.1.1.2-11266.i386
> rsct.core.utils.msg.zh_TW.UTF-8-3.1.1.2-11266.i386
> rsct.opt.stackdump-3.1.4.4-13032.i386
> rsct.opt.storagerm-3.1.4.4-13032.i386
> ruby-1.8.7.352-7.el6_2.x86_64
> ruby-devel-1.8.7.352-7.el6_2.x86_64
> rubygems-1.3.7-1.el6.noarch
> ruby-irb-1.8.7.352-7.el6_2.x86_64
> ruby-libs-1.8.7.352-7.el6_2.x86_64
> ruby-rdoc-1.8.7.352-7.el6_2.x86_64
> sam-3.2.2.5-13129.i386
> sam.adapter-3.2.2.5-13129.i386
> sam.msg.de_DE-3.2.2.4-0.i386
> [email protected]
> sam.msg.de_DE.ISO-8859-1-3.2.2.4-0.i386
> sam.msg.de_DE.UTF-8-3.2.2.4-0.i386
> sam.msg.es_ES-3.2.2.4-0.i386
> [email protected]
32 IBM SmartCloud Orchestrator 2.3: User's Guide
> sam.msg.es_ES.ISO-8859-1-3.2.2.4-0.i386
> sam.msg.es_ES.UTF-8-3.2.2.4-0.i386
> sam.msg.fr_FR-3.2.2.4-0.i386
> [email protected]
> sam.msg.fr_FR.ISO-8859-1-3.2.2.4-0.i386
> sam.msg.fr_FR.UTF-8-3.2.2.4-0.i386
> sam.msg.it_IT-3.2.2.4-0.i386
> [email protected]
> sam.msg.it_IT.ISO-8859-1-3.2.2.4-0.i386
> sam.msg.it_IT.UTF-8-3.2.2.4-0.i386
> sam.msg.ja_JP.eucJP-3.2.2.4-0.i386
> sam.msg.ja_JP.UTF-8-3.2.2.4-0.i386
> sam.msg.ko_KR.eucKR-3.2.2.4-0.i386
> sam.msg.ko_KR.UTF-8-3.2.2.4-0.i386
> sam.msg.pt_BR-3.2.2.4-0.i386
> sam.msg.pt_BR.UTF-8-3.2.2.4-0.i386
> sam.msg.zh_CN.GB18030-3.2.2.4-0.i386
> sam.msg.zh_CN.GB2312-3.2.2.4-0.i386
> sam.msg.zh_CN.GBK-3.2.2.4-0.i386
> sam.msg.zh_CN.UTF-8-3.2.2.4-0.i386
> sam.msg.zh_TW-3.2.2.4-0.i386
> sam.msg.zh_TW.Big5-3.2.2.4-0.i386
> sam.msg.zh_TW.eucTW-3.2.2.4-0.i386
> sam.msg.zh_TW.UTF-8-3.2.2.4-0.i386
> sam.policies.one-3.2.2.5-13129.i386
> sam.policies.two-3.2.2.5-13129.i386
> sam.sappolicy-3.2.2.5-13129.i386
> scp-chef_repo_srv-2.2.0.0-201311090045.noarch
> scp-cookbooks-2.3.0.0-B20131109005700.noarch
> sg3_utils-1.28-4.el6.x86_64
> src-3.1.4.4-13032.i386
> src.msg.de_DE-1.3.1.1-11266.i386
> [email protected]
> src.msg.de_DE.ISO-8859-1-1.3.1.1-11266.i386
> src.msg.de_DE.UTF-8-1.3.1.1-11266.i386
> src.msg.es_ES-1.3.1.1-11266.i386
> [email protected]
> src.msg.es_ES.ISO-8859-1-1.3.1.1-11266.i386
> src.msg.es_ES.UTF-8-1.3.1.1-11266.i386
> src.msg.fr_FR-1.3.1.1-11266.i386
> [email protected]
> src.msg.fr_FR.ISO-8859-1-1.3.1.1-11266.i386
> src.msg.fr_FR.UTF-8-1.3.1.1-11266.i386
> src.msg.it_IT-1.3.1.1-11266.i386
> [email protected]
> src.msg.it_IT.ISO-8859-1-1.3.1.1-11266.i386
> src.msg.it_IT.UTF-8-1.3.1.1-11266.i386
> src.msg.ja_JP.eucJP-1.3.1.1-11266.i386
> src.msg.ja_JP.UTF-8-1.3.1.1-11266.i386
> src.msg.ko_KR.eucKR-1.3.1.1-11266.i386
> src.msg.ko_KR.UTF-8-1.3.1.1-11266.i386
> src.msg.pt_BR-1.3.1.1-11266.i386
> src.msg.pt_BR.UTF-8-1.3.1.1-11266.i386
> src.msg.zh_CN.GB18030-1.3.1.1-11266.i386
> src.msg.zh_CN.GB2312-1.3.1.1-11266.i386
> src.msg.zh_CN.GBK-1.3.1.1-11266.i386
> src.msg.zh_CN.UTF-8-1.3.1.1-11266.i386
> src.msg.zh_TW-1.3.1.1-11266.i386
> src.msg.zh_TW.Big5-1.3.1.1-11266.i386
> src.msg.zh_TW.eucTW-1.3.1.1-11266.i386
> src.msg.zh_TW.UTF-8-1.3.1.1-11266.i386
> tunctl-1.5-3.el6.x86_64
Chapter 2. Installing 33
RPM packages added during the installation of Central Server 2
> atk-1.28.0-2.el6.i686
> audit-libs-2.2-2.el6.i686
> augeas-libs-0.9.0-4.el6.x86_64
> avahi-libs-0.6.25-12.el6.i686
> axis-1.2.1-7.2.el6.noarch
> bcel-5.2-7.2.el6.x86_64
> boost-1.47.0-7.ibm.x86_64
> boost-chrono-1.47.0-7.ibm.x86_64
> boost-date-time-1.47.0-7.ibm.x86_64
> boost-filesystem-1.47.0-7.ibm.x86_64
> boost-graph-1.47.0-7.ibm.x86_64
> boost-iostreams-1.47.0-7.ibm.x86_64
> boost-program-options-1.47.0-7.ibm.x86_64
> boost-python-1.47.0-7.ibm.x86_64
> boost-random-1.47.0-7.ibm.x86_64
> boost-regex-1.47.0-7.ibm.x86_64
> boost-serialization-1.47.0-7.ibm.x86_64
> boost-signals-1.47.0-7.ibm.x86_64
> boost-system-1.47.0-7.ibm.x86_64
> boost-test-1.47.0-7.ibm.x86_64
> boost-thread-1.47.0-7.ibm.x86_64
> boost-wave-1.47.0-7.ibm.x86_64
> btrfs-progs-0.20-0.2.git91d9eec.el6.x86_64
> bzip2-devel-1.0.5-7.el6_0.x86_64
> bzip2-libs-1.0.5-7.el6_0.i686
> cairo-1.8.8-3.1.el6.i686
> celt051-0.5.1.3-0.el6.x86_64
> classpathx-jaf-1.0-15.4.el6.x86_64
> classpathx-mail-1.1.1-9.4.el6.noarch
> cloog-ppl-0.15.7-1.2.el6.x86_64
> compat-db42-4.2.52-15.el6.i686
> compat-db42-4.2.52-15.el6.x86_64
> compat-db43-4.3.29-15.el6.i686
> compat-db43-4.3.29-15.el6.x86_64
> compat-db-4.6.21-15.el6.i686
> compat-db-4.6.21-15.el6.x86_64
> compat-libstdc++-33-3.2.3-69.el6.i686
> compat-libstdc++-33-3.2.3-69.el6.x86_64
> compat-readline5-5.2-17.1.el6.x86_64
> cpp-4.4.7-3.el6.x86_64
> cracklib-2.8.16-4.el6.i686
> cups-libs-1.4.2-48.el6_3.3.i686
> cyrus-sasl-md5-2.1.23-13.el6_3.1.x86_64
> db4-4.7.25-17.el6.i686
> dbus-libs-1.2.24-7.el6_3.i686
> dos2unix-3.1-37.el6.x86_64
> ebtables-2.0.9-6.el6.x86_64
> ecj-3.4.2-6.el6.x86_64
> elfutils-libelf-0.152-1.el6.i686
> elfutils-libs-0.152-1.el6.i686
> expat-2.0.1-11.el6_2.i686
> febootstrap-supermin-helper-3.12-2.el6.x86_64
> fontconfig-2.8.0-3.el6.i686
> freetype-2.3.11-6.el6_2.9.i686
> fuse-2.8.3-4.el6.x86_64
> fuse-libs-2.8.3-4.el6.x86_64
> gamin-0.1.10-9.el6.i686
> gcc-4.4.7-3.el6.x86_64
> gcc-c++-4.4.7-3.el6.x86_64
> genisoimage-1.1.9-12.el6.x86_64
> glib2-2.22.5-7.el6.i686
> glibc-2.12-1.107.el6.i686
> glibc-devel-2.12-1.107.el6.x86_64
> glibc-headers-2.12-1.107.el6.x86_64
> gnutls-2.8.5-10.el6.i686
> gnutls-utils-2.8.5-10.el6.x86_64
34 IBM SmartCloud Orchestrator 2.3: User's Guide
> gpxe-roms-qemu-0.9.7-6.9.el6.noarch
> gtk2-2.18.9-12.el6.i686
> gtk2-engines-2.18.4-5.el6.i686
> gtk2-engines-2.18.4-5.el6.x86_64
> hivex-1.3.3-4.2.el6.x86_64
> iaasgateway-2013.1-1.1.1.ibm.201310312301.noarch
> ibm-java-x86_64-sdk-6.0-10.0.x86_64
> ibm-simpletoken-authenticator-middleware-2013.1.4-201310161128.ibm.noarch
> iscsi-initiator-utils-6.2.0.873-2.el6.x86_64
> jakarta-commons-collections-3.2.1-3.4.el6.noarch
> jakarta-commons-daemon-1.0.1-8.9.el6.x86_64
> jakarta-commons-dbcp-1.2.1-13.8.el6.noarch
> jakarta-commons-discovery-0.4-5.4.el6.noarch
> jakarta-commons-httpclient-3.1-0.6.el6.x86_64
> jakarta-commons-logging-1.0.4-10.el6.noarch
> jakarta-commons-pool-1.3-12.7.el6.x86_64
> jasper-libs-1.900.1-15.el6_1.1.i686
> java-1.5.0-gcj-1.5.0.0-29.1.el6.x86_64
> java_cup-0.10k-5.el6.x86_64
> kernel-headers-2.6.32-358.el6.x86_64
> keyutils-libs-1.4-4.el6.i686
> keyutils-libs-devel-1.4-4.el6.x86_64
> krb5-devel-1.10.3-10.el6.x86_64
> krb5-libs-1.10.3-10.el6.i686
> ksh-20100621-19.el6.x86_64
> libart_lgpl-2.3.20-5.1.el6.x86_64
> libcom_err-1.41.12-14.el6.i686
> libcom_err-devel-1.41.12-14.el6.x86_64
> libconfig-1.3.2-1.1.el6.x86_64
> libgcc-4.4.7-3.el6.i686
> libgcj-4.4.7-3.el6.x86_64
> libgcrypt-1.4.5-9.el6_2.2.i686
> libgcrypt-devel-1.4.5-9.el6_2.2.x86_64
> libgpg-error-1.7-4.el6.i686
> libgpg-error-devel-1.7-4.el6.x86_64
> libguestfs-1.16.34-2.el6.x86_64
> libguestfs-tools-1.16.34-2.el6.x86_64
> libguestfs-tools-c-1.16.34-2.el6.x86_64
> libguestfs-winsupport-1.0-7.el6.x86_64
> libICE-1.0.6-1.el6.i686
> libicu-4.2.1-9.1.el6_2.x86_64
> libjpeg-turbo-1.2.1-1.el6.i686
> libpng-1.2.49-1.el6_2.i686
> libselinux-2.0.94-5.3.el6.i686
> libselinux-devel-2.0.94-5.3.el6.x86_64
> libsepol-devel-2.0.41-4.el6.x86_64
> libSM-1.2.1-2.el6.i686
> libstdc++-4.4.7-3.el6.i686
> libstdc++-devel-4.4.7-3.el6.x86_64
> libtasn1-2.3-3.el6_2.1.i686
> libthai-0.1.12-3.el6.i686
> libtiff-3.9.4-9.el6_3.i686
> libuuid-2.17.2-12.9.el6.i686
> libvirt-client-0.10.2-18.el6.x86_64
> libX11-1.5.0-4.el6.i686
> libXau-1.0.6-4.el6.i686
> libxcb-1.8.1-1.el6.i686
> libXcomposite-0.4.3-4.el6.i686
> libXcursor-1.1.13-2.el6.i686
> libXdamage-1.1.3-4.el6.i686
> libXext-1.3.1-2.el6.i686
> libXfixes-5.0-3.el6.i686
> libXft-2.3.1-2.el6.i686
> libXi-1.6.1-3.el6.i686
> libXinerama-1.1.2-2.el6.i686
> libXmu-1.1.1-2.el6.i686
> libXmu-1.1.1-2.el6.x86_64
Chapter 2. Installing 35
> libXp-1.0.0-15.1.el6.i686
> libXp-1.0.0-15.1.el6.x86_64
> libXrandr-1.4.0-1.el6.i686
> libXrender-0.9.7-2.el6.i686
> libXt-1.1.3-1.el6.i686
> libXtst-1.2.1-2.el6.i686
> log4j-1.2.14-6.4.el6.x86_64
> lzo-2.03-3.1.el6.x86_64
> lzop-1.02-0.9.rc1.el6.x86_64
> memcached-1.4.4-3.el6.x86_64
> mpfr-2.4.1-6.el6.x86_64
> mx4j-3.0.1-9.13.el6.noarch
> MySQL-python-1.2.3-0.3.c1.1.el6.x86_64
> nc-1.84-22.el6.x86_64
> ncurses-devel-5.7-3.20090208.el6.x86_64
> netcf-libs-0.1.9-3.el6.x86_64
> nss-softokn-freebl-3.12.9-11.el6.i686
> openssl-devel-1.0.0-27.el6.x86_64
> openstack-keystone-2013.1.4.1-201310310850.ibm.5.noarch
> openstack-utils-2013.1.1.1-201306031701.ibm.1.noarch
> pam-1.1.1-13.el6.i686
> pango-1.28.1-7.el6_3.i686
> perl-Digest-SHA1-2.12-2.el6.x86_64
> perl-hivex-1.3.3-4.2.el6.x86_64
> perl-libintl-1.20-1.el6.x86_64
> perl-Sys-Guestfs-1.16.34-2.el6.x86_64
> perl-Sys-Virt-0.10.2-5.el6.x86_64
> perl-XML-Writer-0.606-6.el6.noarch
> perl-XML-XPath-1.13-10.el6.noarch
> pixman-0.26.2-4.el6.i686
> ppl-0.10.2-11.el6.x86_64
> PyPAM-0.5.0-12.el6.x86_64
> python-anyjson-0.2.4-4.003.ibm.noarch
> python-argparse-1.2.1-3.ibm.noarch
> python-babel-0.9.6-3.001.ibm.noarch
> python-decorator-3.0.1-3.1.el6.noarch
> python-eventlet-0.9.17-2.ibm.noarch
> python-greenlet-0.3.4-11.001.ibm.x86_64
> python-httplib2-0.7.4-7.ibm.noarch
> python-ibm-db-2.0.4.1-2.ibm.el6.x86_64
> python-ibm-db-sa-0.3.0-6.ibm.el6.noarch
> python-iso8601-0.1.4-3.ibm.noarch
> python-keystone-2013.1.4.1-201310310850.ibm.5.noarch
> python-keystoneclient-0.2.3-71.ibm.noarch
> python-libguestfs-1.16.34-2.el6.x86_64
> python-memcached-1.43-6.el6.noarch
> python-migrate-0.7.2-9.ibm.noarch
> python-oslo-config-1.1.1-201308151039.ibm.noarch
> python-passlib-1.5.3-2.ibm.noarch
> python-paste-1.7.4-2.el6.noarch
> python-paste-deploy-1.5.0-5.ibm.001.noarch
> python-prettytable-0.6.1-2.ibm.noarch
> python-requests-0.14.1-2.002.ibm.noarch
> python-routes-1.12.3-5.001.ibm.noarch
> python-sqlalchemy-0.7.9-3.ibm.el6.x86_64
> python-tempita-0.4-2.el6.noarch
> python-webob-1.2.3-2.ibm.noarch
> qemu-img-0.12.1.2-2.355.el6.x86_64
> qemu-kvm-0.12.1.2-2.355.el6.x86_64
> qpid-cpp-client-0.18-6.001.ibm.x86_64
> qpid-cpp-client-ssl-0.18-6.001.ibm.x86_64
> readline-devel-6.0-4.el6.x86_64
> regexp-1.5-4.4.el6.x86_64
> rpm-build-4.8.0-32.el6.x86_64
> ruby-1.8.7.352-7.el6_2.x86_64
> ruby-devel-1.8.7.352-7.el6_2.x86_64
> rubygems-1.3.7-1.el6.noarch
36 IBM SmartCloud Orchestrator 2.3: User's Guide
> ruby-irb-1.8.7.352-7.el6_2.x86_64
> ruby-libs-1.8.7.352-7.el6_2.x86_64
> ruby-rdoc-1.8.7.352-7.el6_2.x86_64
> scrub-2.2-1.el6.x86_64
> seabios-0.6.1.2-26.el6.x86_64
> sgabios-bin-0-0.3.20110621svn.el6.noarch
> sinjdoc-0.5-9.1.el6.x86_64
> spice-server-0.12.0-12.el6.x86_64
> sqlite-devel-3.6.20-1.el6.x86_64
> tomcat6-6.0.24-49.el6.noarch
> tomcat6-el-2.1-api-6.0.24-49.el6.noarch
> tomcat6-jsp-2.1-api-6.0.24-49.el6.noarch
> tomcat6-lib-6.0.24-49.el6.noarch
> tomcat6-servlet-2.5-api-6.0.24-49.el6.noarch
> tunctl-1.5-3.el6.x86_64
> usbredir-0.5.1-1.el6.x86_64
> vgabios-0.6b-3.7.el6.noarch
> wsdl4j-1.5.2-7.8.el6.noarch
> xml-commons-apis-1.3.04-3.6.el6.x86_64
> xml-commons-resolver-1.1-4.18.el6.x86_64
> xz-libs-4.999.9-0.3.beta.20091007git.el6.i686
> yajl-1.0.7-3.el6.x86_64
> zlib-1.2.3-29.el6.i686
RPM packages added during the installation of Central Server 3
> cloog-ppl-0.15.7-1.2.el6.x86_64
> compat-libstdc++-33-3.2.3-69.el6.i686
> compat-libstdc++-33-3.2.3-69.el6.x86_64
> compat-readline5-5.2-17.1.el6.x86_64
> cpp-4.4.7-3.el6.x86_64
> dos2unix-3.1-37.el6.x86_64
> ebtables-2.0.9-6.el6.x86_64
> gcc-4.4.7-3.el6.x86_64
> gcc-c++-4.4.7-3.el6.x86_64
> genisoimage-1.1.9-12.el6.x86_64
> glibc-2.12-1.107.el6.i686
> glibc-devel-2.12-1.107.el6.x86_64
> glibc-headers-2.12-1.107.el6.x86_64
> ibm-java-i386-sdk-6.0-9.3.i386
> ibm-java-x86_64-sdk-6.0-10.0.x86_64
> kernel-headers-2.6.32-358.el6.x86_64
> libgcc-4.4.7-3.el6.i686
> libstdc++-devel-4.4.7-3.el6.x86_64
> mpfr-2.4.1-6.el6.x86_64
> nss-softokn-freebl-3.12.9-11.el6.i686
> ppl-0.10.2-11.el6.x86_64
> ruby-1.8.7.352-7.el6_2.x86_64
> ruby-devel-1.8.7.352-7.el6_2.x86_64
> rubygems-1.3.7-1.el6.noarch
> ruby-irb-1.8.7.352-7.el6_2.x86_64
> ruby-libs-1.8.7.352-7.el6_2.x86_64
> ruby-rdoc-1.8.7.352-7.el6_2.x86_64
> tunctl-1.5-3.el6.x86_64
RPM packages added during the installation of Central Server 4
> atk-1.28.0-2.el6.i686
> audit-libs-2.2-2.el6.i686
> avahi-libs-0.6.25-12.el6.i686
> cairo-1.8.8-3.1.el6.i686
> cloog-ppl-0.15.7-1.2.el6.x86_64
> compat-readline5-5.2-17.1.el6.x86_64
> cpp-4.4.7-3.el6.x86_64
> cups-libs-1.4.2-48.el6_3.3.i686
> dbus-libs-1.2.24-7.el6_3.i686
> ebtables-2.0.9-6.el6.x86_64
> expat-2.0.1-11.el6_2.i686
Chapter 2. Installing 37
> fontconfig-2.8.0-3.el6.i686
> freetype-2.3.11-6.el6_2.9.i686
> gamin-0.1.10-9.el6.i686
> gcc-4.4.7-3.el6.x86_64
> gcc-c++-4.4.7-3.el6.x86_64
> glib2-2.22.5-7.el6.i686
> glibc-2.12-1.107.el6.i686
> glibc-devel-2.12-1.107.el6.x86_64
> glibc-headers-2.12-1.107.el6.x86_64
> gnutls-2.8.5-10.el6.i686
> gtk2-2.18.9-12.el6.i686
> jasper-libs-1.900.1-15.el6_1.1.i686
> kernel-headers-2.6.32-358.el6.x86_64
> keyutils-libs-1.4-4.el6.i686
> krb5-libs-1.10.3-10.el6.i686
> ksh-20100621-19.el6.x86_64
> libcom_err-1.41.12-14.el6.i686
> libgcc-4.4.7-3.el6.i686
> libgcrypt-1.4.5-9.el6_2.2.i686
> libgpg-error-1.7-4.el6.i686
> libjpeg-turbo-1.2.1-1.el6.i686
> libpng-1.2.49-1.el6_2.i686
> libselinux-2.0.94-5.3.el6.i686
> libstdc++-4.4.7-3.el6.i686
> libstdc++-devel-4.4.7-3.el6.x86_64
> libtasn1-2.3-3.el6_2.1.i686
> libthai-0.1.12-3.el6.i686
> libtiff-3.9.4-9.el6_3.i686
> libX11-1.5.0-4.el6.i686
> libXau-1.0.6-4.el6.i686
> libxcb-1.8.1-1.el6.i686
> libXcomposite-0.4.3-4.el6.i686
> libXcursor-1.1.13-2.el6.i686
> libXdamage-1.1.3-4.el6.i686
> libXext-1.3.1-2.el6.i686
> libXfixes-5.0-3.el6.i686
> libXft-2.3.1-2.el6.i686
> libXi-1.6.1-3.el6.i686
> libXinerama-1.1.2-2.el6.i686
> libXrandr-1.4.0-1.el6.i686
> libXrender-0.9.7-2.el6.i686
> libXtst-1.2.1-2.el6.i686
> mpfr-2.4.1-6.el6.x86_64
> nss-softokn-freebl-3.12.9-11.el6.i686
> pango-1.28.1-7.el6_3.i686
> pixman-0.26.2-4.el6.i686
> ppl-0.10.2-11.el6.x86_64
> ruby-1.8.7.352-7.el6_2.x86_64
> ruby-devel-1.8.7.352-7.el6_2.x86_64
> rubygems-1.3.7-1.el6.noarch
> ruby-irb-1.8.7.352-7.el6_2.x86_64
> ruby-libs-1.8.7.352-7.el6_2.x86_64
> ruby-rdoc-1.8.7.352-7.el6_2.x86_64
> tunctl-1.5-3.el6.x86_64
> zlib-1.2.3-29.el6.i686
RPM packages added during the installation of Region Server
"n"
> apr-1.3.9-5.el6_2.x86_64
> apr-util-1.3.9-3.el6_0.1.x86_64
> apr-util-ldap-1.3.9-3.el6_0.1.x86_64
> audit-libs-2.2-2.el6.i686
> augeas-libs-0.9.0-4.el6.x86_64
> bind-9.8.2-0.17.rc1.el6.x86_64
> boost-1.47.0-7.ibm.x86_64
> boost-chrono-1.47.0-7.ibm.x86_64
38 IBM SmartCloud Orchestrator 2.3: User's Guide
> boost-date-time-1.47.0-7.ibm.x86_64
> boost-filesystem-1.47.0-7.ibm.x86_64
> boost-graph-1.47.0-7.ibm.x86_64
> boost-iostreams-1.47.0-7.ibm.x86_64
> boost-program-options-1.47.0-7.ibm.x86_64
> boost-python-1.47.0-7.ibm.x86_64
> boost-random-1.47.0-7.ibm.x86_64
> boost-regex-1.47.0-7.ibm.x86_64
> boost-serialization-1.47.0-7.ibm.x86_64
> boost-signals-1.47.0-7.ibm.x86_64
> boost-system-1.47.0-7.ibm.x86_64
> boost-test-1.47.0-7.ibm.x86_64
> boost-thread-1.47.0-7.ibm.x86_64
> boost-wave-1.47.0-7.ibm.x86_64
> btrfs-progs-0.20-0.2.git91d9eec.el6.x86_64
> bzip2-devel-1.0.5-7.el6_0.x86_64
> celt051-0.5.1.3-0.el6.x86_64
> cloog-ppl-0.15.7-1.2.el6.x86_64
> compat-libstdc++-296-2.96-144.el6.i686
> compat-libstdc++-33-3.2.3-69.el6.i686
> compat-libstdc++-33-3.2.3-69.el6.x86_64
> compat-readline5-5.2-17.1.el6.x86_64
> cpp-4.4.7-3.el6.x86_64
> cracklib-2.8.16-4.el6.i686
> createrepo-0.9.9-17.el6.noarch
> cyrus-sasl-md5-2.1.23-13.el6_3.1.x86_64
> dapl-2.0.34-1.el6.x86_64
> db4-4.7.25-17.el6.i686
> deltarpm-3.5-0.5.20090913git.el6.x86_64
> dhcp-4.1.1-34.P1.el6.x86_64
> dnsmasq-2.59-5.ibm.003.x86_64
> dnsmasq-utils-2.59-5.ibm.003.x86_64
> dos2unix-3.1-37.el6.x86_64
> ebtables-2.0.9-6.el6.x86_64
> febootstrap-supermin-helper-3.12-2.el6.x86_64
> fuse-2.8.3-4.el6.x86_64
> fuse-libs-2.8.3-4.el6.x86_64
> gcc-4.4.7-3.el6.x86_64
> gcc-c++-4.4.7-3.el6.x86_64
> genisoimage-1.1.9-12.el6.x86_64
> glibc-2.12-1.107.el6.i686
> glibc-devel-2.12-1.107.el6.x86_64
> glibc-headers-2.12-1.107.el6.x86_64
> gnutls-utils-2.8.5-10.el6.x86_64
> gpxe-roms-qemu-0.9.7-6.9.el6.noarch
> hivex-1.3.3-4.2.el6.x86_64
> httpd-2.2.15-26.el6.x86_64
> httpd-tools-2.2.15-26.el6.x86_64
> iscsi-initiator-utils-6.2.0.873-2.el6.x86_64
> kernel-headers-2.6.32-358.el6.x86_64
> keyutils-libs-devel-1.4-4.el6.x86_64
> krb5-devel-1.10.3-10.el6.x86_64
> ksh-20100621-19.el6.x86_64
> libcom_err-devel-1.41.12-14.el6.x86_64
> libconfig-1.3.2-1.1.el6.x86_64
> libgcc-4.4.7-3.el6.i686
> libgcrypt-devel-1.4.5-9.el6_2.2.x86_64
> libgpg-error-devel-1.7-4.el6.x86_64
> libguestfs-1.16.34-2.el6.x86_64
> libguestfs-tools-1.16.34-2.el6.x86_64
> libguestfs-tools-c-1.16.34-2.el6.x86_64
> libguestfs-winsupport-1.0-7.el6.x86_64
> libibverbs-1.1.6-5.el6.x86_64
> libicu-4.2.1-9.1.el6_2.x86_64
> librdmacm-1.0.17-0.git4b5c1aa.el6.x86_64
> libselinux-2.0.94-5.3.el6.i686
> libselinux-devel-2.0.94-5.3.el6.x86_64
Chapter 2. Installing 39
> libsepol-devel-2.0.41-4.el6.x86_64
> libstdc++-4.4.7-3.el6.i686
> libstdc++-devel-4.4.7-3.el6.x86_64
> libvirt-0.10.2-18.el6.x86_64
> libvirt-client-0.10.2-18.el6.x86_64
> libvirt-python-0.10.2-18.el6.x86_64
> lzo-2.03-3.1.el6.x86_64
> lzop-1.02-0.9.rc1.el6.x86_64
> mpfr-2.4.1-6.el6.x86_64
> mtools-4.0.12-1.el6.x86_64
> MySQL-python-1.2.3-0.3.c1.1.el6.x86_64
> nc-1.84-22.el6.x86_64
> ncurses-devel-5.7-3.20090208.el6.x86_64
> netcf-libs-0.1.9-3.el6.x86_64
> novnc-0.4-6.003.ibm.el6.noarch
> nss-softokn-freebl-3.12.9-11.el6.i686
> openssl-devel-1.0.0-27.el6.x86_64
> openstack-cinder-2013.1.4.1-201310310842.ibm.5.noarch
> openstack-glance-2013.1.4.1-201310310845.ibm.5.noarch
> openstack-nova-2013.1.4.1-201310310901.ibm.8.noarch
> openstack-nova-api-2013.1.4.1-201310310901.ibm.8.noarch
> openstack-nova-cells-2013.1.4.1-201310310901.ibm.8.noarch
> openstack-nova-cert-2013.1.4.1-201310310901.ibm.8.noarch
> openstack-nova-common-2013.1.4.1-201310310901.ibm.8.noarch
> openstack-nova-compute-2013.1.4.1-201310310901.ibm.8.noarch
> openstack-nova-compute-prereqs-2013.1-201308201437.ibm.1.x86_64
> openstack-nova-conductor-2013.1.4.1-201310310901.ibm.8.noarch
> openstack-nova-console-2013.1.4.1-201310310901.ibm.8.noarch
> openstack-nova-network-2013.1.4.1-201310310901.ibm.8.noarch
> openstack-nova-novncproxy-0.4-6.003.ibm.el6.noarch
> openstack-nova-objectstore-2013.1.4.1-201310310901.ibm.8.noarch
> openstack-nova-scheduler-2013.1.4.1-201310310901.ibm.8.noarch
> openstack-utils-2013.1.1.1-201306031701.ibm.1.noarch
> pam-1.1.1-13.el6.i686
> perl-Config-General-2.44-1.el6.noarch
> perl-hivex-1.3.3-4.2.el6.x86_64
> perl-libintl-1.20-1.el6.x86_64
> perl-Sys-Guestfs-1.16.34-2.el6.x86_64
> perl-Sys-Virt-0.10.2-5.el6.x86_64
> perl-XML-Writer-0.606-6.el6.noarch
> perl-XML-XPath-1.13-10.el6.noarch
> ppl-0.10.2-11.el6.x86_64
> PyPAM-0.5.0-12.el6.x86_64
> pyparsing-1.5.7-2.ibm.noarch
> python-amqplib-0.6.1-3.002.ibm.noarch
> python-anyjson-0.2.4-4.003.ibm.noarch
> python-argparse-1.2.1-3.ibm.noarch
> python-boto-2.5.2-2.ibm.noarch
> python-cheetah-2.4.4-4.001.ibm.x86_64
> python-cinder-2013.1.4.1-201310310842.ibm.5.noarch
> python-cinderclient-1.0.3-2.ibm.noarch
> python-cliff-1.3.2-1.ibm.noarch
> python-cmd2-0.6.4-3.ibm.noarch
> python-crypto-2.3-7.ibm.002.x86_64
> python-decorator-3.0.1-3.1.el6.noarch
> python-deltarpm-3.5-0.5.20090913git.el6.x86_64
> python-eventlet-0.9.17-2.ibm.noarch
> python-glance-2013.1.4.1-201310310845.ibm.5.noarch
> python-glanceclient-0.9.0-4.ibm.el6.noarch
> python-greenlet-0.3.4-11.001.ibm.x86_64
> python-httplib2-0.7.4-7.ibm.noarch
> python-ibm-db-2.0.4.1-2.ibm.el6.x86_64
> python-ibm-db-sa-0.3.0-6.ibm.el6.noarch
> python-iso8601-0.1.4-3.ibm.noarch
> python-jsonpatch-0.10-2.ibm.noarch
> python-jsonpointer-0.5-2.ibm.noarch
> python-jsonschema-0.7-2.ibm.noarch
40 IBM SmartCloud Orchestrator 2.3: User's Guide
> python-keystone-2013.1.4.1-201310310850.ibm.5.noarch
> python-keystoneclient-0.2.3-71.ibm.noarch
> python-kombu-1.0.4-2.002.ibm.noarch
> python-libguestfs-1.16.34-2.el6.x86_64
> python-lockfile-0.8-4.ibm.002.noarch
> python-markdown-2.0.1-3.1.el6.noarch
> python-memcached-1.43-6.el6.noarch
> python-migrate-0.7.2-9.ibm.noarch
> python-nova-2013.1.4.1-201310310901.ibm.8.noarch
> python-novaclient-2.13-2.ibm.noarch
> python-ordereddict-1.1-3.001.ibm.noarch
> python-oslo-config-1.1.1-201308151039.ibm.noarch
> python-paramiko-1.8.0-3.ibm.el6.noarch
> python-passlib-1.5.3-2.ibm.noarch
> python-paste-1.7.4-2.el6.noarch
> python-paste-deploy-1.5.0-5.ibm.001.noarch
> python-prettytable-0.6.1-2.ibm.noarch
> python-pyasn1-0.0.12a-2.ibm.noarch
> python-pygments-1.1.1-1.el6.noarch
> python-qpid-0.18-3.ibm.el6.noarch
> python-qpid-qmf-0.18-6.001.ibm.x86_64
> python-quantumclient-2.2.1-5.ibm.noarch
> python-requests-0.14.1-2.002.ibm.noarch
> python-routes-1.12.3-5.001.ibm.noarch
> python-sqlalchemy-0.7.9-3.ibm.el6.x86_64
> python-stevedore-0.8-2.ibm.noarch
> python-suds-0.4.1-3.el6.noarch
> python-swiftclient-1.2.0-4.ibm.noarch
> python-tempita-0.4-2.el6.noarch
> python-warlock-0.7.0-2.ibm.noarch
> python-webob-1.2.3-2.ibm.noarch
> python-websockify-0.2.0-3.001.ibm.noarch
> python-wsgiref-0.1.2-10.001.ibm.noarch
> qemu-img-0.12.1.2-2.355.el6.x86_64
> qemu-kvm-0.12.1.2-2.355.el6.x86_64
> qpid-cpp-client-0.18-6.001.ibm.x86_64
> qpid-cpp-server-0.18-6.001.ibm.x86_64
> qpid-cpp-server-ha-0.18-6.001.ibm.x86_64
> qpid-qmf-0.18-6.001.ibm.x86_64
> qpid-tools-0.18-6.001.ibm.noarch
> radvd-1.6-1.el6.x86_64
> readline-devel-6.0-4.el6.x86_64
> rsct.64bit-3.1.4.4-13032.x86_64
> rsct.basic-3.1.4.4-13032.i386
> rsct.basic.msg.de_DE-3.1.1.2-11266.i386
> [email protected]
> rsct.basic.msg.de_DE.ISO-8859-1-3.1.1.2-11266.i386
> rsct.basic.msg.de_DE.UTF-8-3.1.1.2-11266.i386
> rsct.basic.msg.es_ES-3.1.1.2-11266.i386
> [email protected]
> rsct.basic.msg.es_ES.ISO-8859-1-3.1.1.2-11266.i386
> rsct.basic.msg.es_ES.UTF-8-3.1.1.2-11266.i386
> rsct.basic.msg.fr_FR-3.1.1.2-11266.i386
> [email protected]
> rsct.basic.msg.fr_FR.ISO-8859-1-3.1.1.2-11266.i386
> rsct.basic.msg.fr_FR.UTF-8-3.1.1.2-11266.i386
> rsct.basic.msg.it_IT-3.1.1.2-11266.i386
> [email protected]
> rsct.basic.msg.it_IT.ISO-8859-1-3.1.1.2-11266.i386
> rsct.basic.msg.it_IT.UTF-8-3.1.1.2-11266.i386
> rsct.basic.msg.ja_JP.eucJP-3.1.1.2-11266.i386
> rsct.basic.msg.ja_JP.UTF-8-3.1.1.2-11266.i386
> rsct.basic.msg.ko_KR.eucKR-3.1.1.2-11266.i386
> rsct.basic.msg.ko_KR.UTF-8-3.1.1.2-11266.i386
> rsct.basic.msg.pt_BR-3.1.1.2-11266.i386
> rsct.basic.msg.pt_BR.UTF-8-3.1.1.2-11266.i386
> rsct.basic.msg.zh_CN.GB18030-3.1.1.2-11266.i386
Chapter 2. Installing 41
> rsct.basic.msg.zh_CN.GB2312-3.1.1.2-11266.i386
> rsct.basic.msg.zh_CN.GBK-3.1.1.2-11266.i386
> rsct.basic.msg.zh_CN.UTF-8-3.1.1.2-11266.i386
> rsct.basic.msg.zh_TW-3.1.1.2-11266.i386
> rsct.basic.msg.zh_TW.Big5-3.1.1.2-11266.i386
> rsct.basic.msg.zh_TW.eucTW-3.1.1.2-11266.i386
> rsct.basic.msg.zh_TW.UTF-8-3.1.1.2-11266.i386
> rsct.core-3.1.4.4-13032.i386
> rsct.core.msg.de_DE-3.1.1.2-11266.i386
> [email protected]
> rsct.core.msg.de_DE.ISO-8859-1-3.1.1.2-11266.i386
> rsct.core.msg.de_DE.UTF-8-3.1.1.2-11266.i386
> rsct.core.msg.es_ES-3.1.1.2-11266.i386
> [email protected]
> rsct.core.msg.es_ES.ISO-8859-1-3.1.1.2-11266.i386
> rsct.core.msg.es_ES.UTF-8-3.1.1.2-11266.i386
> rsct.core.msg.fr_FR-3.1.1.2-11266.i386
> [email protected]
> rsct.core.msg.fr_FR.ISO-8859-1-3.1.1.2-11266.i386
> rsct.core.msg.fr_FR.UTF-8-3.1.1.2-11266.i386
> rsct.core.msg.it_IT-3.1.1.2-11266.i386
> [email protected]
> rsct.core.msg.it_IT.ISO-8859-1-3.1.1.2-11266.i386
> rsct.core.msg.it_IT.UTF-8-3.1.1.2-11266.i386
> rsct.core.msg.ja_JP.eucJP-3.1.1.2-11266.i386
> rsct.core.msg.ja_JP.UTF-8-3.1.1.2-11266.i386
> rsct.core.msg.ko_KR.eucKR-3.1.1.2-11266.i386
> rsct.core.msg.ko_KR.UTF-8-3.1.1.2-11266.i386
> rsct.core.msg.pt_BR-3.1.1.2-11266.i386
> rsct.core.msg.pt_BR.UTF-8-3.1.1.2-11266.i386
> rsct.core.msg.zh_CN.GB18030-3.1.1.2-11266.i386
> rsct.core.msg.zh_CN.GB2312-3.1.1.2-11266.i386
> rsct.core.msg.zh_CN.GBK-3.1.1.2-11266.i386
> rsct.core.msg.zh_CN.UTF-8-3.1.1.2-11266.i386
> rsct.core.msg.zh_TW-3.1.1.2-11266.i386
> rsct.core.msg.zh_TW.Big5-3.1.1.2-11266.i386
> rsct.core.msg.zh_TW.eucTW-3.1.1.2-11266.i386
> rsct.core.msg.zh_TW.UTF-8-3.1.1.2-11266.i386
> rsct.core.utils-3.1.4.4-13032.i386
> rsct.core.utils.msg.de_DE-3.1.1.2-11266.i386
> [email protected]
> rsct.core.utils.msg.de_DE.ISO-8859-1-3.1.1.2-11266.i386
> rsct.core.utils.msg.de_DE.UTF-8-3.1.1.2-11266.i386
> rsct.core.utils.msg.es_ES-3.1.1.2-11266.i386
> [email protected]
> rsct.core.utils.msg.es_ES.ISO-8859-1-3.1.1.2-11266.i386
> rsct.core.utils.msg.es_ES.UTF-8-3.1.1.2-11266.i386
> rsct.core.utils.msg.fr_FR-3.1.1.2-11266.i386
> [email protected]
> rsct.core.utils.msg.fr_FR.ISO-8859-1-3.1.1.2-11266.i386
> rsct.core.utils.msg.fr_FR.UTF-8-3.1.1.2-11266.i386
> rsct.core.utils.msg.it_IT-3.1.1.2-11266.i386
> [email protected]
> rsct.core.utils.msg.it_IT.ISO-8859-1-3.1.1.2-11266.i386
> rsct.core.utils.msg.it_IT.UTF-8-3.1.1.2-11266.i386
> rsct.core.utils.msg.ja_JP.eucJP-3.1.1.2-11266.i386
> rsct.core.utils.msg.ja_JP.UTF-8-3.1.1.2-11266.i386
> rsct.core.utils.msg.ko_KR.eucKR-3.1.1.2-11266.i386
> rsct.core.utils.msg.ko_KR.UTF-8-3.1.1.2-11266.i386
> rsct.core.utils.msg.pt_BR-3.1.1.2-11266.i386
> rsct.core.utils.msg.pt_BR.UTF-8-3.1.1.2-11266.i386
> rsct.core.utils.msg.zh_CN.GB18030-3.1.1.2-11266.i386
> rsct.core.utils.msg.zh_CN.GB2312-3.1.1.2-11266.i386
> rsct.core.utils.msg.zh_CN.GBK-3.1.1.2-11266.i386
> rsct.core.utils.msg.zh_CN.UTF-8-3.1.1.2-11266.i386
> rsct.core.utils.msg.zh_TW-3.1.1.2-11266.i386
> rsct.core.utils.msg.zh_TW.Big5-3.1.1.2-11266.i386
42 IBM SmartCloud Orchestrator 2.3: User's Guide
> rsct.core.utils.msg.zh_TW.eucTW-3.1.1.2-11266.i386
> rsct.core.utils.msg.zh_TW.UTF-8-3.1.1.2-11266.i386
> rsct.opt.stackdump-3.1.4.4-13032.i386
> rsct.opt.storagerm-3.1.4.4-13032.i386
> ruby-1.8.7.352-7.el6_2.x86_64
> ruby-devel-1.8.7.352-7.el6_2.x86_64
> rubygems-1.3.7-1.el6.noarch
> ruby-irb-1.8.7.352-7.el6_2.x86_64
> ruby-libs-1.8.7.352-7.el6_2.x86_64
> ruby-rdoc-1.8.7.352-7.el6_2.x86_64
> sam-3.2.2.5-13129.i386
> sam.adapter-3.2.2.5-13129.i386
> sam.msg.de_DE-3.2.2.4-0.i386
> [email protected]
> sam.msg.de_DE.ISO-8859-1-3.2.2.4-0.i386
> sam.msg.de_DE.UTF-8-3.2.2.4-0.i386
> sam.msg.es_ES-3.2.2.4-0.i386
> [email protected]
> sam.msg.es_ES.ISO-8859-1-3.2.2.4-0.i386
> sam.msg.es_ES.UTF-8-3.2.2.4-0.i386
> sam.msg.fr_FR-3.2.2.4-0.i386
> [email protected]
> sam.msg.fr_FR.ISO-8859-1-3.2.2.4-0.i386
> sam.msg.fr_FR.UTF-8-3.2.2.4-0.i386
> sam.msg.it_IT-3.2.2.4-0.i386
> [email protected]
> sam.msg.it_IT.ISO-8859-1-3.2.2.4-0.i386
> sam.msg.it_IT.UTF-8-3.2.2.4-0.i386
> sam.msg.ja_JP.eucJP-3.2.2.4-0.i386
> sam.msg.ja_JP.UTF-8-3.2.2.4-0.i386
> sam.msg.ko_KR.eucKR-3.2.2.4-0.i386
> sam.msg.ko_KR.UTF-8-3.2.2.4-0.i386
> sam.msg.pt_BR-3.2.2.4-0.i386
> sam.msg.pt_BR.UTF-8-3.2.2.4-0.i386
> sam.msg.zh_CN.GB18030-3.2.2.4-0.i386
> sam.msg.zh_CN.GB2312-3.2.2.4-0.i386
> sam.msg.zh_CN.GBK-3.2.2.4-0.i386
> sam.msg.zh_CN.UTF-8-3.2.2.4-0.i386
> sam.msg.zh_TW-3.2.2.4-0.i386
> sam.msg.zh_TW.Big5-3.2.2.4-0.i386
> sam.msg.zh_TW.eucTW-3.2.2.4-0.i386
> sam.msg.zh_TW.UTF-8-3.2.2.4-0.i386
> sam.policies.one-3.2.2.5-13129.i386
> sam.policies.two-3.2.2.5-13129.i386
> sam.sappolicy-3.2.2.5-13129.i386
> scp-chef_repo_srv-2.2.0.0-201311090045.noarch
> scp-cookbooks-2.3.0.0-B20131109005700.noarch
> scrub-2.2-1.el6.x86_64
> scsi-target-utils-1.0.24-2.el6.x86_64
> seabios-0.6.1.2-26.el6.x86_64
> sg3_utils-1.28-4.el6.x86_64
> sgabios-bin-0-0.3.20110621svn.el6.noarch
> smartcloud-2013.1-1.1.ibm.201311080518.noarch
> spice-server-0.12.0-12.el6.x86_64
> sqlite-devel-3.6.20-1.el6.x86_64
> src-3.1.4.4-13032.i386
> src.msg.de_DE-1.3.1.1-11266.i386
> [email protected]
> src.msg.de_DE.ISO-8859-1-1.3.1.1-11266.i386
> src.msg.de_DE.UTF-8-1.3.1.1-11266.i386
> src.msg.es_ES-1.3.1.1-11266.i386
> [email protected]
> src.msg.es_ES.ISO-8859-1-1.3.1.1-11266.i386
> src.msg.es_ES.UTF-8-1.3.1.1-11266.i386
> src.msg.fr_FR-1.3.1.1-11266.i386
> [email protected]
> src.msg.fr_FR.ISO-8859-1-1.3.1.1-11266.i386
Chapter 2. Installing 43
> src.msg.fr_FR.UTF-8-1.3.1.1-11266.i386
> src.msg.it_IT-1.3.1.1-11266.i386
> [email protected]
> src.msg.it_IT.ISO-8859-1-1.3.1.1-11266.i386
> src.msg.it_IT.UTF-8-1.3.1.1-11266.i386
> src.msg.ja_JP.eucJP-1.3.1.1-11266.i386
> src.msg.ja_JP.UTF-8-1.3.1.1-11266.i386
> src.msg.ko_KR.eucKR-1.3.1.1-11266.i386
> src.msg.ko_KR.UTF-8-1.3.1.1-11266.i386
> src.msg.pt_BR-1.3.1.1-11266.i386
> src.msg.pt_BR.UTF-8-1.3.1.1-11266.i386
> src.msg.zh_CN.GB18030-1.3.1.1-11266.i386
> src.msg.zh_CN.GB2312-1.3.1.1-11266.i386
> src.msg.zh_CN.GBK-1.3.1.1-11266.i386
> src.msg.zh_CN.UTF-8-1.3.1.1-11266.i386
> src.msg.zh_TW-1.3.1.1-11266.i386
> src.msg.zh_TW.Big5-1.3.1.1-11266.i386
> src.msg.zh_TW.eucTW-1.3.1.1-11266.i386
> src.msg.zh_TW.UTF-8-1.3.1.1-11266.i386
> syslinux-4.02-8.el6.x86_64
> tftp-server-0.49-7.el6.x86_64
> tunctl-1.5-3.el6.x86_64
> usbredir-0.5.1-1.el6.x86_64
> vgabios-0.6b-3.7.el6.noarch
> xinetd-2.3.14-38.el6.x86_64
> yajl-1.0.7-3.el6.x86_64
> zlib-devel-1.2.3-29.el6.x86_64
Installing a compute node
If you have already deployed the Region Server with KVM type, compute nodes
must be installed on a physical machine. If the machine has no operating system,
use PXE. If the machine already has Red Hat Enterprise Linux 6.3 or 6.4 64-bit
system installed, use the script.
Note: If you have a Region Server, for example, - rs-1 -, with one KVM compute
node added, it is possible to add a second or subsequent nodes to this same
Region Server. However, this is only possible if the compute nodes that are added
are on the same subnet. When adding these additional compute nodes, you can
run the deploy_compute_node.sh script. You do not need to run the
deploy_region_server.sh script again.
All KVM compute nodes must use the same interface to connect to the Region
Server, for example, eth0, eth1, or eth2.
Installing a KVM compute node by PXE
Pre-Boot Execution Environment (PXE) allows a workstation to start from a server
on a network before it runs the operating system on the local hard disk drive. You
can use this method to add a KVM compute node to your network.
Before you begin
The KVM compute node must be a physical machine.
Restriction: PXE does not support a physical machine with SAN storage.
Procedure
1. Make sure that you have already installed a KVM region server and that the
physical machine is PXE-enabled.
44 IBM SmartCloud Orchestrator 2.3: User's Guide
2. On the region server where the KVM compute node must be connected, run
the following command to register the KVM compute node:
/install_images/installer/inst-scripts/register_node.sh
<kvm-host-name> <mac-of-nic> <ip-of-nic>
where:
<kvm-host-name>
Required. Defines the host name that you want to assign to the newly
deployed compute node.
<mac-of-nic>
Required. Defines the MAC address of the NIC that you want to boot
from the PXE.
<ip-of-nic>
Required. Defines the IP address that you want to assign to the newly
deployed compute node.
Note: If the physical node has multiple network devices, choose the device that
connects to the cloud.
3. On the physical node, reboot and change the BIOS settings to ensure it boots
from network.
4. After the physical machine reboots, choose "Choose Compute Node In Disk"
in the prompted menu.
5. On the physical machine, once the operating system has been installed and a
reboot occurs. change the BIOS settings to ensure that the hard disk is the first
boot device.
What to do next
When you have completed this procedure, a SmartCloud Orchestrator with KVM
region was setup successfully. If multiple region are required, see Installing a
multiple-region environment on page 47, otherwise go to Verifying the
installation on page 47.
Note: If you have a region server, for example, - rs-1 -, and it has one KVM
compute node added to it, it is possible to add a second or subsequent nodes to
this same region server. However, this is only possible if the compute nodes that
are added are on the same subnet.
Installing a KVM compute node by script
You can install a KVM compute node using a script.
Before you begin
Make sure that you already have a physical machine with Red Hat Enterprise
Linux 6.3/6.4 64-bit system installed. "Basic Server" is enough to meet the OS
requirement.
Restriction: The compute node and region server must be in the same subnet.
Note:
v Make sure that compute node must be in the same network with the
vm_ip_range specified in region-server.conf.
Chapter 2. Installing 45
v Make sure that compute node operating system is freshly installed and that the
kernel version is consistent with the kernel version of the Region Server.
v Make sure that you have 100 GB in the "/var" partition.
Procedure
1. Make sure that you have already installed a KVM region server.
2. Configure the network with static IP which can be connected to region server.
3. Make sure that the SSHD is enabled and the region server can SSH to it.
4. Edit the /etc/selinux/config file and set the parameter SELINUX=disabled.
5. Reboot the computer.
6. Run the following command to deploy the compute node on region server
where the KVM compute node must be connected:
/install_images/installer/./deploy_compute_node.sh [-h]
<-s <additional node ip> [-p OS root password]
[-n additional-node-name][-e chef-environment]
where:
<-s additional node ip>
Required. Defines the IP address of the KVM compute node.
-p OS root password
Optional. Defines the OS root password to login the additional node. If
it is not indicated here, the command will prompt you for it.
-n additional-node-name
Optional. Defines the name of the KVM compute service that will be
stored in Chef server, the default value is the hostname of your
compute node.
-e chef-environment
Optional. Defines the chef environment of SmartCloud Orchestrator.
Default is production.
What to do next
When you have completed this procedure, a SmartCloud Orchestrator with KVM
region was setup successfully. If multiple region are required, see Installing a
multiple-region environment on page 47, otherwise go to Verifying the
installation on page 47.
Note: If you have a region server, for example, - rs-1 -, and it has one KVM
compute node added to it, it is possible to add a second or subsequent nodes to
this same region server. However, this is only possible if the compute nodes that
are added are on the same subnet. When adding these additional compute nodes,
you can run the deploy_compute_node.sh script. You do not need to run the
deploy_region_server.sh script again.
46 IBM SmartCloud Orchestrator 2.3: User's Guide
Installing a multiple-region environment
You can install SmartCloud Orchestrator in a multiple-region environment.
About this task
A SmartCloud Orchestrator environment must have at least one region server
installed. However, you can install additional region servers. Each region server
can point to any of the supported hypervisor management infrastructures.
Therefore, you can choose whether the regions use the same hypervisor type or
different hypervisor types.
In a multiple-region environment, you can use a single SmartCloud Orchestrator
user interface to deploy your application across multiple providers. For a
high-level overview of the multiple-region structure, see the diagram displayed at
https://www.ibm.com/developerworks/community/wikis/home?lang=en#!/
wiki/IBM%20SmartCloud%20Orchestrator/page/IBM%20SmartCloud
%20Orchestrator%202.3%20topology
Procedure
1. Install SmartCloud Orchestrator with at least one region.
2. Prepare a new region server. For more information, see Preparing the central
server and the region server on page 17.
3. Deploy the new region server. For more information, see Installing the region
server on page 26.
4. Repeat steps 2 and 3 to add the required number of region servers.
Verifying the installation
When you have completed the installation, you can verify it by completing the
verification steps.
Procedure
1. Make sure that the integration of all components is successful by accessing the
SmartCloud Orchestrator user interfaces. To access each user interface, use the
admin user name, and the SmartCloud Orchestrator password specified in
Installing the central server on page 23. Leave the domain name blank, the
default value default is used.
a. To access the main user interface:
1) Open the following URL:
https://$central-server-3_ip
where $central-server-3_ip is the IP address of Central Server 3.
2) Click Configuration > Cloud Group.
3) Find the cloud group with the name that is prefixed with the region
name that you specified in Installing the central server on page 23,
and make sure that the cloud group is connected. When you use
multiple regions, multiple cloud groups should be discovered and
connected. One cloud group corresponds to one region.
b. To access the Virtual Image Library user interface:
1) Open the following URL:
https://$central-server-2_ip:9443/ImageLibraryUI
Chapter 2. Installing 47
where $central-server-2_ip is the IP address of Central Server 2.
2) Click Images > Operational Repositories.
3) Make sure that one repository with the same name as the region name
that you specified in Installing the region server on page 26 is
connected. When you use multiple regions, multiple repositories should
be discovered and connected. One repository corresponds to one region.
c. To access the Business Process Manager user interface, open the following
URL:
https://$central-server-4_ip:9443/ProcessCenter/
where $central-server-4_ip is the IP address of Central Server 4.
For advanced usage of the SmartCloud Orchestrator user interfaces, see
Accessing SmartCloud Orchestrator user interfaces on page 135.
2. Verify the connectivity to the KVM compute node or VMware vCenter or
VMControl, by using the OpenStack command line.
To configure and administer SmartCloud Orchestrator, 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. The environment profile /root/keystonerc is generated on each region
server. Make sure that the OpenStack command-line interface can be executed
by using the profile, as shown in the following example:
a. Run the following command to invoke the profile:
source /root/keystonerc
b. Run the following command to display a list of services:
nova-manage service list
The output should be displayed in the following format. The State of each
service should be :-). Otherwise, the cloud is not ready.
v For a KVM region:
Binary Host Zone Status State Updated_At
nova-scheduler region-server-1 internal enabled :-) 2013-10-10 09:27:57.870300
nova-conductor region-server-1 internal enabled :-) 2013-10-10 09:27:58.027345
nova-consoleauth region-server-1 internal enabled :-) 2013-10-10 09:27:57.547338
nova-cert region-server-1 internal enabled :-) 2013-10-10 09:27:50.464783
nova-compute compute-1 nova enabled :-) 2013-10-10 09:27:53.349208
nova-network compute-1 internal enabled :-) 2013-10-10 09:27:57.227900
v For a VMware or VMControl region:
Binary Host Zone Status State Updated_At
nova-scheduler region-server-1 internal enabled :-) 2013-09-26 07:36:17.428072
nova-conductor region-server-1 internal enabled :-) 2013-09-26 07:36:17.426761
nova-consoleauth region-server-1 internal enabled :-) 2013-09-26 07:36:17.426186
nova-network region-server-1 internal enabled :-) 2013-09-26 07:36:17.428626
nova-cert region-server-1 internal enabled :-) 2013-09-26 07:36:17.424870
nova-smartcloud region-server-1 internal enabled :-) 2013-09-14 19:48:19.691012
nova-compute [email protected] nova_smartcloud enabled :-) 2013-09-14 19:48:19.695301
For more information about the OpenStack command-line interface, see the
OpenStack End User Guide(http://docs.openstack.org/user-guide/content/
index.html).
3. Additional verification steps:
The IaaS Generic REST call makes REST calls to OpenStack services through
the IaaS gateway. You can use the interface to specify the target region and the
service to start. If required, check the status by accessing the
http://$central-server-2_ip:9973/providers URL.
The following information should be displayed:
<serviceCatalog>
<service type="identity" name="keystone">
<endpoint interface="internal" url="<http://172.16.102.182:9973/5177539e9caa42959a2818209754a485/v3"
region="RegionOne" id="5177539e9caa42959a2818209754a485"/>
<endpoint interface="admin" url="<http://172.16.102.182:9973/164a8cf0ad3541438200dcc1f3d81abb/v3"
region="RegionOne" id="164a8cf0ad3541438200dcc1f3d81abb"/>
48 IBM SmartCloud Orchestrator 2.3: User's Guide
<endpoint interface="internal" url="http://172.16.102.182:9973/6836f7dfb3954371bfc9261e40d069e8/v3"
region="Master" id="6836f7dfb3954371bfc9261e40d069e8"/>
<endpoint interface="admin" url="http://172.16.102.182:9973/6bffb3fd97a94b1597fe0b25d7e1493b/v3"
region="Master" id="6bffb3fd97a94b1597fe0b25d7e1493b"/>
<endpoint interface="public" url="http://172.16.102.182:9973/d0ec3a2830b6470d900aa66ede514313/v3"
region="RegionOne" id="d0ec3a2830b6470d900aa66ede514313"/>
<endpoint interface="public" url="http://172.16.102.182:9973/85d0ffc426604dc488dc0c8103fa249b/v3"
region="Master" id="85d0ffc426604dc488dc0c8103fa249b"/>
</service>
</serviceCatalog>
4. To improve the performance of the SmartCloud Orchestrator environment, you
can add both the fully-qualified domain name (FQDN) and the host name of all
the central and region servers to /etc/hosts on all the SmartCloud Orchestrator
server nodes. For example:
cat /etc/hosts on central server 2
127.0.0.1 localhost localhost.localdomain localhost4 localhost4.localdomain4
::1 localhost localhost.localdomain localhost6 localhost6.localdomain6
172.16.34.201 central-server-1.cloud.company.com central-server-1
172.16.34.202 central-server-2.cloud.company.com central-server-2
172.16.34.203 central-server-3.cloud.company.com central-server-3
172.16.34.204 central-server-4.cloud.company.com central-server-4
172.16.34.205 region-server-1.cloud.company.com region-server-1
172.16.34.206 region-server-2.cloud.company.com region-server-2
You can find FQDN by "nslookup" on each server that has the correct
nameserver configured. For example:
[root@central-server-2 ]# nslookup 172.16.34.202
Server: 172.16.34.200
Address: 172.16.34.200#53
201.34.16.172.in-addr.arpa name = central-server-2.cloud.company.com.
[root@central-server-2 ]# cat /etc/resolv.conf
search cloud.company.com company.com
nameserver 172.16.34.200
What to do next
After checking the environment profile and cloud groups, start to use the product
to work with virtual images in your cloud environment. See Chapter 3, Getting
started, on page 131. Make sure that virtual system patterns can be deployed.
Performing advanced configuration tasks
After successful installation of SmartCloud Orchestrator, you can perform
advanced configuration tasks that help you better manage the product.
Setting up virtual machines to install Central Server and
Region Server
Set up the KVM or VMware virtual machines to install the Central Server and
Region Server by using the virt-manager or the vCenter application. You can also
set up the KVM virtual machines by using the command line.
Setting up KVM virtual machines
To set up a KVM virtual machine, install and configure the KVM-related software
and create the virtual machines as described in the following procedures. It is
recommended to use the same operating system version on your Central Server
and Region Server.
Install and configure KVM-related software
Chapter 2. Installing 49
1. Make sure that the KVM-related feature is enabled in the BIOS of your
host machines. The host machines must use either Intel VT or AMD-V
chipsets that support hardware-assisted virtualization. Verify that the
processor supports KVM by running the following command on your
system:
grep -E vmx|svm /proc/cpuinfo
If the command returns output, your system supports KVM.
2. 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 RHEL 6 ISO image stored in
/opt/RHEL6.3-20120613.2-Server-x86_64-DVD1.iso, mount the ISO
image by running the following commands:
mkdir -p /mnt/rhel6
mount -o loop /opt/RHEL6.3-20120613.2-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
3. Install the KVM management packages via yum by running the
following command:
yum install kvm virt-manager libvirt libvirt-python python-virtinst tunctl
4. Configure the network by performing the following steps:
a. Switch to root user.
b. Disable NetworkManager by running the following commands:
chkconfig NetworkManager off
chkconfig network on
service NetworkManager stop
service network start
c. Start the libvirtd service by running the following command:
service libvirtd start
d. 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
50 IBM SmartCloud Orchestrator 2.3: User's Guide
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:
service network restart
d. You can review your interfaces and bridge by running the following
commands:
ifconfig
brctl show
Creating the virtual machines
v By using virt-manager (recommended)
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 allows an easy method for adding
hardware.
v By using the command line
Perform the following steps:
1. Create a base qcow2 image for Central Server and Region Server by
running the following command:
qemu-img create -f qcow2 -o cluster_size=2048k
/home/sco-base.qcow2 200G
2. Creating guests with virt-install, by running the following command:
virt-install --connect=qemu:///system \
--name=sco-base \
--ram=2048 \
--vcpus=2 \
--arch=x86_64 \
--os-type=linux \
--os-variant=rhel6 \
--hvm \
--virt-type kvm \
--cdrom=/opt/RHEL6.3-20120613.2-Server-x86_64-DVD1.iso \
--disk path=/home/sco-base.qcow2,format=qcow2,bus=virtio \
--network bridge=br0,model=virtio \
--accelerate \
--vnc
where
--arch Specifies the bits of the guest operating system. x86_64 is
64-bit and i686 is 32-bit.
--os-variant
Specifies the detailed variant of the guest operating system.
You can get the full list by running the man virt-install
command.
--disk Specifies the virtual disk or disks for installing the guest
operating system. If supported, enable virtio.
--network
Specifies the bridge device name. If supported, enable virtio.
The virt-viewer window is displayed. Follow the steps in the
installation wizard to complete the RHEL installation. Install the
Chapter 2. Installing 51
operating system with base mode. For operating systems that
support virtio, customize the partition layout with only /filesystem.
3. Configure the image file by performing the following steps:
a. Log in to the operating system by using virt-viewer:
virtviewer <ID or name>
For example:
virtviewer sco-base
Run the virsh list --all command to get a list of all the IDs or
names.
b. Disable SELinux by editing the /etc/selinux/config file and
specifying the following value:
SELINUX=disabled
c. Disable the firewall by running the following commands:
service iptables stop
service ip6tables stop
chkconfig iptables off
chkconfig ip6tables off
d. Edit the /etc/hosts file and specify the following value:
# Do not remove the following line, or various programs that require network functionality will fail.
127.0.0.1 localhost.localdomain localhost
e. Edit the /etc/sysconfig/network file and specify the following
value:
NETWORKING=yes
f. Edit the /etc/sysconfig/network-scripts/ifcfg-eth0 file and
specify the following values:
# Intel Corporation 82562GT 10/100 Network Connection
DEVICE=eth0
BOOTPROTO=dhcp
ONBOOT=yes
TYPE=Ethernet
PERSISTENT_DHCLIENT=1
Remove the write net rules by running the following commands:
mv /lib/udev/write_net_rules /lib/udev/write_net_rules.bak
mv /etc/udev/rules.d/70-persistent-net.rules /etc/udev/rules.d/70-persistent-net.rules.bak
mv /lib/udev/rules.d/75-persistent-net-generator.rules
/lib/udev/rules.d/75-persistent-net-generator.rules.bak
g. Shut down the virtual machine by running the following
command:
shutdown -h now
4. Create Central Server and Region Server image files by running the
following command:
qemu-img create -b <path>/sco-base.qcow2 -f qcow2 -F qcow2 <path>/<SERVER_NAME>.qcow2
5. Create XML templates file called <SERVER_NAME>.xml for Central
Server and Region Server with the following content:
<domain type=kvm>
<name>SERVER_NAME</name>
<memory unit=KiB>SERVER_RAM</memory>
<currentMemory unit=KiB>SERVER_RAM</currentMemory>
<vcpu placement=static>CPU_NUM</vcpu>
<os>
<type arch=x86_64>hvm</type>
<boot dev=hd/>
</os>
<features>
<acpi/>
<apic/>
</features>
52 IBM SmartCloud Orchestrator 2.3: User's Guide
<clock offset=localtime/>
<on_poweroff>destroy</on_poweroff>
<on_reboot>restart</on_reboot>
<on_crash>restart</on_crash>
<devices>
<emulator>/usr/libexec/qemu-kvm</emulator>
<disk type=file device=disk>
<driver name=qemu type=qcow2 cache=none/>
<source file=IMAGE_PATH/>
<target dev=vda bus=virtio/>
</disk>
<controller type=ide index=0>
<address type=pci domain=0x0000 bus=0x00 slot=0x01 function=0x1/>
</controller>
<controller type=usb index=0>
<address type=pci domain=0x0000 bus=0x00 slot=0x01 function=0x2/>
</controller>
<interface type=bridge>
<source bridge=br0/>
<model type=virtio/>
<address type=pci domain=0x0000 bus=0x00 slot=0x03 function=0x0/>
</interface>
<serial type=pty>
<target port=0/>
</serial>
<console type=pty>
<target type=serial port=0/>
</console>
<input type=tablet bus=usb/>
<input type=mouse bus=ps2/>
<graphics type=vnc port=-1 autoport=yes/>
<video>
<model type=cirrus vram=9216 heads=1/>
<address type=pci domain=0x0000 bus=0x00 slot=0x02 function=0x0/>
</video>
<memballoon model=virtio>
<address type=pci domain=0x0000 bus=0x00 slot=0x06 function=0x0/>
</memballoon>
</devices>
</domain>
Note: To define the SERVER_RAM and CPU_NUM values for each server,
see Hardware prerequisites on page 13. Replace SERVER_NAME and
IMAGE_PATH with the actual values.
6. Create the virtual machines by using the generated XML files by
running the following commands:
virsh define <IMAGE_PATH>/<SERVER_NAME>.xml
virsh start <SERVER_NAME>
7. Create a volume and attach the volume to Central Server 2 by
performing the following steps:
a. Run the following command:
qemu-img create -f qcow2 -o cluster_size=2048k
/hbase-disk.qcow2 5G
b. Create the attach_device.xml file with the following content:
<disk type=block device=disk>
<driver name=qemu type=qcow2/>
<source dev=<path>/hbase-disk.qcow2/>
<target dev=vdb bus=virtio/>
</disk>
c. Run the following command:
virsh attach-device <Central_Server_2_domain_ID> attach_device.xml
After setting up the KVM virtual machines to install the Central Server and Region
Server, start the virtual machine configuration by following the procedure
described in Preparing the central server and the region server on page 17.
Chapter 2. Installing 53
Setting up VMware virtual machines
VMware vCenter Server provides a centralized platform for managing your
VMware vSphere environments. You can automate and deliver a virtual
infrastructure. vCenter Server also supports the high availability solution. For more
information, see the VMware documentation.
After setting up the VMware virtual machines to install the Central Server and
Region Server, start the virtual machine configuration by following the procedure
described in Preparing the central server and the region server on page 17.
Managing networks
SmartCloud Orchestrator uses VLAN network that is also compatible with flat
interface. By default, the network is created according to the vm_ip_range
parameter in the region-server.cfg file while deploying the region server. If you
want to organize and manage instances with different networks, you can create
and configure more networks for SmartCloud Orchestrator.
Creating a network for a KVM region
There are two types of network for a KVM region.
Creating a VLAN-based network:
This topic describes how to create a VLAN-based network for SmartCloud
Orchestrator.
Before you begin
v Plan your network before you create a virtual machine, so that you reserve the
required IP addresses for the compute nodes.
v You cannot create multiple networks with overlapping IP ranges.
v The GATEWAY_IP must exist and belong to X.X.X.X/YY.
v You must configure the VLAN ID on the switch as a trunk.
v All KVM compute nodes must use the same interface to connect to the Region
Server, for example, eth0, eth1, or eth2.
Procedure
1. To create a network, run the following command on one line:
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
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
The bridge_interface parameter is the interface that all compute nodes must
use to connect to the Region Server. The compute node does not create the
VLAN or bridge until a virtual machine is deployed.
2. 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 each
compute node:
54 IBM SmartCloud Orchestrator 2.3: User's Guide
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
3. Stop all dnsmasq services and restart the openstack-nova-network on the Region
Server or compute node:
killall dnsmasq
service openstack-nova-network restart
4. Decide which IP addresses you need to reserve. Reserve an IP address range
for the compute nodes, and use unreserved IP addresses for virtual machines.
For example, if the VLAN network is 192.0.2.0./22 and you plan to install 70
compute nodes, you reserve the IP address range 192.0.2.3 through
192.0.2.72 for the compute nodes, as follows:
a. Connect to the nova database.
b. In the fixed IPs table, update the reserved and host field for each IP
address that you want to reserve. For example, rtpvc11-01-bc01bld01 is a
newly installed compute node that does not host any virtual machine. To
reserve IP address 192.0.2.3 for compute node rtpvc11-01-bc01bld01, run
the following command:
db2 => update fixed_ips set host=rtpvc11-01-bc01bld01, reserved=1
where address=192.0.2.3 and deleted = 0
If you create a virtual machine host on this compute node, the IP address is
192.0.2.3.
c. Reserve IP addresses for the compute nodes that you plan to add in the
future. For example, to reserve the IP address range 192.0.2.73 through
192.0.2.150, run the following command:
db2 => update fixed_ips set reserved=1 where address >192.0.2.72 and
address < 192.0.2.151 and deleted = 0
You can then use the IP address range 192.0.2.151 through 192.0.2.254 for
the virtual machines.
5. To reserve an IP address, you have the following options:
v Option 1: Reserve the IP address via the nova command on the region server
to reserve an IP address which cannot be used by SmartCloud Orchestrator:
nova fixed-ip-reserve <fixed_ip>.
v Option 2: Update the database directly if there are too many fixed IP
addresses that need to be reserved. If there are some IP addresses in the
X.X.X.X/YY range and you do not want them to be used by SmartCloud
Orchestrator, you can exclude them. For example, to exclude the IP addresses
10.10.10.0-10.10.10.20, run the following commands:
db2 => connect to openstac
Database Connection Information
Database server = DB2/LINUXX8664 10.1.2
SQL authorization ID = DB2INST1
Local database alias = OPENSTACdb2
db2 => select schemaname from syscat.schemata
SCHEMANAME
------------------------------------------------
CIR14447
GLE14447
NOA14447
NULLID
SCE14447
Chapter 2. Installing 55
SQLJ
SYSCAT
SYSFUN
SYSIBM
SYSIBMADM
SYSIBMINTERNAL
SYSIBMTS
SYSPROC
SYSPUBLIC
SYSSTAT
SYSTOOLS
16 record(s) selected.
Find the user for nova, here it is NOA14447.
db2 => connect to openstac user $username using $password_for_db2
Database Connection Information
Database server = DB2/LINUXX8664 10.1.2
SQL authorization ID = NOA14447
Local database alias = OPENSTAC
Find the corresponding ID numbers for the reserved IPs.
db2 => select * from fixed_ips where ADDRESS=10.10.10.0
CREATED_AT UPDATED_AT DELETED_AT ID ADDRESS NETWORK_ID ALLOCATED LEASED RESERVED VIRTUAL_INTERFACE_ID
-------------------------- ----------- ----------- ---- ----------- ----------- --------- ------ -------- --------------------
2013-09-23-19.03.58.894240 - - 11 10.10.10.0 1 0 0 0 -
HOST INSTANCE_UUID DELETED
------- -------------- -------
- - 0
1 record(s) selected.
db2 => select * from fixed_ips where ADDRESS=10.10.10.20
CREATED_AT UPDATED_AT DELETED_AT ID ADDRESS NETWORK_ID ALLOCATED LEASED RESERVED VIRTUAL_INTERFACE_ID
-------------------------- ----------- ----------- ---- ----------- ----------- --------- ------ -------- --------------------
2013-09-23-19.03.58.951306 - - 32 10.10.10.20 1 0 0 0 -
HOST INSTANCE_UUID DELETED
------- -------------- -------
- - 0
1 record(s) selected.
Here we can see the ID numbers for the IP addresses 10.10.10.0-10.10.10.20
is 11-32. Update the database to reserve the IP addresses 10.10.10.0-
10.10.10.20 using the following command:
db2 => update fixed_ips set reserved=1 where id>10 and id<33
DB20000I The SQL command completed successfully.
6. Update DNS with the new network information. Run the following commands:
db2 => update NETWORKS set dns1=X.X.X.X, dns2=X.X.X.X
DB20000I The SQL command completed successfully.
where:
v The value X.X.X.X can be your DNS server or IP address of the Region
Server.
What to do next
Proceed to Configuring DNS for the Workload Deployer IP groups on page 61.
56 IBM SmartCloud Orchestrator 2.3: User's Guide
Creating a flat network:
You can create a flat network for workstations that are directly connected to each
other.
Procedure
1. Create a bridge. 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
2. 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.
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
3. 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.
4. 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
5. Configure the nodes to use the new gateway. Run the following commands on
the Region Server and each compute node:
echo "dhcp-option=tag:newnet,option:router,NEWNET_GW" >>
/etc/dnsmasq.d/nova.gateway
echo "domain=DNS_SUFFIX,X.X.X.X/YY" >> /etc/dnsmasq.d/nova.domain
6. To reserve an IP address, you have the following options:
Chapter 2. Installing 57
v Option 1: Reserve the IP address via the nova command on the region server
to reserve an IP address which cannot be used by SmartCloud Orchestrator:
nova fixed-ip-reserve <fixed_ip>.
v Option 2: Update the database directly if there are too many fixed IP
addresses that need to be reserved. If there are some IP addresses in the
X.X.X.X/YY range and you do not want them to be used by SmartCloud
Orchestrator, you can exclude them. For example, to exclude the IP addresses
10.10.10.0-10.10.10.20, run the following commands:
db2 => connect to openstac
Database Connection Information
Database server = DB2/LINUXX8664 10.1.2
SQL authorization ID = DB2INST1
Local database alias = OPENSTACdb2
db2 => select schemaname from syscat.schemata
SCHEMANAME
------------------------------------------------
CIR14447
GLE14447
NOA14447
NULLID
SCE14447
SQLJ
SYSCAT
SYSFUN
SYSIBM
SYSIBMADM
SYSIBMINTERNAL
SYSIBMTS
SYSPROC
SYSPUBLIC
SYSSTAT
SYSTOOLS
16 record(s) selected.
Find the user for nova, here it is NOA14447.
db2 => connect to openstac user $username using $password_for_db2
Database Connection Information
Database server = DB2/LINUXX8664 10.1.2
SQL authorization ID = NOA14447
Local database alias = OPENSTAC
Find the corresponding ID numbers for the reserved IPs.
db2 => select * from fixed_ips where ADDRESS=10.10.10.0
CREATED_AT UPDATED_AT DELETED_AT ID ADDRESS NETWORK_ID ALLOCATED LEASED RESERVED VIRTUAL_INTERFACE_ID
-------------------------- ----------- ----------- ---- ----------- ----------- --------- ------ -------- --------------------
2013-09-23-19.03.58.894240 - - 11 10.10.10.0 1 0 0 0 -
HOST INSTANCE_UUID DELETED
------- -------------- -------
- - 0
1 record(s) selected.
db2 => select * from fixed_ips where ADDRESS=10.10.10.20
CREATED_AT UPDATED_AT DELETED_AT ID ADDRESS NETWORK_ID ALLOCATED LEASED RESERVED VIRTUAL_INTERFACE_ID
-------------------------- ----------- ----------- ---- ----------- ----------- --------- ------ -------- --------------------
2013-09-23-19.03.58.951306 - - 32 10.10.10.20 1 0 0 0 -
HOST INSTANCE_UUID DELETED
------- -------------- -------
- - 0
1 record(s) selected.
58 IBM SmartCloud Orchestrator 2.3: User's Guide
Here we can see the ID numbers for the IP addresses 10.10.10.0-10.10.10.20
is 11-32. Update the database to reserve the IP addresses 10.10.10.0-
10.10.10.20 using the following command:
db2 => update fixed_ips set reserved=1 where id>10 and id<33
DB20000I The SQL command completed successfully.
7. Update DNS with the new network information. Run the following commands:
db2 => update NETWORKS set dns1=X.X.X.X, dns2=X.X.X.X
DB20000I The SQL command completed successfully.
where:
v The value X.X.X.X can be your DNS server or IP address of the Region
Server.
You might need to update dhcp_start for your network in mysql:
db2 => update networks set dhcp_start=X.X.X.X where uuid=XXXXXXXX
8. Optional but recommended. It is better to have the IP range well planned for
usage, for example, explicitly reserve the 10 IP addresses for the compute
nodes:
db2 => update fixed_ips set host=compute_name_1 where address=10.10.10.21
db2 => update fixed_ips set host=compute_name_2 where address=10.10.10.22
...
db2 => update fixed_ips set host=compute_name_10 where address=10.10.10.30
9. 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.
What to do next
Proceed with Configuring DNS for the Workload Deployer IP groups on page
61.
Creating a network for a VMware or Power region
This topic describes how to create a network for a VMware or Power region.
About this task
To create a network for a VMware or Power region, you must run the following
command on the region server:
/install_image/installer/scripts/ ./config_network.sh -d $database_password -p $password
-t $region_type -r $vm_ip_range -m $vm_ip_netmask -g $vm_gateway -H $host
-U $username -N $network -P $port
where:
-d db2_password
Defines the password of the database.
-p password
Defines the password of the administrator of the VMware (or Power)
vCenter VMControl.
-t region_type
Specifies one of region types (vmware/power)
Chapter 2. Installing 59
-r vm_ip_range
Defines the IP addresses for provisioned virtual machines.
-m vm_ip_netmask
Defines the netmask of vm_ip_range.
-g vm_gateway
Defines the gateway IP address for vm_ip_range.
-H host
Defines the hostname or IP address of vCenter/VMControl.
-U username
Defines the user name of the administrator of vCenter/VMControl.
Note: SmartCloud Orchestratordoes not support Domain User Account for
vCenter.
-N network
Defines the network name defined in vCenter/VMControl.
-P port
Defines the port to connect to vCenter/VMControl (the default is: 443)
For example, if your vCenter is 10.10.0.5 with username Administrator and
password mypassword, you can create a new network for VMware region by
running the following command:
./config_network.sh -d passw0rd -p mypassword -t vmware -r 10.10.0.20-10.10.0.30
-m 255.255.255.0 -g 10.10.0.1 -H 10.10.0.5 -U Administrator -N VM Network -P 443
What to do next
(Optional) To reserve an IP address in the database, you have the following
options:
v Option 1: Reserve the IP address via the nova command on the region server to
reserve an IP address which cannot be used by SmartCloud Orchestrator: nova
fixed-ip-reserve <fixed_ip>.
v Option 2: Update the database directly if there are too many fixed IP addresses
that need to be reserved. If there are some IP addresses in the X.X.X.X/YY range
and you do not want them to be used by SmartCloud Orchestrator, you can
exclude them. For example, to exclude the IP addresses 10.10.10.0-10.10.10.20,
run the following commands:
db2 => connect to openstac
Database Connection Information
Database server = DB2/LINUXX8664 10.1.2
SQL authorization ID = DB2INST1
Local database alias = OPENSTACdb2
db2 => select schemaname from syscat.schemata
SCHEMANAME
------------------------------------------------
CIR14447
GLE14447
NOA14447
NULLID
SCE14447
SQLJ
SYSCAT
SYSFUN
60 IBM SmartCloud Orchestrator 2.3: User's Guide
SYSIBM
SYSIBMADM
SYSIBMINTERNAL
SYSIBMTS
SYSPROC
SYSPUBLIC
SYSSTAT
SYSTOOLS
16 record(s) selected.
Find the user for nova, here it is NOA14447.
db2 => connect to openstac user $username using $password_for_db2
Database Connection Information
Database server = DB2/LINUXX8664 10.1.2
SQL authorization ID = NOA14447
Local database alias = OPENSTAC
Find the corresponding ID numbers for the reserved IPs.
db2 => select * from fixed_ips where ADDRESS=10.10.10.0
CREATED_AT UPDATED_AT DELETED_AT ID ADDRESS NETWORK_ID ALLOCATED LEASED RESERVED VIRTUAL_INTERFACE_ID
-------------------------- ----------- ----------- ---- ----------- ----------- --------- ------ -------- --------------------
2013-09-23-19.03.58.894240 - - 11 10.10.10.0 1 0 0 0 -
HOST INSTANCE_UUID DELETED
------- -------------- -------
- - 0
1 record(s) selected.
db2 => select * from fixed_ips where ADDRESS=10.10.10.20
CREATED_AT UPDATED_AT DELETED_AT ID ADDRESS NETWORK_ID ALLOCATED LEASED RESERVED VIRTUAL_INTERFACE_ID
-------------------------- ----------- ----------- ---- ----------- ----------- --------- ------ -------- --------------------
2013-09-23-19.03.58.951306 - - 32 10.10.10.20 1 0 0 0 -
HOST INSTANCE_UUID DELETED
------- -------------- -------
- - 0
1 record(s) selected.
Here we can see the ID numbers for the IP addresses 10.10.10.0-10.10.10.20
is 11-32. Update the database to reserve the IP addresses 10.10.10.0-
10.10.10.20 using the following command:
db2 => update fixed_ips set reserved=1 where id>10 and id<33
DB20000I The SQL command completed successfully.
Proceed with what documented in Configuring DNS for the Workload Deployer
IP groups.
Configuring DNS for the Workload Deployer IP groups
Configure the Workload Deployer IP groups to be able to resolve host name.
About this task
The following configuration applies to:
v SmartCloud Orchestrator uses a built-in DNS (standalone environment).
v SmartCloud Orchestrator uses a built-in DNS but with the corporate DNS being
the parent DNS.
On central server 1, run:
/install_image/installer/scripts/delegate_region.sh <region name> <region ip> [vm_ip_range]
where
Chapter 2. Installing 61
v region-name is a required parameter. The region name of the new added
network.
v region ip is a required parameter. The ip address of the region server.
v vm_ip_range is an optional parameter, required for new added networks. The IP
range of the new added network. For example, 10.10.10.100-10.10.10.200.
For SmartCloud Orchestrator that uses the corporate DNS and no built-in DNS,
refer to Preparing the central server and the region server on page 17 for manual
work.
Deleting the existing networks
The commands can be used to disassociate the project from the network, delete an
existing network, or delete the virtual machines that belong to it.
Procedure
v To delete all virtual machines in the network through GUI or CLI, run:
nova delete xxxx
v To disassociate the project from the network, run:
nova-manage network modify x.x.x.x/yy --disassociate-project
v To delete a network, run:
nova-manage network delete x.x.x.x/yy
v 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
Shutting down or starting Central Servers and Region Servers
This topic describes how to shut down or start Central Servers and Region Servers.
To shut down the Central Servers and the Region Servers, follow this order:
1. Shut down Central Server 1.
2. Shut down Central Server 2.
3. Shut down Central Server 3.
4. Shut down Central Server 4.
5. Shut down the Region Servers.
To start the Central Servers and the Region Servers, follow these steps:
1. Start Central Server 1.
2. Make sure that all services are started on Central Server 1, you can run this
command to check this:
# netstat -tnlp | grep 5000
if the output of the command is like the following, then you can proceed:
# netstat -tnlp | grep 5000
tcp 0 0 0.0.0.0:50000 0.0.0.0:* LISTEN 6856/db2sysc 0
3. Start Central Server 2.
4. Start Central Server 3.
5. Start Central Server 4.
62 IBM SmartCloud Orchestrator 2.3: User's Guide
6. Start the Region Servers.
To reboot the Central Servers and the Region Servers, follow these steps:
1. Reboot Central Server 1.
2. Make sure that all services are started on Central Server 1, you can run this
command to check this:
# netstat -tnlp | grep 5000
if the output of the command is like the following, then you can go next:
# netstat -tnlp | grep 5000
tcp 0 0 0.0.0.0:50000 0.0.0.0:* LISTEN 6856/db2sysc 0
3. Reboot Central Server 2.
4. Reboot Central Server 3.
5. Reboot Central Server 4.
6. Reboot the Region Servers.
Integrating SmartCloud Orchestrator with VMware vCenter
Integrate your SmartCloud Orchestrator environment with VMware vCenter to
effectively manage your cloud environment based on VMware ESX Systems.
Before you begin
Restriction: Metadata service is not supported in a VMware environment.
About this task
After OpenStack SmartCloud Extension has been deployed, you can use the CLI to
configure SmartCloud Orchestrator to connect to the existing vCenter.
Procedure
1. Make sure that the OpenStack services are running, including the SmartCloud
service.
2. Create a vCenter backend connection for SmartCloud:
a. Verify that the source file works in the OpenStack environment:
# cd /opt/ibm/openstack/iaas/smartcloud/bin
# source ~/keystonerc
b. Add an existing vCenter environment:
#/opt/ibm/openstack/iaas/smartcloud/bin/nova-cloud-create
[--os-region-name <region-name>] <os-hostname> <name>
<hostname> <username> <password> <type>[<port>]
where:
<os-hostname>
Fully qualified host name where the OpenStack SmartCloud driver
is running, normally the output of hostname --fqdn.
<name>
The cloud name. The cloud name must be unique across a region.
<hostname>
Host name or IP address of the vCenter or VMControl system.
<username>
User name of the administrator for the system.
Chapter 2. Installing 63
<password>
Password of the administrator for the system.
<type>
Region type. Either VMware or VMControl.
<port>
Optional. Port to connect to the system (defaults: type VMware 443
and VMControl 8422).
<region-name>
Optional. The OpenStack region name. Must be the first in the
command argument.
Example:
# /opt/ibm/openstack/iaas/smartcloud/bin/nova-cloud-create
rs-34-1.customer.ibm.com RegionVMW 172.16.133.254
Administrator password VMware 443
c. Verify that the vCenter backend connection for SmartCloud:
# /opt/ibm/openstack/iaas/smartcloud/bin/nova-cloud-show
{"username": "administrator"
"jmsPort": 61617
"name": "RegionVMW"
"hostname": "172.16.133.254"
"port": 443
"state":
{"id": "OK"
"label": "OK"}
"cloudType": "VMware"
"timeout": 600
"external_uri": "172.16.133.254:443"
"id": "rs-34-1:301"
"description": "OpenStack managed VMware"}
3. Match nova-network with VMware hypervisor networks queried from vCenter:
a. Check if the existing nova-network IP addresses are available for the
VMware deployment. If not, create a workable network. For example:
# nova-manage network create --fixed_range_v4=172.16.133.0/24 --label vm-network --bridge=br4090
# nova-manage network list
id IPv4 IPv6 start addres DNS1 DNS2 VlanID project uuid
1 172.16.133.0/24 None 172.16.133.10 172.16.34.200 172.16.34.205 None None
83d7f72a-3b03-48c5-a6fa-19be15daae18
Note: For more information about the OpenStack command-line interface,
see the OpenStack End User Guide.
b. Get the available networks list from vCenter:
# ./opt/ibm/openstack/iaas/smartcloud/bin/nova-netext-show [--os-region-name <region-name>[raw]
where:
<cloud name>
Name of the cloud. All clouds can be listed with nova-cloud-show.
[region-name]
Optional. The OpenStack region name. Must be the first in the
command argument.
[raw] Optional. Show the output in raw JSON form.
Example:
#/opt/ibm/openstack/iaas/smartcloud/bin/nova-netext-show RegionVMW
{"enableDhcpV6": false
64 IBM SmartCloud Orchestrator 2.3: User's Guide
"activeDirectoryPassword": null
"name": "VM Network"
"domainName": null
"computerNamePrefix": null
"networkName": "VM Network"
"cloudId": "rs-34-1:301"
"activeDirectory": null
"wins2": null
"hostnamePrefix": null
"enableDhcp": false
"wins1": null
"cloudType": "VMware"
"activeDirectoryUser": null
"osNetworkId": "83d7f72a-3b03-48c5-a6fa-19be15daae18"
"id": "2792e082-a1db-4033-81c5-740d0e8200b3"
"workgroup": null}
c. Match the target hypervisor network with nova network.
# ./nova-netext-match [--os-region-name <region-name>] <cloud name>
<network_name>
<nova_network_id> [domainName]
where:
<cloud name>
Name of the cloud. All clouds can be listed with nova-cloud-show.
<network name>
Name of the network extension. All network extensions are listed by
cloud with nova-netext-show.
<nova network id>
The network ID list in nova.
[domain name]
Optional. Domain name applied to virtual servers on this network.
[region-name]
Optional. The OpenStack region name. Must be the first in the
command argument.
# ./nova-netext-match RegionVMW "VM Network" 83d7f72a-3b03-48c5-a6fa-19be15daae18
{"networkExtension": {"enableDhcpV6": false, "activeDirectoryPassword": null, "name": "VM Network",
"domainName": null, "computerNamePrefix": null, "networkName": "VM Network", "cloudId":
"rs-34-1:301",
"activeDirectory": null, "wins2": null, "hostnamePrefix": null, "enableDhcp": false, "wins1": null,
"cloudType": "VMware", "activeDirectoryUser": null, "osNetworkId":
"83d7f72a-3b03-48c5-a6fa-19be15daae18",
"id": "2792e082-a1db-4033-81c5-740d0e8200b3", "workgroup": null}}
4. Verify the connectivity to vCenter. Verify the configuration. Check if the virtual
machine template has been synchronized as image in Glance by comparing the
list with the virtual machine templates showing in the vCenter:
> glance index
ID Name Disk Format Container FormatSize
------------------------------------ -------------------- ---------------------------------
af53c607-f9e9-4048-b6ee-55d8c62fef39 win2k8r2ee raw ovf 0
f0f676f4-98ef-445a-b685-966252b99141 takeover-248 raw ovf 0
45c8d691-fc1c-447b-8ae7-e7e5cc127d5b SCE Default Image raw ovf 0
Check if the virtual machine has been synchronized as server in nova by
comparing the list with the virtual machines showing in the vCenter:
> nova list
+--------------------------------------+-------------------+---------+----------+
| ID | Name | Status | Networks |
+--------------------------------------+-------------------+---------+----------+
| 8a2172a3-0a22-4403-97aa-23e0fc72ae94 | hilltest | ACTIVE | |
Chapter 2. Installing 65
| b398a87f-8db6-40c4-b6d4-fbcb9c34a5ae | q3 | ACTIVE | |
| f3ee86e1-8804-455c-8a4f-83ef98064bb8 | takeover-demo-248 | SHUTOFF | |
| d83940fb-0c94-45f0-8364-f6f1c5e7db60 | vCentGMN | ACTIVE | |
+--------------------------------------+-------------------+---------+----------+
Restriction: SCE Default Image is used to provide details for instances that
have no information about the images that created them. You cannot use the
image to deploy a virtual machine, but do not delete it.
5. Boot a server:
> nova boot --image af53c607-f9e9-4048-b6ee-55d8c62fef39 --flavor m1.tiny mytest
Note: The Virtual Machine template in vCenter must be installed with
VMware-tools. This is mandatory if you want to use this template to boot
servers from OpenStack.
Note: The virtual machine template must have the operating system
successfully installed.
Note: The flavor value must be bigger than the virtual machine template size
or use m1.tiny which is to match the template size.
6. Configure the Virtual Image Library for VMware (see Configuring Virtual
Image Library for VMware on page 305).
7. Additional CLIs:
v /opt/ibm/openstack/iaas/smartcloud/bin/nova-cloud-delete <cloud id>
where cloud id is the ID of the cloud to delete. Use nova-cloud-show to find
the ID.
v /opt/ibm/openstack/iaas/smartcloud/bin/nova-cloud-delete-byname <cloud name>
where cloud name is the name of the cloud to delete. Use nova-cloud-show to
find the name.
v nova-cloud-pingtest <hostname> <username> <password>
<type> [port]
where hostname is the name of the vCenter system, username is the username
of the system administrator, password is the administrator's password, type is
either VMware or VMControl, [port is the port to connect to the system
(defaults: type VMware 443).
v nova-netext-unset <cloud name> <network name> <nova network id>
where cloud name is the name of the cloud (all clouds can be listed with
nova-cloud-show), network name is the name of the network (all networks can
be listed with nova-netext-show).
Integrating SmartCloud Orchestrator with VMControl
Integrate your SmartCloud Orchestrator environment with IBM Systems Director
VMControl to effectively manage your cloud environment based on IBM Power
Systems
.
About this task
After OpenStack SmartCloud Extension has been deployed, you can use the CLI to
configure SmartCloud Orchestrator to connect to the existing VMControl.
66 IBM SmartCloud Orchestrator 2.3: User's Guide
Procedure
1. It is necessary to upgrade the Director/VMControl or Flex System Manager
(FSM) to the IBM Director 6.3.3.1, which ships with VMControl 2.4.3.1.
However, SmartCloud Orchestrator requires an additional VMControl APAR
that needs to be loaded on top of VMControl 2.4.3.1 This fix is bundled with
SmartCloud Orchestrator inside the VMControl-upgrade directory. The
vmc-update.2.4.3.1-201310251457-IC97186.zip file is for the standalone
Director/VMControl environment and the fsmfix_vmc-update.2.4.3.1-
201310251457-IC97186.zip is for the Flex System Manager (FSM). These files
must be copied over to the VMC/FSM server and be decompressed there.
From there, you can use the Director UI to install the updates or use the CLI as
follows:
smcli importupd -v -r <directory_of_decompressed_contents>
smcli lsupd *IC96480
(which should return something similar to the following
three lines:
confirm thatthose updates were imported to the Director
upgrade manager):
com.ibm.ensemble.local.mgmt.feature_2.4.3.1-201309300916- IC96480
com.ibm.vmcontrol.rf.power.feature_2.4.3.1-201309300916-
IC96480
com.ibm.vmcontrol.services.feature_2.4.3.1-201309300916-
IC96480
smcli installneeded (this drives the install of those updates into director )
Once finished, one must restart Director after this installation using the smstop
and smstart commands.
2. Make sure that the OpenStack services are running, including the SmartCloud
service.
3. Create a VMControl backend connection for SmartCloud.
a. Verify that the source file works in the OpenStack environment:
# cd /opt/ibm/openstack/iaas/smartcloud/bin
# source ~/keystonerc
b. Add an existing VMControl environment:
# ./nova-cloud-create [--os-region-name <region-name>] <openstack-hostname>
<cloud_name> <VMControl-hostname> <VMControl-username>
<VMControl-password> <type> [port]
where:
<region-name>
Optional. The OpenStack region name. If specified, this argument
must be the first argument in the command.
<openstack-hostname>
The name of the host where the OpenStack SmartCloud driver is
running. This value must be the same as the result returned by the
hostname command.
<cloud_name>
The cloud name. This name must be unique across a region.
<VMControl-hostname>
The host name or IP address of the VMControl system.
<VMControl-username>
The user name of the administrator of the VMControl system.
<VMControl-password>
The password of the administrator of the VMControl system.
Chapter 2. Installing 67
<type> The type of system. Specify VMControl.
[port] Optional. The port to connect to the VMControl system. The default
port for VMControl is 8422.
Example:
# ./nova-cloud-create sco-vmw-29-fb vmcontrol 172.16.22.6
root object00 VMControl
{ "cloud":{ "driver":"sco-vmw-29-fb", "name":"vmcontrol",
"description":"OpenStack managed VMControl",
"hostname":"172.16.22.6",
"username":"root", "password":"object00", "type":"VMControl",
"port":8422, "version":"2.4.3.x"} }
{"cloud": {"username": "root", "jmsPort": 61617, "name": "vmcontrol",
"hostname": "172.16.22.6", "port": 8422, "version": "2.4.3.x",
"timeout": 600, "cloudType": "VMControl", "id":
"sco-vmw-29-fb:301",
"description": "OpenStack managed VMControl"}}
{ "cloud":{ "cloudId":"sco-vmw-29-fb:301", "name":"vmcontrol",
"description":"OpenStack managed VMControl",
"hostname":"172.16.22.6",
"username":"root", "password":"object00",
"type":"VMControl", "port":8422} }
4. Match nova-network with Power hypervisor networks queried from
VMControl.
a. Check whether the existing nova-network IP addresses are available for the
Power LPAR deployment. If not, create a workable network. Here the
network 172.17.40.0/22 does not work for Power LPAR deployment.
# ./nova-manage network list
id IPv4 IPv6 start address DNS1
1 172.17.40.0/22 None 172.17.41.230 172.17.41.224
DNS2 VlanID project uuid
172.17.41.224 None None 215b4dfa-11f4-47d5-872d-4e0620057b16
# nova-manage network create --fixed_range_v4 172.16.22.0/24 --gateway 172.16.22.1
--dns1 172.17.41.224 --label vmcnet --fixed_cidr 172.16.22.224/28 --bridge br4090
# nova-manage network list
id IPv4 IPv6 start address DNS1
1 172.17.40.0/22 None 172.17.41.230 172.17.41.224
2 172.16.22.0/24 None 172.16.22.2 172.17.41.224
DNS2 VlanID project uuid
172.17.41.224 None None 215b4dfa-11f4-47d5-872d-e0620057b16
None None None 365a1ab0-94e2-40a5-8601-d98c3584536f
b. Get the available networks list from VMControl.
# ./nova-netext-show [--os-region-name <region-name>] <cloud_name> [raw]
where:
<region-name>
Optional. The OpenStack region name. If specified, this argument
must be the first argument in the command.
<cloud_name>
The cloud name. To show all cloud names, use the nova-cloud-show
command.
[raw] Show the output in raw JSON format.
Example:
# ./nova-netext-show vmcontrol
{"enableDhcpV6": false
"activeDirectoryPassword": null
"name": "Discovered/99/0/ETHERNET0 (VLAN 99
68 IBM SmartCloud Orchestrator 2.3: User's Guide
Not Bridged)"
"domainName": null
"computerNamePrefix": null
"networkName": "Discovered/99/0/ETHERNET0"
"cloudId": "sco-vmw-29-fb:301"
"activeDirectory": null
"wins2": null
"hostnamePrefix": null
"enableDhcp": false
"wins1": null
"cloudType": "VMControl"
"activeDirectoryUser": null
"osNetworkId": null
"id": "5c411f0d-ac77-4dce-807a-b849de6d928a"
"workgroup": null}
{"enableDhcpV6": false
"activeDirectoryPassword": null
"name": "Discovered/1/0/ETHERNET0 (VLAN 1
Bridged)"
"domainName": null
"computerNamePrefix": null
"networkName": "Discovered/1/0/ETHERNET0"
"cloudId": "sco-vmw-29-fb:301"
"activeDirectory": null
"wins2": null
"hostnamePrefix": null
"enableDhcp": false
"wins1": null
"cloudType": "VMControl"
"activeDirectoryUser": null
"osNetworkId": null
"id": "1c94bf17-6499-416a-8e4f-4391e4105fa6"
"workgroup": null}
c. Match the target hypervisor network with nova network.
# ./nova-netext-match [--os-region-name <region-name>] <cloud name>
<network_name> <nova_network_id> [domainName]
where:
<region-name>
Optional. The OpenStack region name. If specified, this argument
must be the first argument in the command.
<cloud_name>
The cloud name. To show all cloud names, use the nova-cloud-show
command.
<network_name>
The name of the network extension. To list all network extensions
by cloud, use the nova-netext-show command.
<nova_network_id>
The network ID list in nova.
[domainName]
Must match the domain name used for that network on the NIM
server if one is being used. NIM-based deployments can fail if the
domain name returned by a reverse DNS lookup on the NIM server
does not match this value.
Example:
# ./nova-netext-match vmcontrol "Discovered/1/0/ETHERNET0"
365a1ab0-94e2-40a5-8601-d98c3584536f mydomainname.com
{"networkExtension": {"enableDhcpV6": false,
"activeDirectoryPassword": null,
Chapter 2. Installing 69
"name": "Discovered/1/0/ETHERNET0 (VLAN 1, Bridged)",
"domainName": "mydomainname.com",
"computerNamePrefix": null, "networkName":
"Discovered/1/0/ETHERNET0", "cloudId": "sco-vmw-29-fb:301",
"activeDirectory": null, "wins2": null,
"hostnamePrefix": null, "enableDhcp": false, "wins1": null,
"cloudType": "VMControl", "activeDirectoryUser":
null, "osNetworkId": "365a1ab0-94e2-40a5-8601-d98c3584536f",
"id": "1c94bf17-6499-416a-8e4f-4391e4105fa6", "workgroup": null}}
Note: If there are multiple Power networks in the environment, make sure
to use the right network in OpenStack to match with the Power network.
5. Create an OpenStack flavor for the Power instance deployment.
Note: Many Power images have predefined limit properties that restrict the
ability to deploy a virtual machine with traditional OpenStack flavors as they
unnecessarily require a specific amount of cpu and memory. For example,
many IBM PureApp Hypervisor Edition images require exactly 1 vCPU and 3
GB of memory. It is strongly recommended to run the ./nova-remove-ovf-
limits <cloud-name> command after those images have been loaded into
VMControl to remove those limits so that traditional OpenStack flavors can be
used. However, one can still define your own custom flavors (for details, refer
toCreating new flavors in OpenStack on page 560).
# ./nova flavor-create [--ephemeral <ephemeral>] [--swap <swap>]
[--rxtx-factor <factor>] [--is-public <is-public>]
<name> <id> <ram> <disk> <vcpus>
where:
<ephemeral>
The ephemeral space size in GB. The default value is 0.
<swap>
The swap space size in MB. The default value is 0.
<factor>
The RX/TX factor. The default value is 1.
<is-public>
Make the flavor accessible to the public. The default value is true.
<name>
The name of the new flavor.
<id> A unique ID (integer or UUID) for the new flavor. If you specify auto, a
UUID is generated.
<ram> The memory size in MB.
<disk> The disk size in GB.
<vcpus>
The number of vCPUs.
Example:
# ./nova flavor-create --is-public True IPAS 6 4096 30 1
+----+------+-----------+------+-----------+------+-------+-------------+-----------+-------------+
| ID | Name | Memory_MB | Disk | Ephemeral | Swap | VCPUs | RXTX_Factor | Is_Public | extra_specs |
+----+------+-----------+------+-----------+------+-------+-------------+-----------+-------------+
| 6 | IPAS | 4096 | 30 | 0 | | 1 | 1.0 | True | {} |
+----+------+-----------+------+-----------+------+-------+-------------+-----------+-------------+
6. To customize flavors for Power features, refer to Customizing flavors for
Power features on page 561.
Example:
70 IBM SmartCloud Orchestrator 2.3: User's Guide
# ./nova flavor-key IPAS set ibm-smartcloud:cpushu=0.3
./nova flavor-key IPAS set ibm-smartcloud:memmax=32768
./nova flavor-key IPAS set ibm-smartcloud:cpushmaxu=4
./nova flavor-key IPAS set ibm-smartcloud:cpushmax=4
./nova flavor-list
+----+-----------+-----------+------+-----------+------+-------+-------------+-----------
| ID | Name | Memory_MB | Disk | Ephemeral | Swap | VCPUs | RXTX_Factor | Is_Public
+----+-----------+-----------+------+-----------+------+-------+-------------+-----------
| 1 | m1.tiny | 512 | 0 | 0 | | 1 | 1.0 | True
| 2 | m1.small | 2048 | 20 | 0 | | 1 | 1.0 | True
| 3 | m1.medium | 4096 | 40 | 0 | | 2 | 1.0 | True
| 4 | m1.large | 8192 | 80 | 0 | | 4 | 1.0 | True
| 5 | m1.xlarge | 16384 | 160 | 0 | | 8 | 1.0 | True
| 6 | IPAS | 4096 | 30 | 0 | | 1 | 1.0 | True
| | | | | | | | |
+----+-----------+-----------+------+-----------+------+-------+-------------+-----------
+----------------------------------------------------------------------------+
| extra_specs |
+----------------------------------------------------------------------------+
| {} |
| {} |
| {} |
| {} |
| {} |
| {uibm-smartcloud:cpushu: u0.3, uibm-smartcloud:memmax: u32768, |
| uibm-smartcloud:cpushmaxu: u4, uibm-smartcloud:cpushmax: u4} |
+----------------------------------------------------------------------------+
For SCS deployment, you can use the extra_specs flavor to customize the
storage connection method. The default method is VSCSI. The NPIV method
requires hardware support.
Example:
# ./nova flavor-key IPAS set ibm-smartcloud:storageconnection=NPIV
For SCS deployment, you can use the extra_specs flavor to customize the
storage connection method. The default method is VSCSI. The NPIV method
requires hardware support and has a limitation (for details, refer to Product
limitations on page 1089).
7. Optional: When you add new hosts, clean up the hypervisor list. For more
information, see Must remove hosts that are not eligible for cloud on page
1118.
What to do next
You can now log into the SmartCloud Orchestrator interface to register images and
deploy VMs from those registered images.
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
Chapter 2. Installing 71
deployments or failure to start virtual application instances or virtual system
instances. If an NTP server is not used, the system clocks for the SmartCloud
Orchestrator environment and the hypervisors must be synchronized manually.
Procedure
1. In Central Server 3, 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 in the following
example:
"ntp_servers": [
"127.0.0.1",
"127.0.0.2",
"127.0.0.3",
"127.0.0.4"
]
Note: The list of the defined NTP servers is propagated to the provisioned
virtual machines and it is used to configure NTP on them.
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.
Configuring Memcached cache size
SmartCloud Orchestrator uses Memcached with an in-memory storage and
expiration dates to manage the tokens in case the performance is impacted by large
numbers of tokens that are generated by multiple concurrent users, you could
increase the cache size according to your requirement.
Procedure
1. Login to Central Server 2, edit the /etc/sysconfig/memcached file and set the
CACHESIZE=4096 parameter. Then restart the service to take effect by running the
following command:
service memcached restart
2. Verify that the Memcached cache size is increased by running memcached-tool
127.0.0.1:11211 stats. If Memcached works properly, the values of
total_items, total_connections, and get_hits are increasing.
Configuring Virtual Image Library proxies
Use distributed components, called proxies, to offload the typical image
management operations that are performed by Virtual Image Library to remote
sites. Using proxies, you do not need to access remote data stores directly from the
main server. The proxies also provide a more efficient solution for managing
segregated networks and slow links.
About this task
By default, the installer configures Virtual Image Library to work with a remote
proxy that is installed on the Region Server so that it can manage the OpenStack
system.
72 IBM SmartCloud Orchestrator 2.3: User's Guide
If you want to add more proxies or modify the existing configuration, you must
edit the origami configuration file that stores the main configuration properties
which determine which proxy manages which domain. You can find the file on
both the Virtual Image Library server and any remote node where you installed
the proxy. Even if the structure is the same, the file that is related to the Virtual
Image Library server contains some additional configuration sections to identify
the knowledge base and all the deployed proxies that it must be aware of to
properly distribute the actions to particular nodes.
Procedure
1. The /etc/origami/origami.config file on the Virtual Image Library server,
contains the following proxies section:
"proxies": [
{
"url": "local://",
"capabilities": ["crawl", "cache", "portability"],
"connectivity": ["Central Server 2","localhost","127.0.0.1"],
"agent_id":"Central Server 2",
"enabled": true
},
{
"url": "http://<PROXYAGENT>:8123/origami",
"capabilities": ["crawl", "cache", "portability"],
"connectivity": ["<PROXYAGENT>"],
"agent_id": "<PROXYAGENT>",
"enabled": true
},
...
]
2. To define a new proxy, run the following commands:
cd /home/library
./configureProxy.sh --addProxyDef -h <PROXYAGENT_IP> -c <Hypervisor_Manager_IP>
where
v <PROXYAGENT_IP> is the IP address of the new proxy agent.
v <Hypervisor_Manager_IP> is the IP address of the hypervisor manager. If
your hypervisor manager is VMware, you must specify both the IP address
and port in the format <Hypervisor_Manager_IP>:<port> (the default port
value is 443).
As an alternative, if you already defined a Virtual Image Library proxy, you can
add a new hypervisor manager to be managed by the existing proxy by
running the following commands:
cd /home/library
./configureProxy.sh --addRepDef -h <PROXYAGENT_IP> -c <Hypervisor_Manager_IP>
where
v <PROXYAGENT_IP> is the IP address of the proxy agent that is already defined
in the origami.config file.
v <Hypervisor_Manager_IP> is the IP address of the new hypervisor manager. If
your hypervisor manager is VMware, you must specify both the IP address
and port in the format <Hypervisor_Manager_IP>:<port> (the default port
value is 443).
3. Restart the proxy service on the Virtual Image Library server by running the
following command:
service vilProxy restart
Chapter 2. Installing 73
4. If the Virtual Image Library proxy is not installed, follow the procedure that is
described in Installing the proxy component on page 301 to install the proxy
on a new machine.
5. In the proxy machine, configure the Virtual Image Library proxy by running
the following commands:
cd /home/library
./configureProxy.sh --addRepDef -c <Hypervisor_Manager_IP>
where <Hypervisor_Manager_IP> is the IP address of the hypervisor manager to
be managed by the proxy. If your hypervisor manager is VMware, you must
specify the both IP address and port in the format
<Hypervisor_Manager_IP>:<port> (the default port value is 443). The proxy
definition is modified in the /etc/origami/origami.config file.
6. Restart the Virtual Image Library proxy on the proxy machine by running the
following command:
service vilProxy restart
Results
You configured the Virtual Image Library proxy. For more information about
configuring Virtual Image Library proxies, see Configuring Virtual Image Library
server and remote proxy components on page 303.
Removing a Compute Node
Follow this procedure to remove a KVM compute node from SmartCloud
Orchestrator.
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
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
74 IBM SmartCloud Orchestrator 2.3: User's Guide
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
4. (Optional, this step is required before re-adding a removed compute back to the
Region Server) On the Region Server, remove the file /iaas/chef-repo-srv/
data/nodes/<compute_node_hostname>.
5. (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>
6. (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 SmartCloud Orchestrator installer and
reassign the IP back to ethX interface.
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
Use the steps that are described in this section to remove a region from the
SmartCloud Orchestrator environment.
Procedure
1. The SmartCloud Orchestrator admin must delete all instances on the region
from the cloud groups:
v Log on to the SmartCloud Orchestrator user interface and click Instances >
All Instances.
v Review each of the instances and delete the instances that belong to the
region that you want to remove.
2. Update the Virtual Image Library environment to ensure that all region-specific
data is removed:
v On the Virtual Image Library proxy machine, which is also referred to as the
Region Server, copy the images if required:
Run the /home/library/copyImages.sh script to copy the images to the
Virtual Image Library server or to another proxy connected to it:
copyImages.sh -destdomain <DESTDOMAIN> [-srcdomain <SRCDOMAIN>]
where
- -destdomain, -dest, -d <DESTDOMAIN> indicates the fully qualified
domain name of the destination Virtual Image Library proxy or server.
- -srcdomain, -src, -s <SRCDOMAIN> indicates the fully qualified domain
name of the source Virtual Image Library proxy or server. If this is not
specified, the local domain name is used.
v On the Virtual Image Library proxy machine, stop and disable the Virtual
Image Library proxy by running the following commands:
service vilProxy stop
chkconfig vilProxy off
Chapter 2. Installing 75
v On the Virtual Image Library server machine - Central Server 2:
Run
java -cp "/opt/p2pdiff/TransferClient/p2pDiffTransfer.jar:/opt/p2pdiff/TransferClient"
com.ibm.sid.RunCommand <ServerHostName> DeleteDatacenter <targetDatacenterName>
where:
- <ServerHostName> is the Virtual Image Library fully qualified server
host name.
- <targetDatacenterName> is the removed Virtual Image Library proxy
fully qualified host name. This is the region server fully qualified host
name.
This command might return the Status=false xxx not found message, if
no images were checked in or checked out from this region.
3. 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
For VMware or Power
regions only, run the following command on the
applicable region server:
source /root/openrc
/opt/ibm/openstack/iaas/smartcloud/bin/nova-cloud-delete <Region>
4. Update the SmartCloud Orchestrator environment as follows:
v Delete the region cloud groups:
Click Configuration > Cloud Groups.
Select the cloud group for the region you are deleting and click Discover.
Select each cloud group related to the region and click Delete.
v Delete the region IP group:
Click Configuration > IP Groups, select the required IP group and click
Delete.
5. On the Virtual Image Library proxy machine, enable and start the Virtual
Image Library proxy machine by running the following commands:
chkconfig vilProxy on
service vilProxy start
6. Optional: Update the region data:
v Update the data on Central Server 1: /iaas/installer/scripts/
clean_region_data.sh RegionOne
Note: This step erases data that is related to the removed region in the
OPENSTAC database. You must back up your data if required.
7. To check if the region has been successfully removed, perform these steps:
a. Be sure that no endpoints are found in keystone. Run the following
command on Central Server 2:
source /root/keystonerc
keystone endpoint-list |grep RegionOne
where RegionOne is the region you removed. No output should be returned.
b. Be sure there are no cloud groups related to this region in SmartCloud
Orchestrator. Login to SmartCloud Orchestrator, click Configuration >
Cloud Groups, there should be no cloud groups related to the region.
76 IBM SmartCloud Orchestrator 2.3: User's Guide
c. In SmartCloud Orchestrator, click Images&Patterns > Virtual Image
Library. In Virtual Image Library, click images and verify that the deleted
region is not listed in Operational Repositories.
Configuring LDAP authentication
Configure SmartCloud Orchestrator to use an LDAP server for user authentication.
By default, SmartCloud Orchestrator authenticates users against the OpenStack
Keystone database that is part of the product. You can configure SmartCloud
Orchestrator to authenticate against an external corporate directory (such as LDAP
or Active Directory) by enabling SmartCloud Orchestrator to pass an
authentication request to the corporate directory before passing the request to
Keystone.
The LDAP authentication support provided by SmartCloud Orchestrator enables
users defined in LDAP to logon to SmartCloud Orchestrator by specifying the
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, SmartCloud 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 80.
Configuring LDAP authentication independently of the domain
You can configure LDAP authentication for SmartCloud Orchestrator.
To configure LDAP authentication, you must already have an LDAP server set up.
You will also need to specify which LDAP attributes are used as part of the
authentication process. You need to decide on the following:
v Which LDAP attribute will be checked against the username 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 will be what the user must type into the
SmartCloud Orchestrator login panel.
v Where are the user objects stored in the LDAP server? You need to 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 will need an
LDAP user and password account that does have search capabilities, for the
subtree that contains the user's objects.
Note: The SmartCloud Orchestrator administrator account admin will already exist
in the local OpenStack database. Care must be taken to make sure there is not an
LDAP account that also has the name admin, otherwise this will now supersede the
local admin account.
Chapter 2. Installing 77
With the above items decided, 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 (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
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, then 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 simply refer to your secure LDAP server by
specifying url = ldaps://.... in keystone.conf.
If you use TLS, then the certificate details are specified instead 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 both not 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 configuration file or paste.ini, define a filter for this class:
78 IBM SmartCloud Orchestrator 2.3: User's Guide
[filter:ldapauth]
paste.filter_factory =
keystone.middleware.ldapauth:LdapAuthAuthentication.factory
6. Add the ldapauth plug-in to the pipeline that you are using. By default this is
the api_v3 pipeline. ldapauth must come after the simpletoken filter:
[pipeline:api_v3]
pipeline = access_log sizelimit stats_monitoring
url_normalize token_auth admin_token_
auth xml_body json_body simpletoken ldapauth
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 this can be done manually, or using an external directory synchronization
tool, SmartCloud 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
populates the minimal amount of information required into Keystone, namely 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 decide on the following:
v Which LDAP attribute will be used to create a unique user_id within
the OpenStack keystone? This must be something that will 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,
again, a common alternative (it is perfectly acceptable, for example, to use email
as both the username and the user_id).
v Which project should the user be given an initial role on as part of the
auto-population? This project will already need 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 will create a user-record the first time
a user authenticates, it will 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 SmartCloud 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 81).
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
Chapter 2. Installing 79
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
Note: The roles assigned here only affect the assignments held within
SmartCloud 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. However, for backward compatibility with SmartCloud
Orchestrator 2.2 fix pack 1, setting this using default_tenant_id is also still
supported.
3. In your Keystone configuration file or paste.ini, 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_normaliz e token_auth admin_token_auth
xml_body json_body simpletoken ldapauth autopop debug
stats_reporting ec2_extension s3_extension service_v3
Configuring LDAP authentication on a domain-by-domain basis
There are some additional steps to configure LDAP authentication in a SmartCloud
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 77:
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
Only the [ldap_pre_auth] and [auto_population] sections should be included
in the domain specific configuration file, within which you should 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 77.
80 IBM SmartCloud Orchestrator 2.3: User's Guide
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.
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 character varying(64) NOT NULL
name character varying(64) NOT NULL
domain_id character varying(64) NOT NULL
password character varying(128) NOT NULL
enabled Boolean
extra text
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:
Chapter 2. Installing 81
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
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 section are as follows:
Table 10. 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
82 IBM SmartCloud Orchestrator 2.3: User's Guide
Table 10. Configuration file options in ldap_pre_auth section (continued)
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 SmartCloud Orchestrator UI.
Domain configuration files are only read when the keystone component of
SmartCloud Orchestrator is started (or restarted).
Default
False
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 83
Table 10. Configuration file options in ldap_pre_auth section (continued)
url 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:
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
user 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.
Default
None
Example
user = cn=root
user_attribute_name This is now depreciated, 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 ain 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
84 IBM SmartCloud Orchestrator 2.3: User's Guide
Table 10. 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 11. 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 85
Table 11. 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
default_role 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
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 depreciated, but has the same meaning as default_project_id.
Default
None
Modifying project quotas
You can configure the project quotas in OpenStack so that they suit your business
needs.
About this task
Nova utilizes a quota system at the project level to control resource consumption
across the available hardware resources. The default values of quotas are listed in
the nova.conf file and you can edit this file to change the default values. For more
information about quotas, see the OpenStack documentation.
Procedure
1. Run the following command to see the quota for a project:
nova quota-show --tenant <project_id>
where <project_id> is the ID of the project (not the name of the project) for
which you want to set the quotas.
To get the list of the project IDs, run the following command:
keystone tenant-list
+----------------------------------+---------+---------+
| id | name | enabled |
+----------------------------------+---------+---------+
| 3d48139b938a4671b3c72df1ac27983a | admin | true |
86 IBM SmartCloud Orchestrator 2.3: User's Guide
| 715c10e6871d4e518f98e0a917eda857 | service | true |
| d592e14e8df64868aafc18cec4abb87c | DJ01 | true |
+----------------------------------+---------+---------+
2. To change the default project quotas, edit the nova.conf file.
3. To change the quota values in your project, run the following command:
nova quota-update --instances <number_of_instances>
--cores <number_of_process_cores>
--ram <size_of_ram_in_MB>
--volumes <number_of_volumes>
--fixed-ips <number_of_fixed_ips>]
<project_id>
To make the quota values unlimited in your project, set the corresponding
quota value to "-1".
Preparing to install additional Enterprise components
A complete deployment of SmartCloud Orchestrator Enterprise involves the
installation of various optional components that comprise the SmartCloud
Orchestrator Enterprise release.
These components include:
v Jazz for Service Management
v IBM SmartCloud Cost Management
v IBM Tivoli Monitoring
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 links below:
1. Quick Start Guide for Jazz for Service Management.
2. Quick Start Guide for IBM SmartCloud Cost Management
3. Quick Start Guide for IBM Tivoli Monitoring and Tivoli Monitoring for Virtual
Environments
Quick start guide for metering and billing
Use this topic as a go to 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.3.
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.
Chapter 2. Installing 87
v For information about defining rates and rate templates. see
Administering the system.
v For information about customizing jobs, see Administering data
processing.
Confirming the creation of offerings and categories
You can confirm the creation of offerings and categories to verify that the
SCO-CatalogImport.sh tool is installed correctly.
About this task
The SCO-CatalogImport.sh tool is used during installation to install the offerings
and categories for the vSys toolkit which is included in SmartCloud Orchestrator. If
the offerings and categories are created, it means that the action was performed
correctly.
To verify that the offerings and categories have been created successfully, perform
the following steps:
Procedure
1. Go to Configuration > Self Service Categories and verify the following
categories:
v Virtual System Operations (Single Instance)
v Virtual System Operations (Multiple Instances)
2. Go to Configuration > Self Service Offerings and verify the following
categories:
v Deploy Virtual System Instance
v Start Virtual System Instance
v Stop Virtual System Instance
v Restart Virtual System Instance
v Delete Virtual System Instance
v Change End Time of Virtual System Instance
v Change Limits of Environmental Profile
v Start Single Server Virtual System Instance
v Stop Single Server Virtual System Instance
v Restart Single Server Virtual System Instance
v Delete Single Server Virtual System Instance
v Modify Single Server Virtual System Instance
v Start Multiple Virtual System Instances
v Stop Multiple Virtual System Instances
v Restart Multiple Virtual System Instances
v Delete Multiple Virtual System Instances
88 IBM SmartCloud Orchestrator 2.3: User's Guide
Changing the language settings for the vSys offerings and
categories
After installation, you can change the language settings for the vSys offerings and
categories.
About this task
After installation, you can change the language settings from the English default to
another language. To do this, manually remove all the vSys-created offerings and
categories. Use the SCO-CatalogImport.sh tool with the translated xml files located
on the Business Process Manager node in the directory /opt/ibm/ccs/catalog/
samples/vsys. For example, for Italian, use the file ./SCO-CatalogImport.sh
/opt/ibm/ccs/catalog/samples/vsys/vSysToolkitOfferings_it.xml admin admin.
Changing the various passwords
This topic describes how you can change the password for SmartCloud
Orchestrator built-in users, and how to change the password for the user that is
used to connect to a VMware vCenter in a VMware-based region.
The topic contains the following sections:
v Changing the admin password
v Changing the wasadmin password on page 91
v Changing the bpm_admin and tw_admin passwords on page 91
v Changing the db2inst1 password on page 91
v Changing the bpmuser password on page 93
v Changing the password for the vCenter connection (VMware regions only) on
page 94
v Changing the password for the VMControl connection (PowerVM regions
only) on page 95
Changing the admin password
The admin user is used across the following SmartCloud Orchestrator components:
SmartCloud Orchestrator user interface, Iaas Gateway, and OpenStack.
1. Change the password in the SmartCloud Orchestrator user interface by editing
the admin user in the Users panel (Administration > Users). After you change
the password, you cannot continue to work with the user interface until you
complete step 4 of this procedure. Close your browser.
2. Log on to the Region Server and encrypt the new password using the
/usr/bin/openstack-obfuscate <new password> command. Then log on to
Central Server 2 and edit the /etc/iaasgateway/iaasgateway.conf file by
changing the following line to the new password:
password = <type the new admin encrypted password here>
3. Restart the IaaS gateway service:
v If you are not using the SmartCloud Orchestrator high availability solution,
run the following command:
service openstack-iaasgateway restart
v If you are using the SmartCloud Orchestrator high availability solution, log
in to the System Automation Application Manager user interface and
initiate a restart of the openstack-iaasgateway resource.
4. Log on to Central Server 3 and restart the Workload Deployer service:
Chapter 2. Installing 89
v If you are not using the SmartCloud Orchestrator high availability solution,
run the following command:
service iwd restart
v If you are using the SmartCloud Orchestrator high availability solution, log
in to the System Automation Application Manager user interface and
initiate a restart of the Workload Deployer resource.
5. Log on to Central Server 2 and restart Virtual Image Library by doing the
following steps:
v If you are not using the SmartCloud Orchestrator high availability solution,
run the following command:
service vil restart
v If you are using the SmartCloud Orchestrator high availability solution, log
in to the System Automation Application Manager user interface and
initiate a restart of the Virtual Image Library resource group.
6. Log on to the Virtual Image Library user interface, select the OpenStack
domain in the Operational Repositories section in the resource tree, and then
click Actions > Change Credentials.
7. Specify the new password for the admin user.
8. Log on to Central Server 2 and edit the /root/keystonerc file to change the
following line:
export OS_PASSWORD=<old admin password>
to:
export OS_PASSWORD=<new admin password>
9. If you are using a VMware or Power region:
a. Change the admin password in SmartCloud Entry using the following
command (to be run from the Region Server):
curl -v -ku admin:<old admin password>
http://<ip address of the region server>:7080/cloud/api/users/admin
-H "Content-Type:application/json"
-d {"username":"admin","password":"<new admin password>",
"oldPassword":"<old admin password>"}
-X PUT
b. Restart the SmartCloud Entry service:
v If you are not using the SmartCloud Orchestrator high availability
solution, run the following command: service sce restart.
v If you are using the SmartCloud Orchestrator high availability solution,
log in to the System Automation Application Manager user interface and
initiate a restart of the SmartCloud Entry resource.
c. On the Region Server, update /etc/nova/smartcloud.conf replacing the
old encrypted admin password with the new admin encrypted password
in the sce_connection_password property and in the
admin_password property.
d. Restart the openstack-smartcloud service:
v If you are not using the SmartCloud Orchestrator high availability
solution, run the following command: service openstack-smartcloud
restart .
v If you are using the SmartCloud Orchestrator high availability solution,
log in to the System Automation Application Manager user interface and
initiate a restart of the openstack-smartcloud resource.
10. If you used admin as the user to connect to the cloud provider in Image
Construction and Composition Tool, you must remove the cloud provider
90 IBM SmartCloud Orchestrator 2.3: User's Guide
from Administer -> Manage Cloud Providers and create it again
specifying the new password. Then you must import again your images. If
you stopped Image Construction and Composition Tool before recreating the
cloud provider, the cloud provider will no longer be visible. You must
recreate it with a different name and import again the images.
Changing the wasadmin password
To change the wasadmin password used by WebSphere
Application Server, see
Changing the WebSphere account password on page 310.
Changing the bpm_admin and tw_admin passwords
To change the bpm_admin password, follow these steps:
1. Change the password of bpm_admin in the WebSphere Application Server page:
a. Log on to https://$central-server4:9043/ibm/console/logon.jsp.
b. Select Users and Groups.
c. Select bpm_admin.
d. In the User Properties panel, set the password, confirm it, and click Apply.
e. Change the following configuration files:
1) On Central Server 4, create a backup copy of the following files:
/opt/ibm/BPM/v8.5/profiles/DmgrProfile/properties/soap.client.props
and:
/opt/ibm/BPM/v8.5/profiles/Node1Profile/properties/soap.client.props
2) Edit each of the soap.client.props files listed in step i 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=<type the new bpm_admin password here>
3) Encrypt the password by running 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
4) To test if it works well, you can try to restart the service:
service bpm-dmgr restart
service bpm-node restart
2. To change the password of tw_admin, run the same procedure as described in
Step 1.
Changing the db2inst1 password
The db2inst1 password must be changed in the operating system where the DB2
instance is installed and in the OpenStack configuration files.
Remember that db2inst1 is used for OpenStack and Workload Deployer database
connections.
Chapter 2. Installing 91
1. To change the db2inst1 password in the operating system where DB2 is, log on
the system as root and type:
passwd db2inst1
then type in the new password.
2. Update the DB2 related password in the OpenStack configuration file:
a. Update the keystone configuration file on Central Server 2:
1) Find the keystone configuration file:
cd /etc/keystone
grep -Fnr connection ./
./keystone.conf:28:connection =
W0lCTTp2MV12b3pfcW9fZm46Ly94ZnFvOmZwYjRmaWdAMTcyLjE2LjM0LjIwMTo1MDAwMC9iY3JhZmducA==
b. Decode the DB2 connect information:
openstack-obfuscate
-u W0lCTTp2MV12b3pfcW9fZm46Ly94ZnFvOmZwYmdyZmdAMTAuMTYuMzQuMjAxOjUwMDAwL2JjcmFmZ25w
ibm_db_sa://ksdb:[email protected]:50000/openstac
c. Encrypt the DB2 connect information with the new password:
openstack-obfuscate ibm_db_sa://ksdb:<type here the new password>@10.16.34.201:50000/openstac
W0lCTTp2MV12b3pfcW9fZm46Ly94ZnFvOmFyamNuZmYwamVxQDEwLjE2LjM0LjIwMTo1MDAwMC9iY3JhZmducA==
d. Update the other OpenStack components on the Region Server.
3. Find the configuration files and replace the DB2 connection information with
the new password.
On a KVM region, find the configuration files:
cd /etc
grep -Fnr sql_connection ./
./glance/glance-registry.conf:27:sql_connection =
W0lCTTp2MV12b3pfcW9fZm46Ly90eXI1NDg5OTpmcGI0ZmlnQDE3Mi4xNi4zNC4yMDE6NTAwMDAvYmNyYWZnbnA=
./glance/glance-api.conf:32:sql_connection =
W0lCTTp2MV12b3pfcW9fZm46Ly90eXI1NDg5OTpmcGI0ZmlnQDE3Mi4xNi4zNC4yMDE6NTAwMDAvYmNyYWZnbnA=
./cinder/cinder.conf:17:sql_connection =
W0lCTTp2MV12b3pfcW9fZm46Ly9wdmU1NDg5OTpmcGI0ZmlnQDE3Mi4xNi4zNC4yMDE6NTAwMDAvYmNyYWZnbnA=
./nova/nova.conf:71:sql_connection =
W0lCTTp2MV12b3pfcW9fZm46Ly9hYm41NDg5OTpmcGI0ZmlnQDE3Mi4xNi4zNC4yMDE6NTAwMDAvYmNyYWZnbnA=
On a VMware region, find the configuration files:
cd /etc
grep -Fnr sql_connection ./
./glance/glance-registry.conf:27:sql_connection =
W0lCTTp2MV12b3pfcW9fZm46Ly90eXIxNDQ0Nzpub3AxMjNAOS4xMTUuNzcuMzk6NTAwMDAvYmNyYWZnbnA=
./glance/glance-api.conf:32:sql_connection =
W0lCTTp2MV12b3pfcW9fZm46Ly90eXIxNDQ0Nzpub3AxMjNAOS4xMTUuNzcuMzk6NTAwMDAvYmNyYWZnbnA=
./cinder/cinder.conf:17:sql_connection =
W0lCTTp2MV12b3pfcW9fZm46Ly9wdmUxNDQ0Nzpub3AxMjNAOS4xMTUuNzcuMzk6NTAwMDAvYmNyYWZnbnA=
./nova/smartcloud.conf:48:smartcloud_sql_connection=
W0lCTTp2MV12b3pfcW9fZm46Ly9mcHIxNDQ0Nzpub3AxMjNAOS4xMTUuNzcuMzk6NTAwMDAvYmNyYWZnbnA=
./nova/nova.conf:70:sql_connection=
W0lCTTp2MV12b3pfcW9fZm46Ly9hYm4xNDQ0Nzpub3AxMjNAOS4xMTUuNzcuMzk6NTAwMDAvYmNyYWZnbnA=
./nova/nova.conf:142:smartcloud_sql_connection =
W0lCTTp2MV12b3pfcW9fZm46Ly9mcHIxNDQ0Nzpub3AxMjNAOS4xMTUuNzcuMzk6NTAwMDAvYmNyYWZnbnA=
After modifying the configuration files, you must restart all the OpenStack
services. To test the changes has been correctly done, execute an OpenStack
command. For example, try to deploy an instance running the command nova
boot.
Change the db2inst1 password on Workload Deployer:
92 IBM SmartCloud Orchestrator 2.3: User's Guide
a. Login as root on Central Server 3.
b. Backup file /etc/rc.d/init.d/iwd-env.
c. Run the command:
service iwd setdb2host $DB2_HOST_ADDRESS $DB2_HOST_PORT $DB2_USER $DB2_PASS
d. Modify the parameter DB2_PASS in the files /etc/rc.d/init.d/iwd-env and
/etc/init.d/iwd-env. Pay attention to the value DB2_PASS, it must be an
encrypted password for the DB2 user, dbinst1. Here is an example on how
to get the encrypted password on Central Server 2:
vim /tmp/tmp_password.txt
password=$db2_password_in_plain_text
then run the command to encrypt the DB2 password:
/IBM/WebSphere/AppServer/bin/PropFilePasswordEncoder.sh /tmp/tmp_password.txt <new password>
Then you can find the encrypted password in /tmp/tmp_password.txt
Note: Pay attention to the format when modifying the password in file
iwd-env.
e. Restart the Workload Deployer by running:
service iwd restart
The output should look like:
[root@CS-3 init.d]# service iwd status
Processes:
db2sysc : STOPPED
derby : STOPPED
storehouse : RUNNING ( 2839 )
kernelservices : RUNNING ( 2917 )
zso : RUNNING ( 3398 )
Changing the bpmuser password
To change the password for the DB2 user used by the Business Process Manager
(bpmuser) you must change it both on Central Server 1 and in the WebSphere
Application Server console used by the Business Process Manager.
1. To change the password for the DB2 user used by the Business Process
Manager (bpmuser log on as root on Central Server 1 and launch:
passwd bpmuser
2. To change the Business Process Manager DB password in WebSphere
Application Server, follow these steps:
a. Log on to the Business Process Manager WebSphere Application Server
console: https://$central-server-4:9043/ibm/console/logon.jsp as
tw_admin
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.
g. Insert the new password.
h. Click Apply to validate the change.
i. A message informs you that you must save your change.
Chapter 2. Installing 93
j. Click Save directly to the master configuration.
k. Click Synchronize.
l. Test the DB connection by clicking Test connection and selecting BPM
Business Space data source.
Note: If you get errors while synchronizing the changes, try to log out and log
in the page, and try to modify the password again.
Note: For details, refer to http://pic.dhe.ibm.com/infocenter/dmndhelp/
v8r5m0/index.jsp?topic=%2Fcom.ibm.wbpm.admin.doc%2Ftopics
%2Ftcfig_db_pwd_postconfig_1.html
Note: To change the Workload Deployer DB2 connection password, change the
DB2 password for the Workload Deployer:
passwd db2inst1
Changing the password for the vCenter connection (VMware
regions only)
The password of the user used to connect to vCenter is recorded in SmartCloud
Entry and in Virtual Image Library, so the change needs to be done in these two
places.
v Changing the password for the vCenter connected to Virtual Image Library can
be done logging in into the Virtual Image Library user interface and selecting
the VMware domain in the Operational Repositories section in the resource tree,
and then clicking Actions > Change Credentials.
v Changing the password in SmartCloud Entry is done using the REST APIs:
v Obtain the id of the involved cloud provider using this command (on a single
line ):
curl -ku <SCE_user_name>:<SCE_user_password>
http://<SCE_UI_hostname>:<SCE_UI_port_number>/cloud/api/clouds/
-H "Content-Type:application/json"
for example:
curl -ku admin:passw0rd http://192.0.2.0:7080/cloud/api/clouds/
-H "Content-Type:application/json"
Here is an example of the output:
{"clouds":[{"jmsPort":61617,"timeout":600,"state":
{"label":"OK","id":"OK"},"isComplete":true,"hostname":"198.51.100.0","isJmsSSL":false,
"username":"Administrator","name":"vmware","id":"301","description":"OpenStack managed VMware",
"uri":"http://192.0.2.0:7080/cloud/api/clouds/301 ","cloudType":"VMware"}]}
v Change the password (on a single line):
curl -v -ku <SCE_user_name>:<SCE_user_password>
http://<SCE_UI_hostname>:<SCE_UI_port_number>/cloud/api/clouds/<CLOUD_PROVIDER_ID>
-H "Content-Type:application/json" -d {"hostname":"<VCENTER_hostname>",
"username":"<VCENTER_user_name>",
"password":"<VCENTER_user_new_password>","cloudType":"VMware"} -X PUT
v For example:
curl -v -ku admin:passw0rd http://192.0.2.0:7080/cloud/api/clouds/301
-H "Content-Type:application/json" -d {"hostname":"198.51.100.0", "username":"Administrator",
"password":"mypassword", "cloudType":"VMware"} -X PUT
Here is an example for the output:
94 IBM SmartCloud Orchestrator 2.3: User's Guide
* About to connect() to 192.0.2.0 port 7080 (#0)
* Trying 192.0.2.0... connected
* Connected to 192.0.2.0 (192.0.2.0) port 7080 (#0)
* Server auth using Basic with user admin
> PUT /cloud/api/clouds/301 HTTP/1.1
> Authorization: Basic YWRtaW46cGFzc3cwcmQ=
> User-Agent: curl/7.19.7 (x86_64-redhat-linux-gnu) libcurl/7.19.7 NSS/3.13.1.0 zlib/1.2.3
libidn/1.18 libssh2/1.2.2
> Host: 192.0.2.0:7080
> Accept: */*
> Content-Type:application/json
> Content-Length: 101
>
< HTTP/1.1 200 OK
< Content-Language: en_US
< Content-Type: text/plain; charset=UTF-8
< Date: Fri, 31 Jan 2014 16:24:45 GMT
< Accept-Ranges: bytes
< Server: Restlet-Framework/2.1.1
< Content-Length: 18
<
* Connection #0 to host 192.0.2.0 left intact
* Closing connection #0
Changing the password for the VMControl connection (PowerVM
regions only)
The password of the user used to connect to VMControl is recorded in SmartCloud
Entry and in Virtual Image Library, so the change must be applied in both places.
1. To change the password for the VMControl connection in Virtual Image
Library, complete the following steps:
a. Log into the Virtual Image Library user interface.
b. In the Operational Repositories section in the resource tree, select the
PowerVM domain.
c. Click Actions > Change Credentials.
2. To change the password in SmartCloud Entry, use the REST APIs as follows:
a. Get the id of the relevant cloud provider by entering the following
command on one line:
curl -ku <SCE_user_name>:<SCE_user_password>
http://<SCE_UI_hostname>:<SCE_UI_port_number>/cloud/api/clouds/
-H "Content-Type:application/json"
where:
<SCE_user_name>
The SmartCloud Entry user admin.
<SCE_user_password>
The password for the SmartCloud Entry user admin.
<SCE_UI_hostname>
The IP address or host name of the PowerVM region server where
SmartCloud Entry is installed.
<SCE_UI_port_number>
The port number used to access SmartCloud Entry. The default
value is 7080.
For example:
Chapter 2. Installing 95
curl -ku admin:sco4svt http://192.0.2.0:7080/cloud/api/clouds/
-H "Content-Type:application/json"
Here is an example of the output:
{"clouds":
[{"timeout":600,"port":8422,"isComplete":true,"isJmsSSL":false,"name":"RegionPower",
"uri":"http://192.0.2.0:7080/cloud/api/clouds/301","cloudType":"VMControl",
"jmsPort":61617,"state":
{"label":"OK","id":"OK"},"hostname":"198.51.100.0","username":"root","version":"2.4.3.x",
"id":"301","description":"OpenStack managed VMControl"}]}
b. Change the password by entering the following command on one line:
curl -v -ku <SCE_user_name>:<SCE_user_password>
http://<SCE_UI_hostname>:<SCE_UI_port_number>/cloud/api/clouds/<CLOUD_PROVIDER_ID>
-H "Content-Type:application/json"
-d {"hostname":"<VMCONTROL_hostname>",
"username":"<VMCONTROL_user_name>",
"password":"<VMCONTROL_user_new_password>","cloudType":"VMControl"} -X PUT
where:
<SCE_user_name>
The SmartCloud Entry user admin.
<SCE_user_password>
The password for the SmartCloud Entry user admin.
<SCE_UI_hostname>
The IP address or host name of the PowerVM region server where
SmartCloud Entry is installed.
<SCE_UI_port_number>
The port number used to access SmartCloud Entry. The default
value is 7080.
<CLOUD_PROVIDER_ID>
The ID obtained in the previous step.
<VMCONTROL_hostname>
The IP address or host name of the server where VMControl is
installed.
<VMCONTROL_user_name>
The user that connects to VMControl.
<VMCONTROL_user_new_password>
The new password for the user that connects to VMControl.
For example:
curl -v -ku admin:sco4svt http://192.0.2.0:7080/cloud/api/clouds/301
-H "Content-Type:application/json" -d {"hostname":"198.51.100.0",
"username":"root", "password":"newpassword", "cloudType":"VMControl"} -X PUT
Changing the password for OpenStack service users
OpenStack has three service users: nova, cinder and glance.
By default, the service users are created with the same password assigned at
installation time to the admin user. If you would like to change their passwords
follow these procedures:
To change the password for nova user:
96 IBM SmartCloud Orchestrator 2.3: User's Guide
1. Change the password in the SmartCloud Orchestrator user interface by
editing the nova user in the Users panel (Administration > Users).
2. On the Region Server run /usr/bin/openstack-obfuscate <new
password for nova user> to obtain the encrypted password.
3. On the Region Server, do a backup copy of /etc/nova/nova.conf.
4. On the Region Server, edit /etc/nova/nova.conf replacing the old value
of admin_password with the newly generated in Step 2.
Attention: It is recommended to comment out the property
admin_token in nova.conf.
5. Restart all openstack-nova* services.
To change the password for glance user:
1. Change the password in the SmartCloud Orchestrator user interface by
editing the glance user in the Users panel (Administration > Users).
2. On the Region Server run /usr/bin/openstack-obfuscate <new
password for glance user> to obtain the encrypted password.
3. On the Region Server, do a backup copy of /etc/glance/glance-
api.conf;/etc/glance/glance-registry.conf.
4. On the Region Server, edit /etc/glance/glance-api.conf replacing the
old value of admin_password with the newly generated in Step 2. Do
the same in /etc/glance/glance-registry.conf.
Attention: It is recommended to comment out the property
admin_token in both glance-api.conf and glance-registry.conf.
5. Restart all openstack-glance* services.
To change the password for cinder user:
1. Change the password in the SmartCloud Orchestrator user interface by
editing the cinder user in the Users panel (Administration > Users).
2. On the Region Server run /usr/bin/openstack-obfuscate <new
password for cinder user> to obtain the encrypted password.
3. On the Region Server, do a backup copy of /etc/cinder/cinder.conf.
4. On the Region Server, edit /etc/cinder/cinder.conf replacing the old
value of admin_password with the newly generated in Step 2.
Attention: It is recommended to comment out the property
admin_token in cinder.conf.
5. Restart all openstack-cinder* services.
Replacing the existing certificates
This topic describes how you can replace existing certificates.
SmartCloud Orchestrator user interface (Central Server 3)
To replace the certificates of the SmartCloud Orchestrator user interface with the
certificates officially released by a Certification Authority, follow the procedure to
import and apply into SmartCloud Orchestrator UI components once you receive
the official certificates.
The reference documentation for the jetty server can be found at:
http://wiki.eclipse.org/Jetty/Howto/
Configure_SSL#Loading_Keys_and_Certificates.
1. Log on to Central Server 3 (on the SmartCloud Orchestrator user interface
machine) and navigate to the scoui folder:
Chapter 2. Installing 97
/opt/ibm/ccs/scui/etc/
2. Back up the current keystore file and the jetty.xml configuration file as
follows:
mv keystore keystore.BAK
cp jetty.xml jetty.xml.BAK
3. Next you must follow the following procedure "Loading Keys and Certificates
through PKCS12" to include the new certificate and key into a keystore to be
used for jetty.
Loading Keys and Certificates through PKCS12:
If you have a key and certificate in separate files, you must combine them into
a PKCS12 format file to load into a new keystore. The certificate can be one you
generated yourself or one returned from a Certification Authority in response
to your certification service request.
The following OpenSSL command combines the keys in jetty.key and the
certificate in the jetty.crt file into the jetty.pkcs12.
If you have a chain of certificates, because your Certification Authority is an
intermediary, build the PKCS12 file as follows:
# cat example.crt intermediate.crt [intermediate2.crt]... rootCA.crt > cert-chain.txt
# openssl pkcs12 -export -inkey example.key -in cert-chain.txt -out example.pkcs12
The order of certificates must be from server to rootCA, as per RFC2246 section
7.4.2.
Use keytool (starting from jdk1.6) to import a PKCS12 file with the following
command:
keytool -importkeystore -srckeystore jetty.pkcs12 -srcstoretype PKCS12 -destkeystore newkeystore
The command asks for two passphrase. Give the password from the last step as
the input passphrase and you are set. The "output passphrase" must appear in
your jetty.xml configuration file as both the Password and KeyPassword of the
SunJsseListener that uses the certificate.
4. Configure jetty in order to use the new certificate:
a. Encode the password you used to create the key and the password you
used to import key into the keystore (they can be the same):
java -cp /opt/ibm/ccs/scui/lib/org.eclipse.jetty.util_8.1.3.v20120522.jar
org.eclipse.jetty.util.security.Password <your-password>
This will provide in output the encoded password as follows:
OBF:1v2j1uum1tfe1pot1zer1lbw1uvk1v1v
b. Edit the jetty.xml file and update the path of the keystore file to the new
one. In the sample provided in Step 3, newkeystore is the name of the
keystore file and the relative path from the SmartCloud Orchestrator user
interface root folder is /etc/newkeystore:
Original:
<Set name="keyStore"<SystemProperty name="jetty.home"/etc/keystore</Set>
<Set name="trustStore"<SystemProperty name="jetty.home"/etc/keystore</Set>
New configuration:
<Set name="keyStore"<SystemProperty name="jetty.home"/etc/newkeystore</Set>
<Set name="trustStore"<SystemProperty name="jetty.home"/etc/newkeystore</Set>
Replace the passwords for keystore and key with the encoded password
you got in the previous step:
98 IBM SmartCloud Orchestrator 2.3: User's Guide
<Set name="keyStorePassword">OBF:1vny1zlo1x8e1vnw1vn61x8g1zlu1vn4</Set>
<Set name="keyManagerPassword">OBF:1u2u1wml1z7s1z7a1wnl1u2g</Set>
<Set name="trustStorePassword">OBF:1vny1zlo1x8e1vnw1vn61x8g1zlu1vn4</Set>
c. Restart the SmartCloud Orchestrator user interface to apply the changes:
service scui restart
Workload Deployer (Central Server 3)
The reference documentation for the smash server can be found at:
http://publib.boulder.ibm.com/infocenter/wsmashin/v1r1/index.jsp?topic=/
com.ibm.websphere.sMash.doc/using/zero.core/SSLConfiguration.html.
1. Log on to Central Server 3 (SmartCloud Orchestrator user interface machine)
and navigate to the iwd folder:
/opt/ibm/rainmaker/purescale.app/private/expanded/ibm/rainmaker.rest-4.0.0.1/config/
2. Back up the current keystore file and https-server.config configuration file as
follows:
mv rm.p12 rm.p12.BAK
cp https-server.config https-server.config.BAK
3. Next reuse the same certificates used for jetty. You can reuse the jetty.pkcs12
file as keystore and modify the configuration file as in the next step.
4. Edit the configuration file /opt/ibm/rainmaker/purescale.app/private/
expanded/ibm/rainmaker.rest-4.0.0.0/config/https-server.config and
replace the passwords and keystore path. Note that the passwords must be
encoded 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": "<xor>Lz4sLChvLTs=",
"keyStoreType": "PKCS12",
"trustStore": "${/config/dependencies/ibm:rainmaker.rest}/config/rm.p12",
"trustStorePassword": "<xor>Lz4sLChvLTs=",
"trustStoreType": "PKCS12"
5. Back up the Workload Deployer keystore and Workload Deployer connection
configuration for the SmartCloud Orchestrator user interface. Navigate to the
folder:
/opt/ibm/ccs/scui/etc/
Back up the file iwd_keystore.jks:
mv iwd_keystore.p12 iwd_keystore.p12.BAK
Back up the file config.json:
cp config.json config.json.BAK
6. Edit the section iwd of the file config.json to make it use the same keystore
defined in the section above for the SmartCloud Orchestrator user interface
keystore (in the sample newkeystore).
Note: Remember to change the encrypted password accordingly, same as for
the jetty.xml file in the SmartCloud Orchestrator user interface configuration:
"iwd": {
"provider": "iwd",
"service_url": "https:\/\/2.zoppoz.workers.dev:443\/https\/9.168.58.29",
"simple_token_secret":
"OBF:1c3d1ggf1ls21j8z1x8m1pk31ugk1t9a1q4o1ksl1oxc1jra1jug1oy61ks91q461tb41uh61pi31x881j631lrw1gfj1c3p",
"keyStore": {
"path": "\/opt\/ibm\/ccs\/scui\/etc\/newkeystore",
"password": "OBF:1v2j1uum1lfm1zej1zer1lbw1uvk1v1v"
}
},
Chapter 2. Installing 99
Workload Deployer Kernel Service truststore:
After changing the SSL certificate, you must import it to the Kernel Service
truststore.
The keystore for the Kernel Service is:
/opt/ibm/maestro/maestro/usr/resources/security/KSTrustStore.jks
The password of the keystore is pureScale and you can check this in the
configuration file:
/opt/ibm/maestro/maestro/usr/servers/kernelservices/server.cfg
To set the Workload Deployer certificate in the Kernel Service truststore:
source /etc/profile.d/jdk_iwd.sh;
keytool -v -importkeystore
-srckeystore
/opt/ibm/rainmaker/purescale.app/private/expanded/ibm/rainmaker.rest-4.0.0.1/config/rm.p12
-srcstoretype PKCS12
-destkeystore /opt/ibm /maestro/maestro/usr/resources/security/KSTrustStore.jks
-deststoretype JKS -deststorepass pureScale -srcstorepass <cert_password>
Business Process Manager (Central Server 4)
When the Workload Deployer certificate is changed, the new certificate must be
imported in the Business Process Manager truststore to secure the communication
between Business Process Manager and Workload Deployer. To do so, follow the
instructions documented at http://pic.dhe.ibm.com/infocenter/wasinfo/v8r5/
index.jsp?topic=%2Fcom.ibm.websphere.express.doc%2Fae
%2Ftsec_sslretrievesignersport.html.
Import the certificate from the Workload Deployer server (Central Server 3 port
443). You need to import it into CellDefaultTrustStore and restart Business
Process Manager afterwards.
Archiving historical data
Archive periodically historical data related to deleted VM instances to keep stable
the performance of an OpenStack region server.
About this task
Use the archiveHistory.sh script to periodically archive historical data. The script
is released with the SmartCloud Orchestrator product in the <install_image>/
installer/tools/archive_history_utility directory.
For detailed information about the script installation and usage, see the related
ReadMe.txt file.
100 IBM SmartCloud Orchestrator 2.3: User's Guide
Content Pack installation
To make the content pack processes available in SmartCloud Orchestrator, import
the toolkit provided with the content pack inBusiness Process Manager as
described in this topic.
Follow this procedure:
1. In the Business Process Manager Designer, click Process Center.
2. In the Toolkits, click Import Toolkit.
3. In Import Toolkit, click Browse to select the file to import.
Note: The Toolkit file extension is in twx extension format.
4. Click OK.
When the Toolkit is imported in Business Process Manager, the processes of the
toolkit are available in SmartCloud Orchestrator, which can be configured as
self-service offering or Orchestration Action from the SmartCloud Orchestrator
user interface.
Log in to the SmartCloud Orchestrator user interface:
1. Click Configuration > Self-service Categories.
2. Assign a name, a description, and select a graphical icon for the category.
3. Click Configuration > Self-service Offerings.
4. Provide the offering name, select the newly created category and icon.
5. Select a process to create self-service offerings.
Upgrading to Fix Pack 1
This topic describes how to upgrade SmartCloud Orchestrator 2.3.0.0 to 2.3.0.1.
Before you begin
Both fresh installation and upgrade use the same package. Prepare the package by
performing the following steps on Central Server 1 and on all Region Servers:
1. Extract the package into a new directory, for example, if your working directory
is /install_images:
# tar xvf <installation tar media>
2. Extract install_images/IBM_SmartCloud_Installer_and_OpenStack-*.tgz to
/install_images, then navigate to the directory /install_images/installer/.
3. Prepare the Red Hat Enterprise Linux server DVD ISO file on Central Server 1
and all Region Servers:
a. On Central Server 1, set iso_location to the correct location in the file
central-server.cfg.
b. On each Region Server, set iso_location to the correct location in the file
region-server.cfg.
iso_location=/opt/RHEL6.3-20120613.2-
Server-x86_64-DVD1.iso
The location of the Red Hat Enterprise
Linux Server 6 DVD ISO file.
Note: No other parameters in the configuration files need to be updated, as
these can be determined from the existing installation of SmartCloud
Orchestrator 2.3.
Chapter 2. Installing 101
Note: Do not move to other directories when you perform the upgrade steps.
About this task
Perform the following steps to upgrade SmartCloud Orchestrator:
Procedure
1. Stop the SmartCloud Orchestrator processes:
v If you do not use System Automation Application Manager to control
SmartCloud Orchestrator, see Starting or stopping SmartCloud
Orchestrator on page 135 for information about stopping SmartCloud
Orchestrator.
v If you use System Automation Application Manager to control SmartCloud
Orchestrator, see Controlling the management stack on page 124 for
information about stopping the SmartCloud Orchestrator management stack
from System Automation Application Manager.
2. Back up the virtual machines of the Central Servers, Region Server, and
compute nodes. Backup the file /opt/ibm/pcg/etc/flavors.json on Central
Server 2. Otherwise, Public Cloud Gateway will lose the original flavor
customization after upgrade.
For VMware-hosted virtual machines, see Taking Snaphots for information
about taking snapshots of the virtual machines.
3. On Central Server 1, run deploy_central_server.sh to upgrade the Central
Server:
/install_images/installer/deploy_central_server.sh
4. On each Region Server, run deploy_region_server.sh to upgrade the Region
Server:
/install_images/installer/deploy_region_server.sh -C <central-server-1-ip-address>
5. On each KVM Region Server, run deploy_compute_node.sh to upgrade compute
node for KVM regions:
/install_images/installer/deploy_compute_node.sh -s <additional-node-ip> [-p <OS-root-password>]
6. Restart the SmartCloud Orchestrator processes:
v If you do not use System Automation Application Manager to control
SmartCloud Orchestrator, see Starting or stopping SmartCloud
Orchestrator on page 135 for information about starting SmartCloud
Orchestrator.
v If you use System Automation Application Manager to control SmartCloud
Orchestrator, follow the procedure described in Configuring System
Application Automation Manager to:
Re-configure service autostart on the Central Servers, Region Server, and
compute nodes.
Run the step to copy control scripts from /iaas/scorchestrator to
/home/saam on all the servers.
Note: After restarting SmartCloud Orchestrator processes, if the Virtual Image
Library repositories are not aligned and the resources are in out of synch status,
run Synchronize Repositories from the Virtual Image Library user interface.
7. Restore /opt/ibm/pcg/etc/flavors.json on Central Server 2.
Note: If you forget to backup the file /opt/ibm/pcg/etc/flavors.json in step 2,
you can find it in /opt/ibm/pcg/backup/server-*.zip on Central Server 2.
102 IBM SmartCloud Orchestrator 2.3: User's Guide
Results
You can find the upgrade logs in /tmp/bootstrap-update*.log.
If the upgrade procedure fails, you can roll back your SmartCloud Orchestrator
environment with the data you backed up. For VMware-hosted virtual machines,
see Taking Snaphots for information about taking snapshots of the virtual
machines.
Upgrading from SmartCloud Provisioning 2.3
This topic describes the upgrade from SmartCloud Provisioning 2.3.
About this task
To upgrade from SmartCloud Provisioning 2.3, perform the following steps.
Note: To upgrade to SmartCloud Orchestrator 2.3.0.1, before running the following
procedure, you must upgrade your environment to SmartCloud Provisioning
2.3.0.1.
Procedure
1. Create and prepare Central Server 4 as documented in Preparing the central
server and the region server on page 17.
2. On Central Server 1 untar the required packages. For more information about
the relevant packages, see the Preparing the installation based on electronic
download packages topic. For a list of the available media, refer to the
Preparing the installation based on DVD images topic.
3. On Central Server 1 under the installer/conf directory, do the following:
a. Copy deploy.conf to deploy.conf.bak.
b. Copy deploy_upgrade_from_SCP.conf to deploy.conf (the file contains
product_type=SCO and install_type=upsell).
c. In deploy.conf, replace the CHEF_SERVER_IP with the IP address of Central
Server 1.
4. Copy the SmartCloud_Orchestrator*-2.3.0.swtag file to the required location
using the following command:
cp <SCO install dir>/swtag/SmartCloud_Orchestrator*-2.3.0.swtag
/data/repos/scp/install-packages/iwd/SmartCloud_Orchestrator-2.3.0.swtag
5. On Central Server 1 under the installer directory, customize the
central-server.cfg file to reflect your environment. For more information
about this, see the Installing the central server topic.
6. Run the following command:
/deploy --debug central-server --os_password <admin password>
--os_service_password <service password> --password <root password>
Required arguments:
--os_password <admin password>
OpenStack admin user password.
--os_service_password <service password>
OpenStack service user password.
Optional arguments:
Chapter 2. Installing 103
--identity_file <identity file>
Identity (private key) for ssh public key authentication to login the
central servers.
--password <root password>
root password to login the central servers.
--ldap_password <ldap password>
Password to authenticate LDAP.
7. Important: If you are a SmartCloud Orchestrator Enterprise customer, login to
Central Server 3 and rename the SmartCloud_Orchestrator-2.3.0.swtag file by
executing the following command:
cd /opt/ibm/SmartCloud_Orchestrator/properties/version/
mv SmartCloud_Orchestrator-2.3.0.swtag SmartCloud_Orchestrator_Enterprise-2.3.0.swtag
High Availability
Learn how to setup a SmartCloud Orchestrator management stack with high
availability Quality of Services (QoS).
The high availability solution helps to reduce the downtime of the SmartCloud
Orchestrator management stack. In addition, operation of the SmartCloud
Orchestrator management stack is simplified.
The high availability solution includes a new component, the System Automation
Application Manager, which helps in recovery from application failures and which
simplifies the control of the SmartCloud Orchestrator management stack for the
operating team. The high availability solution can be enhanced by using the high
availability features of the hypervisors, for example, restart of all the virtual
servers on a backup hypervisor. The usage of the hypervisor high availability
capabilities requires additional manual steps at installation time.
The high availability capabilities for the SmartCloud Orchestrator management
stack are achieved through the following functions:
vSphere High Availability (HA) clusters
You can automatically recover after a virtual server failure, a ESXi failure,
or even a server failure by restarting the virtual server. The restart of the
virtual server can occur on the same ESXi server or, depending on the
failure situation, on another ESXi server.
System Automation Application Manager
Used to monitor and automatically recover failed application components.
Both high availability functions work together and should be used together to
achieve high availability of the SmartCloud Orchestrator management stack.
vSphere HA clusters enable a collection of ESXi Servers to work together so that,
as a group, they provide higher levels of availability for virtual machines than each
ESXi host can provide individually. vSphere HA pools virtual machines and ESXi
hosts so that they reside in a cluster. Hosts within the cluster are managed and, in
the event of a failure, the virtual machines on a failed ESXi host are restarted on
alternate host within the cluster. For SmartCloud Orchestrator, using vSphere HA
gives an extra level of redundancy, for example, if one of the ESXi Servers fails, the
SmartCloud Orchestrator virtual machines that were located on that host are
restarted on alternate ESXi hosts. Additionally, one of the features of vSphere HA
is VM Monitoring which, in the event of an OS failure, restarts the virtual machine.
104 IBM SmartCloud Orchestrator 2.3: User's Guide
If vSphere HA is not configured, a hardware failure might, in a worse-case
scenario, involve a reinstallation of the environment, a rather significant outage,
and potential data loss.
System Automation is used to automate the availability of resources. This
availability is accomplished by starting and stopping resources automatically and
in the correct sequence. System Automation Application Manager uses agentless
adapters to monitor and control remote applications. It ensures availability and
provides automation of these services even across operating system boundaries.
This is ideal for SmartCloud Orchestrator because it allows it to have a centralized
server that monitors and automatically stops, starts, or restarts the various
applications on the virtual machines in the SmartCloud Orchestrator environment.
Using both vSphere HA and System Automation Application Manager
withSmartCloud Orchestrator allows the recovery of the SmartCloud Orchestrator
environment in the event of either hardware and software failures, thereby
reducing the downtime of the SmartCloud Orchestrator management stack.
Using vSphere HA clusters
Configure the vSphere HA clusters for the SmartCloud Orchestrator environment.
Before you begin
To set up the vSphere HA solution, make sure that the following requirements are
met:
v vSphere HA Cluster
v Three or more ESXi servers
v Shared Storage (FC, iSCSI, NFS storage)
v Common Network configuration between ESXi Servers
v vMotion-enabled network
v Management network redundancy
v Shared Storage between all the ESXi Servers
v For optimum datastore heartbeating, a minimum of two shared data stores
About this task
For additional information about configuring and using vSphere HA clusters, see
the vSphere Availability guide.
To implement the vSphere HA solution by creating the SmartCloud Orchestrator
virtual machines on datastores that are shared between the ESXi servers, perform
the following procedure:
Procedure
1. Install at least three ESXi Servers. Storage and networking prerequisites must
be configured on all the ESXi Servers.
2. On the vCenter server, create a cluster. Do not enable vSphere at this time.
3. Add the ESXi Servers to the cluster.
4. Select Edit Settings on the cluster and select Turn on vSphere HA.
5. Perform the following steps:
a. Ensure that Host Monitoring is enabled
b. Ensure that Admission Control is enabled.
Chapter 2. Installing 105
c. Admission Control Policy must tolerate one host failure.
Note: Enabling Admission Control and setting the policy to tolerate one
host failure means that you cannot power on any virtual machines that
vSphere HA is not able to restart. For more information, see Configure
Host Monitoring and Admission Control in the vSphere Availability guide.
d. Leave the cluster default settings as it is.
e. Ensure VM Monitoring is set to VM Monitoring only.
f. Optionally, you can configure vSphere DRS. For more information, see
Configuring vSphere DRS.
g. Leave all the other settings as default, and click Finish.
6. The ESXi Servers are now configured for vSphere HA. You can check it in the
Summary tab of the ESXi host.
Note: One ESX Server is defined as the vSphere HA master, and all the other
ESXi Servers are defined as slaves. For more information, see Master and
Slave Hosts in the vSphere Availability guide.
7. Create the virtual machines and install SmartCloud Orchestrator.
Note: For the virtual machines to be protected by HA, you must install them
on the shared storage and they must have network connectivity.
8. Verify that the virtual machines are protected in the vSphere HA Protection
field in the Summary tab for each virtual machine or in the Virtual Machine
tab for the ESXi host.
Configuring vSphere DRS
vSphere Distributed Resource Scheduler (DRS) monitors utilization across vSphere
ESXi servers and allocates resources among virtual machines according to your
needs.
About this task
If a failure occurs, vSphere HA might separate clustered virtual machines that are
meant to stay together, or vSphere HA might put clustered virtual machines that
are meant to stay apart on the same host. You can avoid this problem by setting up
DRS groups and using the VM-Host affinity rules which are followed by vSphere
HA.
For further information about vSphere DRS, see the vSphere Resource Management
guide.
Note: vSphere HA starts the virtual machines on any available ESXi Servers, and
then vSphere DRS moves the virtual machines around for best resource allocation
and based on any rules configured.
The most basic configuration for SmartCloud Orchestrator is to have all virtual
machines on one ESXi server. If there are multiple ESXi servers in the cluster, a
rule is required to keep the virtual machines together.
To configure VM-Host-Affinity rules for the SmartCloud Orchestrator central
server, perform the following steps:
106 IBM SmartCloud Orchestrator 2.3: User's Guide
Note: The IBM SCO all-in-one rule in the following procedure is only for
example. The required rule depends on the physical infrastructure where you
installed SmartCloud Orchestrator.
Procedure
1. Select Edit Settings on the cluster and select Turn on vSphere DRS.
2. On the right of the window, select Rules under vSphere DRS.
3. Click Add and specify the following values:
v Specify IBM SCO all-in-one in the Name field.
v Specify Keep Virtual Machines Together in the Type field.
v In the Virtual Machines field, click Add... and select all SmartCloud
Orchestrator virtual machines.
4. Click OK.
5. Ensure that the rule SCO Central Server VMs together is selected and click
OK.
Using System Automation Application Manager
Use System Automation Application Manager to control the complete SmartCloud
Orchestrator management stack and its subcomponents.
About this task
System Automation Application Manager can detect if a software component of
SmartCloud Orchestrator failed and then automatically restart it. As a result, you
can achieve an improved availability solution for the SmartCloud Orchestrator
management stack.
System Automation Application Manager continuously monitors all the
components and subcomponents of the SmartCloud 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 which define the start and stop
dependency graph for all the SmartCloud Orchestrator components. As a result,
the operating team can start, stop, and monitor the state of the SmartCloud
Orchestrator management stack. System Automation Application Manager also
simplifies the operating tasks because it is possible to control the SmartCloud
Orchestrator management stack in a more granular manner on the component
level. For example, with a single request you can recycle only one component like
Business Process Manager.
Installing System Automation Application Manager
System Automation Application Manager version 3.2.2 is bundled with
SmartCloud Orchestrator version 2.3.
About this task
To install System Automation Application Manager perform the following steps.
Procedure
1. Create a virtual machine with at least 2 CPUs, 4 GB RAM and 20 GB disk
space.
2. Install and configure RHEL.
Chapter 2. Installing 107
Note: You can use the same version of the RHEL media that you used to install
SmartCloud Orchestrator. For information about software prerequisites, see
Software prerequisites on page 15.
Ensure the following packages are installed on the RHEL virtual machine. They
are included in the RHEL installation package.
v X11
v Firefox
v compat-libstdc++-33.i686
v compat-libstdc++-33.x86_64
v libstdc++.i686
3. Install DB2 and upgrade to the latest fix pack. For more information, see the
"Installing the middleware software" section in the System Automation
Application Manager, Installation and Configuration Guide.
4. Install WebSphere Application Server and upgrade to the latest fix pack. For
more information, see the "Installing the middleware software" section in the
System Automation Application Manager, Installation and Configuration Guide.
5. Install System Automation Application Manager. For more information, see the
"Installing System Automation Application Manager" section in the System
Automation Application Manager, Installation and Configuration Guide.
6. Download and install the latest fix pack for System Automation Application
Manager version 3.2.2. Fix pack 2 or later is required. For a list of the available
fix packs, see http://www-933.ibm.com/support/fixcentral/swg/
selectFixes?parent=ibm~Tivoli&product=ibm/Tivoli/
Tivoli+System+Automation+Application+Manager&release=3.2.2
&platform=Linux&function=all.
7. Verify the System Automation Application Manager installation. For more
information, see the "Verifying the installation" section of the System
Automation Application Manager, Installation and Configuration Guide.
8. System Automation Application Manager uses a special tool (named getamdata)
to gather debug output. You must install the tool manually by following the
related documentation. For more information, see http://www-01.ibm.com/
support/docview.wss?&uid=swg27017972#tarball.
Starting System Automation Application Manager
Because System Automation Application Manager is not started when the virtual
machine where it is installed starts, you must start System Automation Application
Manager manually.
To start System Automation Application Manager, run the following commands:
su db2inst1 -c /home/db2inst1/sqllib/adm/db2start
/opt/IBM/WebSphere/AppServer/bin/startServer.sh server1
eezdmn start
eezaladapter start
Stopping System Automation Application Manager
To stop System Automation Application Manager, run the following commands:
eezaladapter stop
eezdmn -SHUTDOWN
/opt/IBM/WebSphere/AppServer/bin/stopServer.sh server1
-username <adminid> -password <password>
su db2inst1 -c /home/db2inst1/sqllib/adm/db2stop
108 IBM SmartCloud Orchestrator 2.3: User's Guide
where <adminid> and <password> are the credentials that you specified during the
installation.
Starting System Automation Application Manager automatically
To automatically start System Automation Application Manager at the startup of
the virtual machine where it is installed, perform the following steps:
1. Create as root a script named startup in the /etc/opt/IBM/tsamp/eez directory
with the following content:
su db2inst1 -c /home/db2inst1/sqllib/adm/db2start
sleep 10
/opt/IBM/WebSphere/AppServer/bin/startServer.sh server1
sleep 30
eezdmn start
eezaladapter start
2. Make sure the script is executable by running the following command:
chmod 755 /etc/opt/IBM/tsamp/eez/startup
3. Add the following lines at the end of the /etc/inittab file:
# start of SA AM
saam:5:wait:/etc/opt/IBM/tsamp/eez/startup
Ensure that the default run level in the inittab of theSystem Automation
Application Manager virtual machine is 5.
Note: This step in only valid for RHEL 5.x, but not for RHEL6.x and beyond.
For these newer versions of RHEL, you must copy the startup script to
/etc/rc.d/init.d, and create a symbolic link to it under /etc/rc.d/
rc$runlevel.d.
Planning for System Automation Application Manager
configuration
Adapt the sample configuration files delivered with System Automation
Application Manager to your SmartCloud Orchestrator environment.
In SmartCloud Orchestrator, the following configuration files are delivered in the
/iaas/scorchestrator/TSA_AM_Policy directory:
ala_SCO.xml
Sample agentless adapter policy configuration file for SmartCloud
Orchestrator
e2e_SCO.xml
Sample end-to-end policy configuration file for SmartCloud Orchestrator
Because you must modify the configuration files for your environment, the
following environment configuration is used to make the changes easier:
Table 12. Environment configuration in sample files
Section in sample file Sample value Value
Central server central-server-1 myserver1
central-server-2 myserver2
central-server-3 myserver3
central-server-4 myserver4
Chapter 2. Installing 109
Table 12. Environment configuration in sample files (continued)
Section in sample file Sample value Value
Region server VMware region-server-VM vmcloud1
IDforVMregion VMcloud1
Region server KVM region-server-KVM kvmcloud1
IDforKVMregion KVMcloud1
Region server PowerVM region-server-POWER pcloud1
IDforPOWERregion Pcloud1
Compute node KVM region-server-Compute kvmcompute1
IDforKVMcompute kvmcompute1
Note:
v If you have more than one VMware region server or KVM region server, define
a host name and a unique ID for each additional region server.
v If you have more than one KVM compute node, define a host name and a
unique ID for each additional compute node.
Modifying the sample configuration files
Make a copy of the sample System Automation Application Manager configuration
files and modify the files to adapt them to your SmartCloud Orchestrator
environment.
Agentless adapter policy
The agentless adapter policy is defined in the ala_SCO.xml configuration file. In the
configuration file, set the name of the agentless adapter automation domain as in
the following example:
<PolicyInformation>
<PolicyName>SCO_ala_Policy</PolicyName>
<AutomationDomainName>SCOalaPolicy</AutomationDomainName>
<PolicyToken>0.3.0</PolicyToken>
</PolicyInformation>
You can change the SCO_ala_Policy policy name. If you change the automation
domain name in the PolicyInformation section, ensure to change all the other
occurrences of the automation domain name in the configuration files.
Central server
In the ala_SCO.xml configuration file, modify the host name of the central servers
for each service by replacing central-server-# with the actual host name of the
server, for example, myserver#.
Note: The server where System Automation Application Manager is running is not
included, because System Automation Application Manager cannot manage its
own server.
For example, the Business Process Manager services are located on
central-server-4. There are three resources defined for Business Process Manager
and for each resource the node parameter must be set to myserver4. You must
modify the configuration file for the Business Process Manager resources as in the
following example:
110 IBM SmartCloud Orchestrator 2.3: User's Guide
<Resource name="bpm-server" class="IBM.RemoteApplication" node="myserver4">
<ClassAttributesReference>
<IBM.RemoteApplicationAttributes name="IBM.RemoteApplication.bpm-server"/>
</ClassAttributesReference>
</Resource>
<Resource name="bpm-node" class="IBM.RemoteApplication" node="myserver4">
<ClassAttributesReference>
<IBM.RemoteApplicationAttributes name="IBM.RemoteApplication.bpm-node"/>
</ClassAttributesReference>
</Resource>
<Resource name="bpm-dmgr" class="IBM.RemoteApplication" node="myserver4">
<ClassAttributesReference>
<IBM.RemoteApplicationAttributes name="IBM.RemoteApplication.bpm-dmgr"/>
</ClassAttributesReference>
</Resource>
Note: System Automation Application Manager must be able to resolve to the host
names that you specify. As an alternative, you can specify the IP address of the
central servers.
Region servers
SmartCloud Orchestrator installation requires cloud regions to host the deployed
systems. SmartCloud Orchestrator can manage three types of cloud regions:
OpenStack KVM, VMware, and PowerVM. You must adapt the policy depending
on your SmartCloud Orchestrator environment. The sample policy contains one
sample entry for each cloud region types. Delete all the sample sections of your
ala_SCO.xml policy file which are not applicable to your environment and adapt
the other sections to your environment.
VMware region server
In the ala_SCO.xml configuration file, modify the sample section related to a
VMware region. If you have more than one VMware region, ensure that you have
a section for each VMware region server and define a unique identifier for each
region. In the sample file, the unique identifier is IDforVMregion. In the following
example, your unique ID is VMcloud1. You must also change the node name to the
host name or IP address of the VMware region server. The sample node name is
region-server-VM. Adapt the whole section by globally replacing the strings
IdforVMregion and region-server-VM with the unique ID for this region and the
host name of the region server.
<Resource name="VMcloud1-remoteproxy" class="IBM.RemoteApplication" node="vmcloud1">
<ClassAttributesReference><IBM.RemoteApplicationAttributes
name="IBM.RemoteApplication.remoteproxy"/>
</ClassAttributesReference>
</Resource>
Note: System Automation Application Manager must be able to resolve to the host
name that you specify. As an alternative, you can specify the IP address of the
region server.
In the installation of the region server, it is possible to either use the shared central
DB2 or a local installation of DB2 on the region server. If you use the shared
central DB2, ensure that the local DB2 service definition is commented out in the
configuration file. If you use a local DB2, uncomment the DB2 server definition
and modify the host name of the region server as for the other services.
Chapter 2. Installing 111
For a VMware region server using a local DB2, change the IDforVMregion value to
the actual region server ID and change the region server host name to the actual
value. For example:
<Resource name="VMcloud1-db2" class="IBM.RemoteApplication" node="vmcloud1">
<ClassAttributesReference>
<IBM.RemoteApplicationAttributes name="IBM.RemoteApplication.db2"/>
</ClassAttributesReference>
</Resource>
KVM region server
In the ala_SCO.xml configuration file, modify the sample section related to the
OpenStack KVM region. If you have more than one KVM region, ensure that you
have a section for each KVM region server and define a unique identifier for each
region. In the sample file, the unique identifier is IDforKVMregion. In the following
example, your unique ID is KVMcloud1. You must also change the node name to the
host name or IP address of the OpenStack KVM region server. The sample node
name is region-server-KVM. Adapt the whole section by globally replacing the
strings IdforKVMregion and region-server-KVM with the unique ID for this region
and the host name of the region server.
<Resource name="KVMcloud1-remoteproxy" class="IBM.RemoteApplication"
node="kvmcloud1">
<ClassAttributesReference><IBM.RemoteApplicationAttributes
name="IBM.RemoteApplication.remoteproxy"/>
</ClassAttributesReference>
</Resource>
Note: System Automation Application Manager must be able to resolve to the host
name that you specify. As an alternative, you can specify the IP address of the
region server.
In the installation of the region server, it is possible to either use the shared central
DB2 or a local installation of DB2 on the region server. If you use the shared
central DB2, ensure that the local DB2 service definition is commented out in the
configuration file. If you use a local DB2, uncomment the DB2 server definition
and modify the host name of the region server as for the other services.
For an OpenStack KVM region server using a local DB2, change the
IDforKVMregion value to the actual region server ID and change the region server
host name to the actual value. For example:
<Resource name="KVMcloud1-db2" class="IBM.RemoteApplication" node="kvmcloud1">
<ClassAttributesReference>
<IBM.RemoteApplicationAttributes name="IBM.RemoteApplication.db2"/>
</ClassAttributesReference>
</Resource>
KVM compute node
In addition to a region server, each OpenStack KVM cloud region contains also
several compute servers. You must modify the related sample section in the
ala_SCO.xml configuration file. If you have more than one KVM compute node,
ensure that you have a section for each KVM compute node and that the resource
name contains a unique identifier. For example, for the nova-compute resource that
is located on the KVM compute node kvmcompute1, modify the configuration file to:
112 IBM SmartCloud Orchestrator 2.3: User's Guide
<Resource name="kvmcompute1-nova-compute" class="IBM.RemoteApplication" node="kvmcompute1">
<ClassAttributesReference>
<IBM.RemoteApplicationAttributes name="IBM.RemoteApplication.openstack-nova-compute"/>
</ClassAttributesReference>
</Resource>
Adapt the whole section by globally replacing the strings IdforKVMcompute and
region-server-Compute with the unique ID for this region and the host name of
the region server.
Note: System Automation Application Manager must be able to resolve to the host
name that you specify. As an alternative, you can specify the IP address of the
compute node.
PowerVM region server
In the ala_SCO.xml configuration file, modify the sample section related to a
PowerVM region. If you have more than one PowerVM region, ensure that you
have a section for each PowerVM region server and define a unique identifier for
each region. In the sample file, the unique identifier is IDforPOWERregion. In the
following example, your unique ID is Pcloud1. You must also change the node
name to the host name or IP address of the PowerVM region server. The sample
node name is region-server-POWER. Adapt the whole section by globally replacing
the strings IdforVMregion and region-server-VM with the unique ID for this region
and the host name of the region server.
<Resource name="Pcloud1-remoteproxy" class="IBM.RemoteApplication" node="pcloud1">
<ClassAttributesReference><IBM.RemoteApplicationAttributes
name="IBM.RemoteApplication.remoteproxy"/>
</ClassAttributesReference>
</Resource>
Note: System Automation Application Manager must be able to resolve to the host
name that you specify. As an alternative, you can specify the IP address of the
region server.
In the installation of the region server, it is possible to either use the shared central
DB2 or a local installation of DB2 on the region server. If you use the shared
central DB2, ensure that the local DB2 service definition is commented out in the
configuration file. If you use a local DB2, uncomment the DB2 server definition
and modify the host name of the region server as for the other services.
For a PowerVM region server using a local DB2, change the IDforPOWERregion
value to the actual region server ID and change the region server host name to the
actual value. For example:
<Resource name="Pcloud1-db2" class="IBM.RemoteApplication" node="pcloud1">
<ClassAttributesReference>
<IBM.RemoteApplicationAttributes name="IBM.RemoteApplication.db2"/>
</ClassAttributesReference>
</Resource>
End-to-End policy
The end-to-end policy is defined in the e2e_SCO.xml configuration file. The
configuration file contains sections for the VMware region server, the OpenStack
KVM region server, and the OpenStack KVM compute node. In the configuration
file, set the name of the end-to-end automation domain as in the following
example:
Chapter 2. Installing 113
<PolicyInformation>
<PolicyName>SCO_e2e_Policy</PolicyName>
<AutomationDomainName>SCOE2EPolicy</AutomationDomainName>
<PolicyToken>0.3.0</PolicyToken>
</PolicyInformation>
You can change the SCO_e2e_Policy policy name. If you change the automation
domain name in the PolicyInformation section, ensure to change all the other
occurrences of the automation domain name in the configuration file.
Note: If you changed the automation domain name in the agentless adapter policy
you must also change the SCOalaPolicy name to the new name in this
configuration file.
Central server
In the e2e_SCO.xml configuration file, modify the host name of the central servers
for each service by replacing central-server-# with the actual host name of the
server, for example, myserver#.
Note: The server where System Automation Application Manager is running is not
included, because System Automation Application Manager cannot manage its
own server.
For example, the bpm-dmgr service is located on central-server-4. You must
modify the configuration file as in the following example:
<ResourceReference name="bpm-dmgr">
<DesiredState>Online</DesiredState>
<ReferencedResource>
<AutomationDomain>SCOalaPolicy</AutomationDomain>
<Name>bpm-dmgr</Name>
<Class>IBM.RemoteApplication</Class>
<Node>myserver4</Node>
</ReferencedResource>
</ResourceReference>
Note: System Automation Application Manager must be able to resolve to the host
names that you specify. As an alternative, you can specify the IP address of the
central servers.
For DB2 defined on the central server, modify the configuration file as in the
following example:
<ResourceReference name="db2">
<DesiredState>Online</DesiredState>
<ReferencedResource>
<AutomationDomain>SCOalaPolicy</AutomationDomain>
<Name>db2</Name>
<Class>IBM.RemoteApplication</Class>
<Node>myserver1</Node>
</ReferencedResource>
</ResourceReference>
Region servers
Check the Top Level Resource Group in the e2e_SCO.xml sample file. The sample
file contains sample lines for each type of region server. Depending on your
SmartCloud Orchestrator environment, uncomment the type of region server that
you are using and adapt it accordingly.
114 IBM SmartCloud Orchestrator 2.3: User's Guide
VMware region server
In the e2e_SCO.xml configuration file, modify the section related to the VMware
region server by replacing:
v All the IDforVMregion instances to the ID you used in the agentless adapter
policy (for example, VMcloud1)
v All the region-server-VM instances to the actual VMware region server host
name (for example, vmcloud1)
If you have more than one VMware region, ensure that you have a section for each
VMware region server and that the resource name contains a unique identifier. The
section is contained between the comments VMware Region Server Start and
VMware Region Server End.
The end-to-end policy contains sample entries for a central DB2 server. If you use a
local DB2 server, uncomment the entry related to local DB2. You can find it by
searching for Local DB2 Service. Also, for the resource group that follows this
resource definition, you must uncomment the entry line for the local DB2.
Depending if a local DB2 or the central DB2 is used, you must adapt the
relationships. There are the sample sections Relationships to central DB2 and
Relationships to local DB2. In the sample, the relationships to the central DB2
are configured, the relationship to a local DB2 are commented out. If the central
DB2 is used, either leave the relationships for local DB2 commented out or delete
them. If a local DB2 is used, comment out or delete the relationships for the central
DB2 and uncomment the relationships for the local DB2. In addition to this, you
must replace all the sample IDforVMregion occurrences with the unique ID for this
region.
Note: System Automation Application Manager must be able to resolve to the host
name that you specify. As an alternative, you can specify the IP address of the
region server.
KVM region server
In the e2e_SCO.xml configuration file, modify the section related to the OpenStack
KVM region server by replacing:
v All the IDforKVMregion instances to the ID that you used in the agentless
adapter policy (for example, KVMcloud1)
v All the region-server-KVM instances to the actual KVM region server host name
(for example, kvmcloud1)
If you have more than one OpenStack KVM region server, ensure that you have a
section for each KVM region server and that the resource name contains a unique
identifier. The section is contained between the comments OpenStack KVM Region
Server Start and OpenStack KVM Region Server End.
The end-to-end policy contains sample entries for a central DB2 server. If you use a
local DB2 server, uncomment the entry related to local DB2. You can find it by
searching for Local DB2 Service. Also, for the resource group that follows this
resource definition, you must uncomment the entry line for the local DB2.
Depending if a local DB2 or the central DB2 is used, you must adapt the
relationships. There are the sample sections Relationships to central DB2 and
Relationships to local DB2. In the sample, the relationships to the central DB2
are configured, the relationship to a local DB2 are commented out. If the central
Chapter 2. Installing 115
DB2 is used, either leave the relationships for local DB2 commented out or delete
them. If a local DB2 is used, comment out or delete the relationships for the central
DB2 and uncomment the relationships for the local DB2. In addition to this, you
must replace all the sample IDforKVMregion occurrences with the unique ID for
this region.
Note: System Automation Application Manager must be able to resolve to the host
name that you specify. As an alternative, you can specify the IP address of the
region server.
KVM compute node
In the e2e_SCO.xml configuration file, modify the section related to the OpenStack
KVM compute node by replacing:
v All the IDforKVMcompute instances to the ID that you used in the agentless
adapter policy (for example, KVMcompute1)
v All the region-server-Compute instances to the actual KVM compute node host
name (for example, kvmcompute1)
If you have more than one OpenStack KVM compute node, ensure that you have a
section for each KVM compute node and that the resource name contains a unique
identifier. The section is contained between the comments OpenStack KVM Compute
Server Start and OpenStack KVM Compute Server End.
Note: System Automation Application Manager must be able to resolve to the host
name that you specify. As an alternative, you can specify the IP address of the
compute node.
PowerVM region server
In the configuration file, modify the section related to the PowerVM region server
by replacing:
v All the IDforPOWERregion instances to the ID you used in the agentless adapter
policy (for example, Pcloud1)
v All the region-server-POWER instances to the actual PowerVM region server host
name (for example, pcloud1)
If you have more than one PowerVM region, ensure that you have a section for
each PowerVM region server and that the resource name contains a unique
identifier. The section is contained between the comments PowerVM Region Server
Start and PowerVM Region Server End.
The end-to-end policy contains sample entries for a central DB2 server. If you use a
local DB2 server, uncomment the entry related to local DB2. You can find it by
searching for Local DB2 Service. Also, for the resource group that follows this
resource definition, you must uncomment the entry line for the local DB2.
Depending if a local DB2 or the central DB2 is used, you must adapt the
relationships. There are the sample sections Relationships to central DB2 and
Relationships to local DB2. In the sample, the relationships to the central DB2
are configured, the relationship to a local DB2 are commented out. If the central
DB2 is used, either leave the relationships for local DB2 commented out or delete
them. If a local DB2 is used, comment out or delete the relationships for the central
DB2 and uncomment the relationships for the local DB2. In addition to this, you
must replace all the sample IDforPOWERregion occurrences with the unique ID for
this region.
116 IBM SmartCloud Orchestrator 2.3: User's Guide
Note: System Automation Application Manager must be able to resolve to the host
name that you specify. As an alternative, you can specify the IP address of the
region server.
Validating the policy
To check the validity of the policy xml file with the System Automation
Application Manager policy checker tool, run the following command:
eezpolicychecker /<policy_file_path>/<policy_filename>.xml
Configuring System Automation Application Manager
Configure System Automation Application Manager to work with SmartCloud
Orchestrator.
Before you begin
System Automation Application Manager requires access to all the servers to
manage the related services. Use one of the following options to set the access by
using SSH:
v Set up an SSH key infrastructure by running the following procedure:
1. Log on as root to the server where System Automation Application Manager
is installed.
2. Run the following command:
ssh-keygen -t rsa
Accept the default values and press enter when asked for the passphrase. A
new SSH key that does not require any password is created in the
/root/.ssh directory.
3. Run the following commands:
chmod 700 /root/.ssh
cat /root/.ssh/id_rsa.pub >> /root/.ssh/authorized_keys
chmod 600 /root/.ssh/authorized_keys
4. Concatenate the content of the /root/.ssh/id_rsa.pub file to the
/root/.ssh/authorized_keys file for all the central servers, all the region
servers, and all the OpenStack compute servers, by running the following
command:
ssh <servername> "echo ` cat /root/.ssh/id_rsa.pub` >> /root/.ssh/authorized_keys"
The /root/.ssh directory must have security set to 700 and the
/root/.ssh/authorized_keys file must have security set to 600 on all the
servers. To verify these settings, log on as root to all the servers from the
System Automation Application Manager server. Accept the server keys to
avoid any prompt in the following SSH accesses.
v Configure System Automation Application Manager to use user ID and
password to access the servers. To do this, an additional steps is added in the
following configuration procedure.
To ensure that System Automation Application Manager has full control on the
SmartCloud Orchestrator services, the service autostart must be disabled by
running the following procedure:
1. On Central Server 1, edit the /etc/rc.local file and comment out the following
lines to disable the DB2 autostart:
/opt/ibm/db2/v10.1/bin/db2fm -i db2inst1 -U -u
/opt/ibm/db2/v10.1/bin/db2fm -i db2inst1 -f on
Chapter 2. Installing 117
Run the following commands:
cd /etc/init
mv db2fmcd.conf db2fmcd.conf_off
2. On Central Server 2, run the following commands:
chkconfig openstack-iaasgateway off
chkconfig openstack-keystone off
chkconfig vil off
chkconfig vilProxy off
chkconfig pcg off
3. On Central Server 3, run the following commands:
chkconfig iwd off
chkconfig scui off
4. On Central Server 4, run the following command:
chkconfig bpm off
5. On the region servers, if a local DB2 is installed, edit the /etc/rc.local file and
comment out the following lines:
/opt/ibm/db2/v10.1/bin/db2fm -i db2inst1 -U -u
/opt/ibm/db2/v10.1/bin/db2fm -i db2inst1 -f on
Run the following commands:
cd /etc/init
mv db2fmcd.conf db2fmcd.conf_off
6. On the VMware region server, run the following commands:
chkconfig qpidd off
chkconfig sce off
chkconfig vilProxy off
chkconfig openstack-cinder-api off
chkconfig openstack-cinder-scheduler off
chkconfig openstack-cinder-volume off
chkconfig openstack-glance-api off
chkconfig openstack-glance-registry off
chkconfig openstack-nova-api off
chkconfig openstack-nova-cert off
chkconfig openstack-nova-conductor off
chkconfig openstack-nova-consoleauth off
chkconfig openstack-nova-network off
chkconfig openstack-nova-novncproxy off
chkconfig openstack-nova-scheduler off
chkconfig openstack-smartcloud off
7. On the KVM region server, run the following commands:
chkconfig qpidd off
chkconfig vilProxy off
chkconfig openstack-cinder-api off
chkconfig openstack-cinder-scheduler off
chkconfig openstack-cinder-volume off
chkconfig openstack-glance-api off
chkconfig openstack-glance-registry off
chkconfig openstack-nova-api off
chkconfig openstack-nova-cert off
chkconfig openstack-nova-conductor off
chkconfig openstack-nova-consoleauth off
chkconfig openstack-nova-scheduler off
8. On the KVM compute node, run the following commands:
chkconfig openstack-nova-compute off
chkconfig openstack-nova-metadata-api off
chkconfig openstack-nova-network off
chkconfig openstack-nova-novncproxy off
9. On the PowerVM, run the following commands:
118 IBM SmartCloud Orchestrator 2.3: User's Guide
chkconfig qpidd off
chkconfig sce off
chkconfig vilProxy off
chkconfig openstack-cinder-api off
chkconfig openstack-cinder-scheduler off
chkconfig openstack-cinder-volume off
chkconfig openstack-glance-api off
chkconfig openstack-glance-registry off
chkconfig openstack-nova-api off
chkconfig openstack-nova-cert off
chkconfig openstack-nova-conductor off
chkconfig openstack-nova-consoleauth off
chkconfig openstack-nova-network off
chkconfig openstack-nova-novncproxy off
chkconfig openstack-nova-scheduler off
chkconfig openstack-smartcloud off
System Automation Application Manager needs control script to manage the
SmartCloud Orchestrator applications. The control scripts are delivered in the
/iaas/scorchestrator directory on the server from which the installation is started
(Central Server 1, by default). Create on all the SmartCloud Orchestrator
management servers, region control servers, and KVM compute nodes, a directory
named /home/saam and copy all the control scripts that end with .sh from the
/iaas/scorchestrator to the /home/saam on all the servers.
About this task
To configure System Automation Application Manager to use the policies that you
defined, run the following procedure:
Procedure
1. Copy the policy configuration files to the System Automation Application
Manager server:
a. Copy the ala_SCO.xml configuration file to the /etc/opt/IBM/tsamp/eez/
aladapterPolicyPool/ directory.
b. Copy the e2e_SCO.xml configuration file to the /etc/opt/IBM/tsamp/eez/
policyPool/ directory.
2. Configure System Automation Application Manager to use the defined policies
by performing the following steps:
a. Run the cfgeezdmn command. The System Automation Application Manager
Configuration window is displayed.
b. In the Application Manager tab, click Configure. The Application Manager
Common Configuration window is displayed.
c. In the Domain tab, enter the AutomationDomainName value that you specified
in the e2e_SCO.xml configuration file, for example, SCOE2EPolicy,in the
Domain Name field.
d. Enter the host name or the IP address of the System Automation
Application Manager server.
e. In the Command Shell tab, select Use specified user credentials and enter
the administrator user ID that you created during the installation. The
default user is eezadmin. To change the password value to the password
specified during the installation, click Change..., enter the password, and
click OK.
f. Select Use FLA domain access credentials as defined under "User
credentials".
Chapter 2. Installing 119
g. In the User Credentials tab in the Credentials for accessing first-level
automation (FLA) domains section, enter root in the Generic user ID for
FLA domains field. To change the password value, click Change..., enter the
password, and click OK.
h. In the Security tab, enter /root/.ssh/id_rsa in the Keystore field.
i. Click Save to confirm your changes and close the Application Manager
Common Configuration window.
j. In the Non-clustered Nodes tab of the System Automation Application
Manager Configuration window, check Enable local Agentless Adapter
configuration, and click Configure to configure the local agentless adapter.
The Application Manager Local Agentless Adapter Configuration window is
displayed.
k. If you do not use the shared SSH for System Automation Application
Manager access to the SmartCloud Orchestrator servers, configure System
Automation Application Manager with the root credentials by performing
the following steps:
1) Click the User Credentials tab and click Add....
2) In the displayed window enter as Node name the server name or the IP
address of a SmartCloud Orchestrator server.
3) Enter the root credentials on this server in the User ID, Password, and
Password confirmation fields.
4) Repeat these steps for all the central servers, all the region servers and
all the OpenStack KVM compute servers in your SmartCloud
Orchestrator environment.
l. In the Adapter tab, click Add... and specify the AutomationDomainName value
that you specified in the ala_SCO.xml configuration file, for example,
SCOalaPolicy in the Domain Name field.
m. In the Security tab, check Enable user authentication with SSH public and
private keys in the Communication between Agentless Adapter and
remote non-clustered nodes section and enter /root/.ssh/id_rsa in the
SSH private key file field.
n. Click Save to confirm your changes and close the Application Manager
Local Agentless Adapter Configuration window.
o. Click Done.
3. Load and activate the xml configuration files by performing the following
steps:
a. Log on to System Automation Application Manager web user interface at
https://<SAAM server hostname>:9043/ibm/console/. Specify the user and
password that you defined during the installation. The default user is
eezadmin.
b. On the left pane, click Tivoli System Automation > SA Operations
Console.
c. In the Topology section, click the end-to-end automation domain name that
you specified, for example, SCOE2EPolicy.
d. In the Information Area on the right, in the Policy tab, click Activate New
Policy....
e. In the displayed panel, select the configuration file that you want to use for
the end-to-end policy and click Activate. If you see a closed lock on the
right of the policy name, click the policy name and enter the root
credentials to access the agentless adapter installed on the System
Automation Application Manager virtual machine.
120 IBM SmartCloud Orchestrator 2.3: User's Guide
The policy is activated.
f. In the Topology section, click the agentless adapter automation domain
name that you specified, for example, SCOalaPolicy.
g. In the Information Area on the right, in the Policy tab, click Activate New
Policy....
h. In the displayed panel, select the configuration file that you want to use for
the agentless adapter policy and click Activate. The policy is activated.
Results
System Automation Application Manager is configured and the policies are
activated. System Automation Application Manager checks the status of the
SmartCloud Orchestrator management services and starts them if needed. After the
services are started, System Automation Application Manager detects any outage
of the SmartCloud Orchestrator management services and automatically restart
them.
If you want to stop any services, see System Automation Application Manager in
Controlling the management stack on page 124.
(Optional) Post configuring System Automation Application
Manager with SmartCloud Orchestrator
This topic describes how to configure System Automation Application Manager to
work with SmartCloud Orchestrator with a non-root user ssh.
Before you begin
Before starting this post configuration, ensure that you have completed the steps
described in Configuring System Automation Application Manager on page 117
About this task
Note: The following commands are all run as root on the server indicated, shell
for lists with the server names should not be put into "".
Procedure
1. Clean up the root access: If root-ssh is already working, do the following to
clean up the root access:
a. On System Automation Application Manager, stop System Automation
Application Manager to avoid error messages during the change:
eezaladapter stop
eezdmn -SHUTDOWN
/opt/IBM/WebSphere/AppServer/bin/stopServer.sh server1 -username <yourname> -password <yourpassword>
su db2inst1 -c /home/db2inst1/sqllib/adm/db2stop
b. Delete the /home/saam scripts on all SmartCloud Orchestrator servers (This
command is executed from the System Automation Application Manager
server with root ssh still working):
for i in <list of your SCO servers>; do ssh $i "rm -rf /home/saam"; done
c. Delete authorized_keys from /root/.ssh/.
2. Copy the sample files in the SmartCloud Orchestrator package:
Copy $install-images/installer/tools/scorchestrator/TSA_AM_Policy/
ala_SCO_nonroot_sample/* to <your_path> on the System Automation
Application Managerserver as root.
Chapter 2. Installing 121
Note: The sample files are all configured using a user named mechasaam.
Search for this in the sample files and change them to the user name you
want to use.
3. Prepare the System Automation Application Manager server for non-root ssh
to the SmartCloud Orchestrator servers:
a. On System Automation Application Manager, create a new user
<yourmechid> and set the password:
useradd -m <yourmechid>
passwd <yourmechaid> #enter at the prompt <yourmechapwd>
b. On System Automation Application Manager, create a directory .ssh,
generate the ssh keys for <yourmechid> and set file permissions:
su - <yourmechid> -c "mkdir .ssh"
su - <yourmechid> -c "ssh-keygen -q -t rsa -N -f ~/.ssh/id_rsa"
su - <yourmechid> -c "chmod 700 .ssh"
c. Copy wrap.py to the path where the control scripts are stored:
/home/<yourmechid>/root/
d. Copy sudoers.saam to the path where the control scripts are stored:
/home/<yourmechid>/root/
e. On System Automation Application Manager, copy the sample files to
<yourmechid> home and change users:
cp -R <your_path>/* /home/yourmechid/
chown <yourmechid>:<yourmechidgroup> /home/<yourmechid>/*
4. Prepare the SmartCloud Orchestrator servers for non-root ssh access:
Note: This must be performed on all Central Servers and Region Servers.
a. On the SmartCloud Orchestrator servers, create a new user <yuormechid>
and set the password:
useradd -m <yourmechid>
passwd <yourmechaid> #enter at the prompt <yourmechapwd>
b. On the SmartCloud Orchestratorservers, create a directory .ssh and set file
permits.
c. On the SmartCloud Orchestrator servers, create a root owned directory
that contains control scripts:
mkdir /home/<yourmechid>/root
chmod 755 /home/<yourmechid>/root
5. Copy the ssh keys from System Automation Application Manager to the
SmartCloud Orchestrator servers and verify that the new user <yourmechid>
can access all SmartCloud Orchestrator servers without password:
a. On System Automation Application Manager, run the following command:
for i in <list of your SCO servers>; do su - <yourmechid> -c "scp ~/.ssh/id_rsa.pub $i:~/.ssh/authorized_keys"; done
Note: It is important in the command that you accept the server key and
the password required is of <yourmechid>.
b. Verify that <yourmechid> on the System Automation Application Manager
server can ssh without interruption to <yourmechid> on your SmartCloud
Orchestrator servers:
su - <yourmechid> -c "ssh <yourmechid>@$SCO_server_ip"
6. Create directory for control scripts and set file permits:
a. On Central Server 1 run:
for i in <list of your SCO servers>;do scp /iaas/scorchestrator/*.sh root@$i:/home/<yourmechid>/root/; done
for i in <list of your SCO servers>;do ssh $i "chmod 755 /home/<yourmechid>/root/*.sh"; done
122 IBM SmartCloud Orchestrator 2.3: User's Guide
b. On Central Server 2 run:
ln -s /home/library/manageVilComponents.sh /home/<yourmechid>/root/manageVilComponents.sh
c. On the Region Servers run:
ln -s /home/library/manageVilProxyComponents.sh /home/<yourmechid>/root/manageVilProxyComponents.sh
7. Deploy wrapper script on the SmartCloud Orchestrator servers:
a. On the System Automation Application Manager server, create a directory
and set file permits:
for i in <list of your SCO servers>;do su - <yourmechid> -c "ssh $i mkdir ~/wrap; chmod 700 ~/wrap"; done
b. On the System Automation Application Manager server, copy wrap script
to wrap directory and set file permit:
for i in <list of your SCO servers>;do su - <yourmechid> -c "scp wrap.py <yourmechid>@$i:~/wrap/"; done
for i in <list of your SCO servers>;do su - <yourmechid> -c "scp sample.askpass.sh sample.bashrc <yourmechid>@$i:"; done
for i in <list of your SCO servers>;do su - <yourmechid> -c "ssh $i chmod 700 ~/wrap/wrap.py; chmod 600 ~/sample.askpass.sh; chmod 600 ~/sam
8. Deploy sudo rules for the new user <yourmechid>:
a. On System Automation Application Manager, copy the sudo rule to the
SmartCloud Orchestrator servers:
for i in <list of your SCO servers>;do scp ~/non-root/saam.sudoers $i:/etc/sudoers.d/saam; done
b. On System Automation Application Manager, set file permission:
for i in <list of your SCO servers>;do ssh $i "chmod 440 /etc/sudoers.d/saam"; done
9. Adapt non-root_ala_SCO.xml as the standard ala_SCO.xml and copy to the
correct directory:
To modify the ala_SCO.xml, refer to the standard SmartCloud Orchestrator
documentation at Modifying the sample configuration files on page 110.
Also, follow the documentation for the e2e policy .
10. Reconfiguring System Automation Application Manager:
On the System Automation Application Manager server:
a. Run the cfgeezdmn command. The System Automation Application
Manager Configuration window is displayed .
b. In the Non-clustered Nodes tab of the System Automation Application
Manager Configuration window, click Configure to configure the local
agentless adapter.
c. The Application Manager Local Agentless Adapter Configuration
window is displayed.
d. In the Security tab, check Enable user authentication with SSH public
and private keys in the Communication between Agentless Adapter and
remote non-clustered nodes section and enter /home/<yourmechid>/.ssh/
id_rsa in the SSH private key file field.
e. Click Save to confirm your changes and close the Application Manager
Local Agentless Adapter Configuration window.
11. Start System Automation Application Manager:
On the System Automation Application Manager server, run the following
commands:
su db2inst1 -c /home/db2inst1/sqllib/adm/db2start
/opt/IBM/WebSphere/AppServer/bin/startServer.sh server1
eezdmn start
eezaladapter start
Chapter 2. Installing 123
Controlling the management stack
Use System Automation Application Manager to control the SmartCloud
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 a SmartCloud Orchestrator virtual
machine, you must stop the SmartCloud 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 System Automation Application Manager on page 125. 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 a SmartCloud 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>:9043/ibm/console/. Specify the user and
password that you defined during the installation. The default user is eezadmin.
2. On the left pane, click Tivoli System Automation > SA Operations Console. In
the console, you can see if all the services are working according to the defined
policies.
3. In the Topology section, click the end-to-end automation domain name that
you specified, for example, SCOE2EPolicy.
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.
5. If you want to stop the whole SmartCloud Orchestrator management stack,
click Request Offline... in the Resource Group Status section. Enter a comment
in the displayed window and click Submit.
6. If you want to stop a specific resource, click on the resource name to select it
and click Request Offline... in the Resource Reference Status section. Enter a
comment in the displayed window and click Submit. The service and all the
dependent services are stopped.
7. To restart a resource or a resource group, click Cancel Request in the Resource
Reference Status or Resource Group Status section.
Results
You stopped and restarted the SmartCloud Orchestrator services.
For more information about using System Automation Application Manager, see
the System Automation Application Manager, Administrator's and User's Guide.
124 IBM SmartCloud Orchestrator 2.3: User's Guide
Troubleshooting System Automation Application Manager
Troubleshoot problems that might occur when running System Automation
Application Manager.
Resource in error
If a resource is in error, perform the following steps:
1. Log on to the System Automation Application Manager web user interface at
https://<SAAM server hostname>:9043/ibm/console/. Specify the user and
password that you defined during the installation. The default user is eezadmin.
2. On the left pane, click Tivoli System Automation > SA Operations Console.
An error icon is displayed for the end-to-end automation policy.
3. In the Topology section, click the end-to-end automation domain name that
you specified, for example, SCOE2EPolicy.
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. Continue to expand the
resource groups where the error icon is displayed until you select the resource
in error. In the Resource Reference Status section the following message is
displayed:
The resource has an unrecoverable problem.
5. Click Reset to try to recover the problem by restarting the resource with the
System Automation Application Manager control.
6. To understand the cause of the problem, you can check the log files by
performing the following steps:
a. In the Topology section, click the agentless adapter domain name that you
specified, for example, SCOalaPolicy.
b. In the General tab of Information Area section, click View Log in the Log
section.
c. In the Log Viewer window, scroll down the message list until you find an
entry marked as ERROR. You can read the related log to find the cause of the
problem.
Using /etc/hosts
If the /etc/hosts file is used for System Automation Application Manager to
resolve the host name of the SmartCloud 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.
Stopping automation for a resource or a resource group for manual
interaction
If you need to manual interact with a SmartCloud Orchestrator management stack
resource or resource group, you must stop the System Automation Application
Manager automation to avoid that System Automation Application Manager
controls the resource and tries to bring it 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 stop the System Automation Application Manager automation,
perform the following steps:
1. Log on to the System Automation Application Manager web user interface at
https://<SAAM server hostname>:9043/ibm/console/. Specify the user and
password that you defined during the installation. The default user is eezadmin.
Chapter 2. Installing 125
2. In the Topology section, click the end-to-end automation domain name that
you specified, for example, SCOE2EPolicy.
3. In the Resources section for the policy, click the SCO resource group to expand
the list of all the related resources and resource groups.
4. Click the resource or resource group for which you want to temporarily
suspend the System Automation Application Manager automation.
5. Click Suspend Automation... in the Resource Reference Status or Resource
Group Status section. 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.
6. After you finish to manually interact with the resource or the resource group,
you can resume the automation by clicking Resume Automation. System
Automation Application Manager brings the resource or the resource group to
the desired state.
Gathering information for problem determination
In the default configuration file for the pdcollect tool, the log collection for System
Automation Application Manager is not enabled.
To collect logs for System Automation Application Manager, add the following
lines in the Environment.xml file:
<host hostname="SAAM_host">
<component name="ALL"/>
<component name="SAAM"/>
</host>
You must replace the SAAM_host string with the host name or the IP address of the
System Automation Application Manager virtual machine.
For more information about the pdcollect tool, see Problem determination with
pdcollect tool on page 1078.
Ports used by SmartCloud Orchestrator
This topic describes the ports used by SmartCloud Orchestrator across the stack of
components.
Table 13. Ports used by SmartCloud Orchestrator
Port
number Protocol From To
9443 HTTPS Image Construction and
Composition Tool
Virtual Image Library server on
Central Server 2
9443 HTTPS Workload Deployer Virtual Image Library server on
Central Server 2
9443 HTTPS Web browser with which the
SmartCloud UI is accessed
Virtual Image Library server on
Central Server 2
9443 HTTPS Web browser with which the
Virtual Image Library UI is
accessed
Virtual Image Library server on
Central Server 2
9043 HTTPS Web browser with which the
WebSphere Web console is
accessed
Virtual Image Library server on
Central Server 2
126 IBM SmartCloud Orchestrator 2.3: User's Guide
Table 13. Ports used by SmartCloud Orchestrator (continued)
Port
number Protocol From To
9060 HTTP Web browser with which the
WebSphere Web console is
accessed
Virtual Image Library server on
Central Server 2
4444 Virtual Image Library proxy Virtual Image Library proxy
9443 HTTPS Business Process Designer Business Process Manager on
Central Server 4
2809 TCP Business Process Designer Business Process Manager on
Central Server 4
7276 TCP Business Process Designer Business Process Manager on
Central Server 4
7286 TCP Business Process Designer Business Process Manager on
Central Server 4
9403 HTTP Business Process Designer Business Process Manager on
Central Server 4
9080 HTTP Business Process Designer Business Process Manager on
Central Server 4
9100 ORB Business Process Designer Business Process Manager on
Central Server 4
9810 ORB Business Process Designer Business Process Manager on
Central Server 4
9405 RMI/IIOP,
SSL
Business Process Designer Business Process Manager on
Central Server 4
9201 RMI/IIOP,
SSL
Business Process Designer Business Process Manager on
Central Server 4
9080 HTTP Web browser with which
Business Process Manager is
accessed
Business Process Manager on
Central Server 4
9080 HTTP SmartCloud UI on Central
Server 3
Business Process Manager on
Central Server 4
80 HTTP Business Process Manager on
Central Server 4
Workload Deployer on Central
Server 3
80 HTTP SmartCloud UI on Central
Server 3
internet (infocenter)
443 HTTPS Business Process Manager on
Central Server 4
Workload Deployer on Central
Server 3
443 HTTPS Virtual Image Library server
on Central Server 2
VMware vCenter
443 HTTPS Web browser with which the
Image Construction and
Composition Tool is accessed
Image Construction and
Composition Tool
443 HTTPS SmartCloud Entry driver VMware vCenter
7443 HTTPS Web browser with which the
SmartCloud UI is accessed
SmartCloud UI on Central
Server 3
9973 HTTP SmartCloud UI on Central
Server 3
IAAS Gateway on Central Server
2
9973 HTTP Workload Deployer on
Central Server 3
IAAS Gateway on Central Server
2
Chapter 2. Installing 127
Table 13. Ports used by SmartCloud Orchestrator (continued)
Port
number Protocol From To
9973 HTTP Image Construction and
Composition Tool
IAAS Gateway on Central Server
2
6379 Virtual Image Library proxy Virtual Image Library proxy on
Central Server 2
8123 HTTP Virtual Image Library server
on Central Server 2
Virtual Image Library proxy
22 SSH Image Construction and
Composition Tool
Extended image
22 SSH Workload Deployer on
Central Server 3
Deployed virtual systems
445 TCP Image Construction and
Composition Tool
Extended image (Windows only)
445 TCP Workload Deployer on
Central Server 3
Deployed virtual systems
(Windows only)
80 Image Construction and
Composition Tool
Extended image
9797 HTTP Virtual Image Library server
on Central Server 2
Public Cloud Gateway
9797 HTTP Workload Deployer on
Central Server 3
Public Cloud Gateway
8776 HTTP OpenStack cinder
9292 HTTP Virtual Image Library server
on Central Server 2
OpenStack glance
5000 HTTP SmartCloud UI on Central
Server 3
OpenStack keystone
5000 HTTP Workload Deployer on
Central Server 3
OpenStack keystone
5000 HTTP Virtual Image Library server
on Central Server 2
OpenStack keystone
35357 HTTP SmartCloud UI on Central
Server 3
OpenStack keystone
35357 HTTP Workload Deployer on
Central Server 3
OpenStack keystone
35357 HTTP Virtual Image Library server
on Central Server 2
OpenStack keystone
8774 HTTP Workload Deployer on
Central Server 3
OpenStack nova
8774 HTTP Virtual Image Library server
on Central Server 2
OpenStack nova
902 HTTP Virtual Image Library proxy VMware ESXis
53 UDP Central Server 1 (if DNS
server is installed)
Any system using the DNS
server
123 UDP Central Server 1 (if NTP
server is installed)
Any system using the NTP
server
ICMP Workload Deployer on
Central Server 3
Deployed virtual systems
128 IBM SmartCloud Orchestrator 2.3: User's Guide
Table 13. Ports used by SmartCloud Orchestrator (continued)
Port
number Protocol From To
ICMP Extended image (Windows
only)
Image Construction and
Composition Tool
ICMP Deployed virtual systems
(Windows only and only if
using add-ons and script
packages)
Workload Deployer on Central
Server 3
139 TCP Workload Deployer on
Central Server 3
Deployed virtual systems
(Windows only)
50000 TCP Virtual Image Library Server
on Central Server 2
DB2 Service on Central Server 1
50000 TCP Workload Deployer on
Central Server 3
DB2 Service on Central Server 1
50000 TCP Business Process Manager on
Central Server 4
DB2 Service on Central Server 1
50000 TCP OpenStack Service on Region
Server
If share_central_db="yes" in
region.server.cfg, DB2 Service
on Central Server 1
Note: For more information on the ports, refer to file /etc/services on each
server.
Chapter 2. Installing 129
130 IBM SmartCloud Orchestrator 2.3: User's Guide
Chapter 3. Getting started
After installing and configuring SmartCloud Orchestrator, learn how to start to use
the product to work with virtual images in your cloud environment.
Before you begin
SmartCloud Orchestrator offers many features to manage your cloud infrastructure.
For more information, see Product features on page 5.
SmartCloud Orchestrator is based on OpenStack to manage the following types of
hypervisor:
v KVM
v VMware ESX (through VMware vCenter)
v IBM PowerVM (through VMControl)
For more information about OpenStack, see Overview of OpenStack on page 8.
Be sure that your SmartCloud Orchestrator environment is started and working.
For more information about starting SmartCloud Orchestrator, see Starting or
stopping SmartCloud Orchestrator on page 135.
Be sure that you have a user to perform the following procedure. A user with the
admin role can perform any step in the procedure. For more information about
users, see Managing users, projects, and domains on page 149. For more
information about roles, see User roles in SmartCloud Orchestrator on page 151.
About this task
To start to work with SmartCloud Orchestrator, perform the following steps:
Procedure
1. Access the SmartCloud Orchestrator user interface.
Log in to the SmartCloud Orchestrator following URL:
https://central-server-3_fqdn
where central-server-3_fqdn is the fully-qualified domain name of Central
Server 3.
Note: Do not use the IP address to access the SmartCloud Orchestrator user
interface.
When logging in to the SmartCloud Orchestrator user interface, you can specify
a scope for the user by entering the domain to which the user belongs. If you
do not specify any 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 in order to access cloud resources.
After logging 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 users, projects,
and domains on page 149.
Copyright IBM Corp. 2013, 2014 131
For more information about accessing SmartCloud Orchestrator user interfaces,
see Accessing SmartCloud Orchestrator user interfaces on page 135.
2. Create virtual images in your environment.
SmartCloud Orchestrator supports virtual images that contain the scp-cloud-init
script and the Activation Engine. SmartCloud Orchestrator also supports virtual
images that run on VMware, if the images contain the Activation Engine and
the VMware tools are installed. Use the Image Construction and Composition
Tool to create images that are supported by SmartCloud Orchestrator.
SmartCloud Orchestrator also supports virtual images that run on PowerVM.
For more information, see Working with IBM Image Construction and
Composition Tool on page 387.
You can also create images in your OpenStack environment by following the
procedure described in Creating new images or using existing images on
page 488.
3. Define virtual images to SmartCloud Orchestrator.
Before you can use the virtual images that you created, you must define them
to the SmartCloud Orchestrator environment by using one of the following
procedures:
v If you want to import an OVA image file, follow the procedure described in
Importing a virtual image to the catalog on page 289.
When you import an image, the image location can be either an HTTP URL
or you can transfer the image using Secure Copy Protocol (SCP) with the
following format: <hostname>:/path. The images that are located in the
/data/repos/scp directory on Central Server-1 can be accessed by specifying
the HTTP URL in the following format:
http://central-server-1_ip/scp/my_virtual_image.ova
where central-server-1_ip is the IP address of Central Server-1.
The image that you imported is stored in the reference repository in the
Virtual Image Library. Before you can deploy the virtual image in a pattern,
you must copy the image to an OpenStack operational repository (KVM,
VMware, or PowerVM). Access the Virtual Image Library user interface by
clicking Images & Patterns > Virtual Image Library, and follow the
procedure described in Copying an image from the reference repository on
page 322.
In Virtual Image Library you can also perform advance management tasks
on the virtual images. For more information, see Working with Virtual
Image Library on page 295.
v If you want to define the virtual images that are stored in your OpenStack
environment, follow the procedure described in Registering a virtual image
on page 290.
When you register an image, you can choose it from a list of the available
images available in the OpenStack region that you selected. If you are using
a VMware hypervisor or a PowerVM hypervisor, the available images are
automatically discovered in your OpenStack environment when the vCenter
connection or VMControl connection is established. If you are using a KVM
hypervisor, before registering an image to SmartCloud Orchestrator, you
must add the image to your OpenStack environment. For more information,
see Adding images to OpenStack on page 294.
You can also perform advance management tasks on the images that are
available in your OpenStack environment by using Virtual Image Library. For
more information, see Working with Virtual Image Library on page 295.
4. Create an environment profile.
132 IBM SmartCloud Orchestrator 2.3: User's Guide
Use environment profiles to group related deployment configuration options
together, and deploy from a single pattern. For more information about
environment profiles, see Environment profiles overview on page 221.
Before you can deploy a virtual image, you must create an environment profile
by following the procedure described in Creating an environment profile on
page 223. When you create the environment profile, define the cloud group to
which you want to deploy the virtual image.
5. Create a virtual system pattern.
A virtual system pattern is one or more virtual images and applications from
the SmartCloud Orchestrator catalog that implements a deployment topology.
For more information about virtual system pattern, see Working with virtual
system patterns on page 511.
Before you can deploy a virtual image, you must create a virtual system pattern
by following the procedure described in Creating a virtual system pattern on
page 519. When you create the virtual system pattern, add the virtual image
that you want to deploy as a part of the virtual system pattern.
6. Deploy a virtual system pattern.
You can deploy a virtual image by deploying the virtual system pattern that
contains it. To deploy a virtual system pattern, follow the procedure described
in Deploying a virtual system pattern on page 547. When you deploy a
virtual system pattern, specify to use the environment profile that you created.
What to do next
You can create custom orchestration workflows in the Business Process Manager
user interface and run them in your SmartCloud Orchestrator environment. For
more information, see Chapter 7, Managing orchestration workflows, on page
763.
Chapter 3. Getting started 133
134 IBM SmartCloud Orchestrator 2.3: User's Guide
Chapter 4. Administering
After you have installed SmartCloud Orchestrator, you can start your environment,
configure optional settings, define users and projects, build your cloud
environment by defining cloud resources, and populate the catalog as described in
the following sections.
Starting or stopping SmartCloud Orchestrator
This topic describes how to start or stop SmartCloud Orchestrator.
Before you begin
Before running the SCOrchestrator.py script, you must review the Managing
services with SCOrchestrator.py topic and ensure that the assumptions that are
described are satisfied.
About this task
You can run the SCOrchestrator.py script to start, stop and view the status of the
SmartCloud Orchestrator components.
For information about running the SCOrchestrator.py script, see Running the
SCOrchestrator.py script on page 138.
If you are using System Automation Application Manager, SmartCloud
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 Using System Automation Application Manager on page 107.
Accessing SmartCloud Orchestrator user interfaces
SmartCloud Orchestrator provides several user interfaces to access the various
components.
To correctly display the SmartCloud Orchestrator user interface, use one of the
following browsers:
v Internet Explorer versions 9, 10, and 11
v Firefox Extended Support Release 24
v Google Chrome versions 29, 30, and 31
To access the main SmartCloud Orchestrator user interface, log in to the following
URL:
https://central-server-3_fqdn
where central-server-3_fqdn is the fully-qualified domain name of Central Server
3.
Note: Do not use the IP address to access the SmartCloud Orchestrator user
interface.
Copyright IBM Corp. 2013, 2014 135
When logging in to the SmartCloud Orchestrator user interface, you can specify a
scope for the user by entering the domain to which the user belongs. If you do not
specify any 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 in order to access cloud resources. After logging 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 users, projects, and domains on page 149.
Note: In SmartCloud Orchestrator, the following limitations apply:
v You cannot log in by using a user name that contains a : (colon) character.
v You cannot log in by using a password that contains a @ character.
v You cannot log in if the primary project to which your user is assigned is
disabled.
v You cannot log in to the same SmartCloud Orchestrator user interface with more
than one browser session on the same machine. If you need to log in to the
SmartCloud Orchestrator user interface with two browser sessions on the same
machine, use different browsers for the two sessions as, for example, an Internet
Explorer browser and a Firefox browser.
To access the Virtual Image Library user interface, log in to the following URL:
https://central-server-2:9443/ImageLibraryUI
where central-server-2 is the host name or the IP address of the machine where
Virtual Image Library has been installed. The default user name and password are
admin/passw0rd.
You can also launch the Virtual Image Library user interface by clicking Images &
Patterns > Virtual Image Library in the menu bar of the SmartCloud Orchestrator
user interface.
To access the Image Construction and Composition Tool user interface, log in to
the following URL:
https://ICCT_server/icn/ui
where ICCT_server is the host name or the IP address of the machine where the
Image Construction and Composition Tool has been installed. The default user
name and password are iconadmin/object00.
To access IBM Business Process Manager user interface:
1. Open SmartCloud Orchestrator user interface.
2. Click Administration > Process Center.
You might also use Business Process Manager Process Designer user interface, but
this application must be installed locally on your computer. The download link for
the installation package is available in Business Process Manager Process Center.
To view the SmartCloud Orchestrator user interface in another language, set the
language option in your browser. Select the language that you want as the first one
in 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.
136 IBM SmartCloud Orchestrator 2.3: User's Guide
Managing the services
The following topics describe how to manage the SmartCloud Orchestrator
services.
Managing services with SCOrchestrator.py
The SCOrchestrator.py Python script can start, stop and provide information about
the status of SmartCloud Orchestrator services.
SmartCloud 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 on several virtual appliances. Because some of these modules
and services require to be started and stopped in sequence, SmartCloud
Orchestrator is delivered with the SCOrchestrator.py script that you can use it to
start, stop and monitor the status of a single component or to start and stop all the
SmartCloud Orchestrator services with one command. If you use the
SCOrchestrator.py script to start or stop all the SmartCloud Orchestrator services,
the services are started or stopped in the correct sequence and all the dependencies
are resolved.
If you use System Automation Application Manager to manage the SmartCloud
Orchestrator services, do not use the SCOrchestrator.py script. For more
information, see Using System Automation Application Manager on page 107.
The SCOrchestrator.py script uses two XML files to obtain the information about
the environment and the components:
v SCOEnvironment.xml
v SCOComponents.xml
v SCOComponents_work.xml
The XML files define the names and the start/stop priority of the SmartCloud
Orchestrator services.
The following tasks are performed when you run SCOrchestrator.py:
1. The script reads the SCOEnvironment.xml and the SCOComponents.xml files.
2. The script obtains the computeNodes of the system and enhances the
SCOEnvironment_work.xml file with the computeNodes.
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 can be found 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 hostname. You can start or stop all modules of a specific virtual
machine by using the hostname of the machine. As a result, all components of that
machine are started or stopped.
Note: Because some SmartCloud Orchestrator services must be started in a given
sequence to work correctly, it is not recommended to start or stop any single
services but only to start or stop the whole SmartCloud Orchestrator stack. Only
Chapter 4. Administering 137
experienced administrators who are aware of the dependencies between the
SmartCloud 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 support on management systems.
Running the SCOrchestrator.py script
You can run the SCOrchestrator.py script to start, stop and view the status of the
SmartCloud Orchestrator components.
Procedure
1. As root, navigate to /iaas/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 show this help message and exit
-s, --start start SC Orchestrator with default parameters in
default sequence
--halt, --shutdown, --stop
stops SC Orchestrator in default sequence
--status status of components of SC Orchestrator
-c SCOComponents.xml, --componentfile=SCOComponents.xml
defines the input properties filename defaultname is
SCOComponents.xml
-e SCOEnvironment.xml, --environmentfile=SCOEnvironment.xml
defines the environment filename defaultname is
SCOEnvironment.xml
-n SYSTEMSLIST, --hostnames=SYSTEMSLIST
list of hostnames to start/stop format
hostname1,hostname2,hostname3,...
-p COMPONENTSLIST, --components=COMPONENTSLIST
list of components to start/stop format
component1,component2,component3,...
--version show PDCollector version and exit
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"
138 IBM SmartCloud Orchestrator 2.3: User's Guide
b. On Central Server 1:
Generate the ssh keys for <yourmechid> and copy it to all SmartCloud
Orchestrator servers:
su - <yourmechid> -c "ssh-keygen -q -t rsa -N -f ~/.ssh/id_rsa"
Here $i stands for the IP address of each SmartCloud Orchestrator server:
[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 SmartCloud
Orchestrator servers without interruption:
su - <yourmechid> -c "ssh <yourmechid>@$SCO_server_ip"
2. Copy the /iaas/scorchestrator and change the directory permission:
On Central Server 1, copy the directory /iaas/scorchestrator to
/home/<yourmechid>:
cp -rf /iaas/scorchestrator /home/<yourmechid>
Change the owner of /home/<yourmechid>:
chown -R <yourmechid>:<yourmechidgroup> /home/<yourmechid>/
3. On each of the SmartCloud 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, modify the file /home/<yourmechid>/scorchestrator/
SCOrchestrator.py:
sed -i "s/\.\//sudo \.\//g" /home/<yourmechid>/scorchestrator/SCOrchestrator.py
sed -i -e s/^SSH_USER.*/SSH_USER = "<yourmechid>>"/g/home/
<yourmechid>/scorchestrator/SCOrchestrator.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 138.
Chapter 4. Administering 139
Example SCOComponents.xml
This topic provides an example of an SCOComponents.xml file that is used by
SCOrchestrator.py.
<SCOComponents>
<component name="db2" scriptName="db2ctrl.sh" workdir="/tmp"
startPrio="10" stopPrio="290"/>
<component name="qpidd" scriptName="qpiddctrl.sh" workdir="/tmp"
startPrio="30" stopPrio="270"/>
<component name="sce" scriptName="scectrl.sh" workdir="/tmp"
startPrio="40" stopPrio="260"/>
<component name="openstack-keystone" openstackService="true"
scriptName="openstack-servicectrl.sh" workdir="/tmp"
startPrio="70" stopPrio="230"/>
<component name="openstack-cinder-api" openstackService="true"
scriptName="openstack-servicectrl.sh" workdir="/tmp"
startPrio="80" stopPrio="220"/>
<component name="openstack-cinder-scheduler" openstackService="true"
scriptName="openstack-servicectrl.sh" workdir="/tmp"
startPrio="90" stopPrio="210"/>
<component name="openstack-cinder-volume" openstackService="true"
scriptName="openstack-servicectrl.sh" workdir="/tmp"
startPrio="100" stopPrio="200"/>
<component name="openstack-glance-api" openstackService="true"
scriptName="openstack-servicectrl.sh" workdir="/tmp"
startPrio="110" stopPrio="190"/>
<component name="openstack-glance-registry" openstackService="true"
scriptName="openstack-servicectrl.sh" workdir="/tmp"
startPrio="120" stopPrio="180"/>
<component name="openstack-nova-api" openstackService="true"
scriptName="openstack-servicectrl.sh" workdir="/tmp"
startPrio="130" stopPrio="170"/>
<component name="openstack-nova-cert" openstackService="true"
scriptName="openstack-servicectrl.sh" workdir="/tmp"
startPrio="140" stopPrio="160"/>
<component name="openstack-nova-conductor" openstackService="true"
scriptName="openstack-servicectrl.sh" workdir="/tmp"
startPrio="150" stopPrio="150"/>
<component name="openstack-nova-cells" openstackService="true"
scriptName="openstack-servicectrl.sh" workdir="/tmp"
startPrio="160" stopPrio="140"/>
<component name="openstack-smartcloud" openstackService="true"
scriptName="openstack-servicectrl.sh" workdir="/tmp"
startPrio="170" stopPrio="130"/>
<component name="openstack-nova-metadata-api" openstackService="true"
scriptName="openstack-servicectrl.sh" workdir="/tmp"
startPrio="180" stopPrio="120"/>
<component name="openstack-nova-network" openstackService="true"
scriptName="openstack-servicectrl.sh" workdir="/tmp"
startPrio="190" stopPrio="110"/>
<component name="openstack-nova-scheduler" openstackService="true"
scriptName="openstack-servicectrl.sh" workdir="/tmp"
startPrio="200" stopPrio="100"/>
<component name="openstack-nova-consoleauth" openstackService="true"
scriptName="openstack-servicectrl.sh" workdir="/tmp"
startPrio="210" stopPrio="90"/>
<component name="openstack-nova-novncproxy" openstackService="true"
scriptName="openstack-servicectrl.sh" workdir="/tmp"
startPrio="220" stopPrio="80"/>
<component name="openstack-nova-compute" openstackService="true"
scriptName="openstack-servicectrl.sh" workdir="/tmp"
startPrio="230" stopPrio="70"/>
<component name="openstack-iaasgateway" openstackService="true"
scriptName="openstack-servicectrl.sh" workdir="/tmp"
startPrio="240" stopPrio="60"/>
<component name="vil" scriptName="vilctrl.sh" workdir="/tmp"
startPrio="250" stopPrio="50"/>
140 IBM SmartCloud Orchestrator 2.3: User's Guide
<component name="vilProxy" scriptName="vilProxyCtrl.sh" workdir="/tmp"
startPrio="215" stopPrio="55"/>
<component name="iwd" scriptName="iwdctrl.sh" workdir="/tmp"
startPrio="260" stopPrio="40"/>
<component name="swi" scriptName="swictrl.sh" workdir="/tmp"
startPrio="270" stopPrio="30"/>
<component name="pcg" scriptName="pcgctrl.sh" workdir="/tmp"
startPrio="280" stopPrio="20"/>
<component name="bpm-dmgr"
scriptName="bpm-dmgrctrl.sh" workdir="/tmp"
startPrio="290" stopPrio="10"/>
<component name="bpm-node"
scriptName="bpm-nodectrl.sh" workdir="/tmp"
startPrio="291" stopPrio="9"/>
<component name="bpm-server"
scriptName="bpm-serverctrl.sh" workdir="/tmp"
startPrio="292" stopPrio="8"/>
</SCOComponents>
Example SCOEnvironment.xml
This topic provides an example of SCOEnvironment.xml file that is used by
SCOrchestrator.py.
This file is automatically generated by the installation procedure when the central
SmartCloud 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.
<SCOEnvironment>
<host hostname="central-server-1">
<component name="db2"/>
</host>
<host hostname="central-server-2">
<component name="qpidd"/>
<component name="openstack-keystone"/>
<component name="openstack-iaasgateway"/>
<component name="pcg"/>
<component name="vil"/>
</host>
<host hostname="central-server-3">
<component name="iwd"/>
<component name="swi"/>
</host>
<host hostname="central-server-4">
<component name="bpm-dmgr"/>
<component name="bpm-node"/>
<component name="bpm-server"/>
</host>
</SCOEnvironment>
Backing up and restoring the services
This topic describes how to backup and restore the core services.
About this task
To backup and restore Workload Deployer and Virtual Image Library, as these
services are installed on virtual machines, backup and restore the related virtual
machine.
To backup and restore Business Process Management, refer to the documentation at
http://pic.dhe.ibm.com/infocenter/dmndhelp/v8r0m1/index.jsp?topic=
%2Fcom.ibm.wbpm.mon.trbl.doc%2Ftopics%2Fcadm_recovery_scenarios.html.
Chapter 4. Administering 141
To backup and restore OpenStack, refer to the OpenStack documentation.
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 and to send the new
password to locally authenticated users when the product administrator changes it.
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, a virtual system pattern, or a virtual image 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.
v Virtual system pattern is created.
v Virtual system pattern is going to be removed due to expired reservation.
v Virtual image is exported.
v Virtual image is imported.
A Simple Mail Transfer Protocol (SMTP) server must be configured for use with
SmartCloud Orchestrator.
Procedure
To configure the mail delivery function, use either the graphical user interface or
the command-line interface as described in the following procedures:
v Configuring email delivery with the user interface on page 143
v Mail delivery command-line interface reference on page 841
142 IBM SmartCloud Orchestrator 2.3: User's Guide
Configuring email delivery with the user interface
Configure the mail delivery function to send event notifications and password
change notices.
Before you begin
You must be assigned the admin role to perform these steps.
About this task
To configure the mail delivery function, specify the required Simple Mail Transfer
Protocol (SMTP) server to be used for SmartCloud Orchestrator by performing the
following steps:
Procedure
1. Click Administration > Settings.
2. Expand Mail Delivery.
3. Add an SMTP server. Provide the IP address or host name for the SMTP server
to be used for SmartCloud 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 and
password change notices.
Virtual Image Library configuration files
You can optionally edit the configuration files to change the parameters to access
the Virtual Image Library user interface from the SmartCloud Orchestrator user
interface with the single sign-on (SSO).
During the SmartCloud Orchestrator installation, the parameters to access the
Virtual Image Library user interface are configured automatically. If you change the
Virtual Image Library server URL, you must change the following configuration
files on the machine where the Workload Deployer component is installed:
v <install-path>/purescale.app/config/iwdvil.config
v /opt/ibm/ccs/scui/etc/config.json
To change the configuration files, perform the following steps:
1. Change the parameters in the iwdvil.config file as described in the following
example:
#example https://<hostname>:<port>/ImageLibrary/ImageLibrary
/config/vil/url = "https://tcloudvm01.rome.ibm.com:9443
/ImageLibrary/ImageLibrary"
#example https://<host_name>:<port>/ImageLibraryUI
/config/vil/ui_url = "https://tcloudvm01.rome.ibm.com:9443
/ImageLibraryUI"
/config/vil/keystorePassword = "<xor>KD4sPjsyNjE="
/config/vil/userName = "adminuser"
/config/vil/password = "passw0rd"
/config/vil/url
Defines the URL for the Virtual Image Library REST operations.
Chapter 4. Administering 143
/config/vil/ui_url
Defines the URL for the Virtual Image Library user interface.
/config/vil/keystorePassword
Defines the encoded password.
Note: If you want to create a new keystore you need to run the
command (in Virtual Image Library):
./createKeys.sh -password password -overwrite yes -was <WAS_INSTALL_DIR>
The script createKeys.sh creates a keystore file in the current directory
named iwdvil.p12, which contains the public and private key pair.
Copy the file to the following directories:
v Image Library server directory in WebSphere
v SmartCloud Orchestrator configuration directory
<install-path>/purescale.app/config
After you have created a new keystore, you must encrypt the password
using the sMash command line. To encrypt the password, go to
<install-path>/purescale.app directory and run the following
command:
./zero encode <password>
For example, if you run the following command:
./zero encode mypassw0rd
the following output is displayed:
CWPZC2029I: Input
mypassw0rd
CWPZC2030I: Result
<xor>MiYvPiwsKG8tOw==
Then you must update the /config/vil/keystorePassword parameter.
/config/vil/userName
/config/vil/password
Define the credentials of the Virtual Image Library administrator.
Note: When you change the password of the administrator user ID,
you must also update the /config/vil/password parameter. This
parameter can be encrypted. To encrypt the new password use the zero
encode command.
2. Change the vil statement in the config.json file as described in the following
example:
"vil":
{
"provider": "vil",
"service_url": ""https://tcloudvm01.rome.ibm.com:9443"
},
where service_url defines the URL for the Virtual Image Library server.
144 IBM SmartCloud Orchestrator 2.3: User's Guide
Configuring the scalable web infrastructure server
You can optionally change the parameters to communicate to the scalable web
infrastructure server in your SmartCloud Orchestrator environment.
During the SmartCloud Orchestrator installation, the parameters related to the
scalable web infrastructure server are configured automatically.
Communicating to the scalable web infrastructure server
To change the parameters to communicate to the scalable web infrastructure server,
modify the following values in the WD_inst_dir/config/zero.config file where
WD_inst_dir is the directory where the Workload Deployer component is installed:
/config/swi/protocol = server_protocol
/config/swi/hostname = server_hostname
/config/swi/port = server_port
where
server_protocol
is the protocol to communicate to the scalable web infrastructure server. By
default, it is https.
server_hostname
is the host name of the scalable web infrastructure server.
server_port
is the port used to communicate to the scalable web infrastructure server.
By default, it is 443.
Defining a Yum repository
If you want to install an RPM package on a deployed virtual machine the first time
that the virtual machine starts, you must define a Yum repository that is accessible
from the scalable web infrastructure server and from the deployed virtual machine.
To define the Yum repository, specify the following parameters in the
/opt/ibm/ccs/scpui/etc/config.json file on the scalable web infrastructure server:
"package_libraries" : [
{
"provider": "yum",
"http_service_url": "http_service_url"
}
]
where http_service_url is the HTTP URL of the directory configured as Yum
repository (that is the directory that contains the repodata directory). For example:
"http_service_url": "http://<ip_address>/rhel/6.3/x86_64"
Chapter 4. Administering 145
Configuring session timeout value
You can optionally increase the default timeout value for the SmartCloud
Orchestrator web interface session.
About this task
The default timeout value for a web interface session is 30 minutes.
To increase the session timeout value, change the following parameter in the
/opt/ibm/rainmaker/purescale.app/private/expanded/ibm/rainmaker.rest-
4.0.0.1/config/timeouts-default.config file on the machine where the Workload
Deployer component is installed:
/config/userZone/idleTimeout = new_idleTimeout_value_in_minutes
/config/security/token/simple += {
"tokenExpiration": new_tokenExpiration_value_in_minutes
}
where
new_idleTimeout_value_in_minutes
Is the session expiration timeout value that you want to change.
new_tokenExpiration_value_in_minutes
Is the token expiration timeout value that you want to change.
Configuring timeout value for Ajax calls
You might need to increase this timeout value to display in the expandable section
all the virtual machines that are available for a selected hypervisor or a virtual
system instance.
About this task
The timeout value for Ajax calls is set in the rainmaker.ui/config/zero.config file
through the parameter /config/rainmaker/ajax/timeout and the default value is
60 seconds.
To increase the timeout value, override the default value by adding the following
line in the purescale.app/config/overrides.config file on the machine where the
Workload Deployer component is installed:
/config/rainmaker/ajax/timeout = new_value_in_seconds
where new_value_in_seconds is the new timeout value.
Configuring OpenStack synchronization
You can optionally change the default synchronization interval with the OpenStack
environment.
About this task
In SmartCloud 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 SmartCloud Orchestrator
environment.
146 IBM SmartCloud Orchestrator 2.3: User's Guide
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. If this timeout is reached, you must check the hypervisor
status in the Hypervisor panel. The message should be meaningful and
after correcting the problem (like network issue), rerunning the Discovery
from the UI should help. Of course exceptions will be logged in traces for
Workload Deployer as well.
To change the server operation settings , 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 = {
.....
"openstack": { "server_operation_timeout_sec": 3600,
"server_operation_check_interval_sec": 60,
"image_service": "vil" }
....
}
where:
server_operation_timeout_sec
Specifies the timeout for each OpenStack operation (for example, the
deployment of a virtual machine). The default is 3600 seconds (1 hour).
server_operation_check_interval_sec
Specifies the interval for the OpenStack operation status check. The default
is 10 seconds.
image_service
Specifies the image service to be used, glance or VIL. Do not change this
parameter.
Chapter 4. Administering 147
Configuring OpenStack connection
You can optionally change the parameters to communicate to OpenStack in your
SmartCloud Orchestrator environment.
About this task
During the SmartCloud Orchestrator installation, the parameters related to the
OpenStack communication are configured automatically. If you need to change
these parameters for technical reasons related to your OpenStack environment,
change the following configuration files on the Central Server 3:
/opt/ibm/maestro/maestro/usr/servers/kernelservices/overrides.cfg
/opt/ibm/maestro/usr/servers/storehouse/overrides.cfg
Change the following parameters:
openstack.iaas.service_url=http://iaas_gateway_hostname:port
openstack.iaas.provider=iaas_gateway
openstack.iaas.admin_user=admin_user
openstack.iaas.admin_tenant=primary_admin_project
openstack.auth.simple_token_secret=simple_token_secret
/opt/ibm/rainmaker/purescale.app/private/expanded/ibm/scp.ui-1.0.0/config/
openstack.config
Change the parameters in the following statement:
/config/openstack = {
"iaas": {
"provider": "iaas_gateway",
"service_url": "http://iaas_gateway_hostname:port",
"admin_user": "admin_user",
"admin_tenant": "primary_admin_project",
"simple_token_secret": "simple_token_secret"
...
}
where
iaas_gateway_hostname:port
Specifies the host name (or the IP address) and the port number of the
machine where the IAAS gateway component is installed.
admin_user
Specifies a user with admin role in the OpenStack environment.
default_admin_project
Specifies the primary project of the user specified in admin_user.
simple_token_secret
Specifies the simple token to be used to communicate.
Note: Be sure that you use the same parameter values in all the configuration files.
148 IBM SmartCloud Orchestrator 2.3: User's Guide
Configuring OpenStack to support thin provisioning
This topic describes how you can configure OpenStack to support thin
provisioning.
About this task
For VMware regions, you can enable thin provisioning for a specific flavor using
this command:
nova flavor-key <flavor name> set ibm-smartcloud:VMWareUseLinkedClones=true
Configuring memory and CPU overcommitment
SmartCloud 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.
Managing users, projects, and domains
You can manage users and the level of access that each user has in the SmartCloud
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
Chapter 4. Administering 149
For more information about the OpenStack commands to be used to manage quota
values in the projects, see Modifying project quotas on page 86.
When you create users and projects in SmartCloud Orchestrator, they are actually
being created in the underlying OpenStack environment. The roles that are defined
in the OpenStack environment are used in SmartCloud Orchestrator as described
in User roles in SmartCloud Orchestrator on page 151.
In SmartCloud 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
SmartCloud 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: SmartCloud 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 SmartCloud 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
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 SmartCloud
Orchestrator. To login to Business Process Manager and Virtual Image Library, 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 and Virtual Image Library 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 and Virtual Image Library. 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 and Virtual Image Library with a '/' as
delimiter, the user name, project name, and domain name must not contain a '/'
character.
Note: In the current release of SmartCloud Orchestrator user, project and domain
names are case insensitive (in other words, if a user is created with the name
'George Windsor', then they would be able to login successfully as 'george
windsor'). However, this is likely to change in a future release, so this fact should
not be relied on.
150 IBM SmartCloud Orchestrator 2.3: User's Guide
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 77.
You can work with your users, projects (only to manage users), and domains with
the SmartCloud Orchestrator user interface.
Procedure
v To work with SmartCloud Orchestrator users, see Managing users on page
153.
v To work with SmartCloud Orchestrator projects, see Managing projects on
page 155.
v To work with SmartCloud Orchestrator domains, see Managing domains on
page 158.
Results
After you completed these steps, users, projects, and domains are defined to
customize the SmartCloud Orchestrator environment to your organization's
business needs.
User roles in SmartCloud Orchestrator
Protect your cloud environment by using roles to control how different users
interact with SmartCloud Orchestrator. When you assign roles to users, you
designate the types of objects (such as cloud groups) that they can access, and the
tasks that they can perform.
In SmartCloud 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 related to the project to which the user belongs. A user 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 152 for more information.
In SmartCloud Orchestrator, you can use the following roles:
admin Can run the following tasks in the SmartCloud Orchestrator environment:
v Assign other user roles, configure product settings, and modify resources
such as: images, patterns, shared services, environment profiles, other
catalog content, and deployed cloud content.
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 and change auditing settings that are editable
(such as the option to delete audit data from the SmartCloud
Orchestrator after download).
Note: The admin role grants a user to have full privileges to all cloud
resources, including all projects and all domains. It is recommended that
Chapter 4. Administering 151
you assign this role only to the cloud administrators and only to users
within the Default domain and admin project.
catalogeditor
Can run the following tasks in the SmartCloud Orchestrator environment:
v Can create both virtual system patterns and virtual application patterns.
These users can also edit or delete any patterns that they create, or to
which they have access.
v Can add objects to the SmartCloud Orchestrator catalog. They can also
modify or delete any catalog content that they create, or to which they
have access.
v Can import image files but cannot register images from a region. For
more information about importing and registering images, see
Importing a virtual image to the catalog on page 289 and Registering
a virtual image on page 290.
v Can create self-service offerings, self-service categories, and orchestration
actions. They can also modify or delete any self-service offerings,
self-service categories, and orchestration actions that they create, or to
which they have access.
Member
Can view and manage the virtual system instances, patterns, and catalog
content to which they are granted access. They can deploy virtual system
patterns and virtual application patterns, but cannot add, remove, or
modify any items.
Object-level access control
SmartCloud 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
v Virtual images
v Patterns
v Script packages
v Add-ons
v Virtual system instances
v Shared services instances
v Self-service offerings
v Orchestration actions
The following table depicts the object-level access definitions in SmartCloud
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.
152 IBM SmartCloud Orchestrator 2.3: User's Guide
Table 14. 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.
Managing users
You can manage the level of access for each individual user to SmartCloud
Orchestrator with the user interface.
Before you begin
You must be assigned the admin role to perform these steps.
About this task
In the SmartCloud Orchestrator environment, the users are defined in the related
OpenStack environment.
If you configure your OpenStack to use LDAP authentication, you can log in to
SmartCloud Orchestrator by using the LDAP users and perform the tasks that are
allowed to the role associated to the user in the related project. For more
information about configuring OpenStack to work with an LDAP server, see
Configuring LDAP authentication on page 77.
Note: If you want to define an account lockout policy, you must configure
OpenStack to work with an LDAP server and enable the policy on LDAP. You
cannot define an account lockout policy with the local Keystone authentication in
OpenStack.
You can manage OpenStack users from the SmartCloud Orchestrator user interface,
by performing the following procedure.
Note: The following procedure apply only to OpenStack users that are locally
defined, and do not apply to users eventually defined in an external LDAP server.
If you create an OpenStack user, be careful about creating a local user with the
same name as an LDAP user, because when you log in to SmartCloud
Orchestrator, the user is authenticated to the LDAP server before being
authenticated locally to OpenStack.
Chapter 4. Administering 153
Procedure
1. Open the User window by clicking Administration > Users in the menu bar.
The list of the existing users is displayed in the left pane.
2. You can perform the following tasks:
v Creating a user -
To create a user, perform the following steps:
a. Click the Add icon in the user list. The Create a new user window is
displayed.
b. Insert the credentials and a valid email address for the user.
Important: As the user and the project name are prefixed by their
domain name in Business Process Manager and Virtual Image Library
with a '/' as delimiter, the user name, project name, and domain name
must not contain a '/' character.
Important: SmartCloud Orchestrator does not support the definition of
same resource names in multiple domains at the same time. Be sure that
there are no duplicated user names.
c. In the Primary project list, select the primary project to which the user is
assigned. For more information about projects, see Managing users,
projects, and domains on page 149.
d. In the Role in primary project list, select the user role in the specified
project. For more information about roles, see User roles in SmartCloud
Orchestrator on page 151.
e. If you do not want to allow the user to log in or to perform any
operation in SmartCloud Orchestrator select Disabled in the State list.
f. Select a domain for the user. Make sure that you already enabled the
domain that you want to use.
Note: After you created the user, you cannot change the domain to which
the user belongs.
g. Click Create. The user is created in the OpenStack environment and it is
available in SmartCloud Orchestrator.
Note: To allow the new user to work with the Process Designer, you
must define the user in the Business Process Manager environment. To
define a user in Business Process Manager, open the Process Center user
interface by clicking Administration > Process Center and follow the
procedure described in Adding users and groups section in the IBM
Business Process Manager information center.
v Editing a user
To change the properties of a user, perform the following steps:
a. Select the user in the user list. The user details are displayed in the right
pane.
b. Click the Edit icon.
c. You can change the following properties:
Email address
Password
Primary project
State
154 IBM SmartCloud Orchestrator 2.3: User's Guide
Note: Only users with admin role can change the user password.
d. Click the Save icon to apply your changes.
v Enabling or disabling a user
To enable or disable a user, select the user in the list and click the Enable or
Disable icon.
v Deleting a user
To delete a user that you do not need anymore, perform the following steps:
a. Select the user in the user list. The user details are displayed in the right
pane.
b. Click the Delete icon. A confirmation window is displayed.
c. Click OK to delete the user. The user is deleted in the OpenStack
environment and it is not more available in SmartCloud Orchestrator.
Results
You managed the users in the SmartCloud Orchestrator environment.
Note: You can also manage users directly from the OpenStack interface. The
changes that you make from the OpenStack interface are automatically displayed
in the SmartCloud Orchestrator environment when you open the Users window. To
refresh the user list in the Users window, click the Refresh icon.
For more information about OpenStack, see Overview of OpenStack on page 8.
Managing projects
You can manage the level of access for each project to SmartCloud Orchestrator
with the user interface.
Before you begin
You must be assigned the admin role to perform these steps.
About this task
In the SmartCloud Orchestrator environment, the projects are defined in the related
OpenStack environment. For more information about projects, see Managing
users, projects, and domains on page 149.
A built-in project named Everyone is already defined in the SmartCloud
Orchestrator environment. This project contains all the existing users and it cannot
be deleted. You must not create a project named Everyone in your OpenStack
environment.
Note: The name of the built-in project depends on the server locale that was
defined when you installed SmartCloud Orchestrator.
To manage projects from the SmartCloud Orchestrator user interface, perform the
following steps:
Procedure
1. Open the Project window by clicking Administration > Projects in the menu
bar. The list of the existing projects is displayed in the left pane. To show the
details of a project in the right pane, select the project in the list.
Chapter 4. Administering 155
2. You can perform the following tasks:
v Creating a project -
To create a project, perform the following steps:
a. Click the Add icon in the project list. The Create a new project window is
displayed.
b. Insert a name for the project.
Important: SmartCloud Orchestrator does not support the definition of
same resource names in multiple domains at the same time. Be sure that
there are no duplicated project names.
Important: As the user and the project name are prefixed by their
domain name in Business Process Manager and Virtual Image Library
with a '/' as delimiter, the user name, project name, and domain name
must not contain a '/' character.
c. Optionally insert a description for the project.
d. If you do not want to allow the project members to perform any
operation in SmartCloud Orchestrator, select Disabled in the State list.
Note: If a project is disabled, the users that are assigned to the project as
their primary project cannot log in to the SmartCloud Orchestrator user
interface.
e. Select a domain for the project. Make sure that you already enabled the
domain that you want to use.
Note: After you created the project, you cannot change the domain to
which the project belongs.
f. Click Create. The project is created in the OpenStack environment and it
is available in SmartCloud Orchestrator.
After you created a new project, perform the following steps to work with
this project in your Virtual Image Library environment:
a. Click Images & Patterns > Virtual Image Library to open the Virtual
Image Library user interface.
b. Click Images in the toolbar.
c. In the Images tab, click Actions > Synchronize User and Group List.
Note: Before you perform this action, be sure that there are no pending
tasks because the Virtual Image Library component is restarted when you
synchronize the user and group list.
v Editing a project
To change the properties of a project, perform the following steps:
a. Select the project in the project list. The project details are displayed in
the right pane.
b. Click the Edit icon.
c. You can change the following properties:
Name
Description
State
Note: Even if you change the project name, the old project name is
displayed in the Access granted to list of the objects that are already
156 IBM SmartCloud Orchestrator 2.3: User's Guide
accessible by the project. Anyway, the access to these objects is still
granted to the users that belong to the project.
d. To add a user to the project, click the Members field and select a user in
the list. The user is added to the project with a default role. You can also
remove a user from the project by clicking remove on the right of the
related user entry.
Note: If you remove your user from a project and your user does not
belong to any other project, you cannot log in to the user interface any
more. Ask to a user with admin role to readd your user to a project. As
an alternative, ask to the OpenStack Keystone administrator to add your
user to a project by running the keystone user-role-add command.
e. To add a role to a user, click the field on the right of the user name and
select a role in the list. You can also remove a role of a user by clicking x
on the right of the role name. A user must have at least one role in the
project. For more information about roles, see User roles in SmartCloud
Orchestrator on page 151.
f. Click the Save icon to apply your changes.
v Enabling or disabling a project
To enable or disable a project, select the project in the list and click the
Enable or Disable icon.
Note: If you disable a project, the users that are assigned to the project as
their primary project cannot log in to the SmartCloud Orchestrator user
interface.
v Deleting a project
To delete a project that you do not need anymore, perform the following
steps:
a. Select the project in the project list. The project details are displayed in
the right pane.
b. Click the Delete icon. A confirmation window is displayed.
c. Click OK to delete the project. The project is deleted in the OpenStack
environment and it is not more available in SmartCloud Orchestrator.
Note: When you delete a project, the users that belong to the project are not
deleted.
Results
You managed the projects in the SmartCloud Orchestrator environment.
Note: You can also manage projects directly in OpenStack. The changes that you
make in the OpenStack environment are automatically displayed in the
SmartCloud Orchestrator environment when you open the Projects window. To
refresh the project list in the Projects window, click the Refresh icon.
To change quota values that are related to the projects, you must use the
OpenStack interface. For more information, see Modifying project quotas on
page 86.
Chapter 4. Administering 157
What to do next
You can grant the access to SmartCloud Orchestrator objects to the users that
belong to a project by adding the project in the Access granted to list in the related
view of the following objects:
v Environment profiles. For more information, see Environment Profiles window
fields on page 230.
v Virtual images. For more information, see Virtual image fields on the user
interface on page 292.
v Virtual system patterns. For more information, see Fields on the Virtual System
Patterns window on page 554.
v Script packages. For more information, see Adding a script package on page
243.
v Add-ons. For more information, see Fields on the Add-Ons user interface on
page 265.
v Orchestration actions. For more information, see Making a process available as
an orchestration action on page 772.
v Self-service offerings. For more information, see Modifying self-service
offerings on page 780.
For more information about user and project permissions, see Object-level access
control on page 152.
Managing domains
You can manage domains in SmartCloud Orchestrator with the user interface.
Before you begin
You must be assigned the admin role to perform these steps.
About this task
A built-in domain named Default is already defined in the SmartCloud
Orchestrator environment. For information about domains, see Managing users,
projects, and domains on page 149.
To manage domains from the SmartCloud Orchestrator user interface, perform the
following steps:
Procedure
1. Open the Domain window by clicking Administration > Domains in the menu
bar. The list of the existing domains displayed in the left pane. To show the
details of a domain in the right pane, select the domain in the list.
2. You can perform the following tasks:
v Creating a domain
To create a domain, perform the following steps:
a. Click the Add icon in the domain list. The Create a new domain window
is displayed.
b. Insert a name for the domain.
158 IBM SmartCloud Orchestrator 2.3: User's Guide
Important: As the user and the project name are prefixed by their
domain name in Business Process Manager and Virtual Image Library
with a '/' as delimiter, the user name, project name, and domain name
must not contain a '/' character.
c. Optionally insert a description for the domain.
d. If you do not want to allow users to log in to the domain select Disabled
in the State list.
e. Click Create. The domain is created in SmartCloud Orchestrator.
v Editing a domain
To change the properties of a domain, perform the following steps:
a. Select the domain in the domain list. The domain details are displayed in
the right pane.
b. Click the Edit icon.
c. You can change the following properties:
Name
Description
State
d. Click the Save icon to apply your changes.
v Enabling or disabling a domain
To enable or disable a domain, select the domain in the list and click the
Enable or Disable icon.
v Deleting a domain
To delete a domain that you do not need anymore, perform the following
steps.
Note: When you delete a domain, all the users and projects belonging to the
domain are also deleted.
a. Select the domain in the domain list. The domain details are displayed in
the right pane.
b. Click the Delete icon. A confirmation window is displayed.
c. Click OK to delete the domain. The domain and all the users and projects
belonging to the domain are deleted.
Results
You managed the domains in the SmartCloud Orchestrator environment.
Using the Public Cloud Gateway
The Public Cloud Gateway is installed on the Central Server 2 machine during the
installation of SmartCloud Orchestrator. Use the topics in this section to learn more
about the Public Cloud Gateway and its use within SmartCloud Orchestrator.
Chapter 4. Administering 159
Public Cloud Gateway overview
The Public Cloud Gateway is a web application that provides an OpenStack API
compatibility layer, so the Amazon Elastic Compute Cloud (Amazon EC2) works
like the standard OpenStack Nova and Glance instances.
The Public Cloud Gateway is automatically installed on the Central Server 2
machine as part of the SmartCloud Orchestrator installation process. For more
information about installing SmartCloud Orchestrator, see the related installation
guide. You can deploy and manage virtual machines and storage across both
private and public clouds, for example, Amazon EC2.
Note: With the Public Cloud Gateway, higher level components such as Workload
Deployer and the SmartCloud Orchestrator User Interface operate normally with
the public clouds with no changes required to support them.
Note: The Public Cloud Gateway can also be used to manage non-IBM supplied
OpenStack from SmartCloud Orchestrator. See the related section for more
information.
See the related topic for more information about how the Public Cloud Gateway
fits into the SmartCloud Orchestrator product architecture.
Related tasks:
Installing
Follow this procedure to install SmartCloud Orchestrator.
Capabilities and limitations
Review the following list of capabilities and limitations available with the Public
Cloud Gateway.
Public Cloud Gateway capabilities within SmartCloud Orchestrator
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 Keypair administration is available.
v Configure the root Keypair on a virtual machine.
v Configure administrator password on a virtual machine with images
containing the Activation Engine.
v Dynamic Host Configuration Protocol (DHCP) networking is available.
v User add-on support is available.
v User data support is available.
Public Cloud Gateway limitations within SmartCloud Orchestrator
v Unable to manage existing instances.
v Unable to leverage the Image Construction and Composition Tool
capabilities using the Public Cloud Gateway. This limitation occurs
because the image must be manually prepared or prepared using the
Image Construction and Composition Tool on a local provider and then
imported into the non-IBM supplied OpenStack.
v Unable to manage virtual application patterns.
v Unable to clone a virtual machine instance.
v Unable to add parts to a virtual system:
160 IBM SmartCloud Orchestrator 2.3: User's Guide
Disk add-on
Network Interface Controller (NIC) add-on
v Unable to retrieve hypervisor resource information when used in a
non-IBM supplied OpenStack configuration.
v Supporting only Dynamic Host Configuration Protocol (DHCP)
networking.
v Unable to manage imported Open Virtualization Appliance (OVA)
images.
v Windows images on Amazon EC2 are not supported.
Related tasks:
Create a supported image
Create a supported image for use with SmartCloud Orchestrator.
Related reference:
Create a supported image
Create a supported image for use with SmartCloud Orchestrator.
Managing Amazon EC2 using the Public Cloud Gateway
The Public Cloud Gateway is not pre-configured for use with Amazon Elastic
Compute Cloud (Amazon EC2) as part of the SmartCloud Orchestrator. Certain
configuration tasks must be completed before using the Public Cloud Gateway
functionality.
Prerequisites
Before configuring the Public Cloud Gateway you must ensure that the
requirements mentioned in this topic are satisfied.
General requirements
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
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 15. Ports used by Public Cloud Gateway
Port TCP or UDP Direction Description
22 TCP Outbound SSH communication
with:
v Virtual Machine
instances created
on the Amazon
EC2 network. This
must be allowed in
the default
Amazon EC2
security group *.
Chapter 4. Administering 161
Table 15. Ports used by Public Cloud Gateway (continued)
Port TCP or UDP Direction Description
ICMP ICMP communication
with:
v Virtual Machine
instances created
on the Amazon
EC2 network. This
must be allowed in
the default
Amazon EC2
security group *.
443 TCP Outbound HTTPS
communication with:
v Amazon EC2
management
endpoints.
Note: * For more information about Amazon EC2 security groups, see
http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-
network-security.html
v Nameserver (DNS) requirements Ensure that the Nameserver 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
/opt/ibm/pcg/etc/config.json. If the Nameserver is not configured
correctly, Public Cloud Gateway functions will not work.
Configuring the Public Cloud Gateway
The Public Cloud Gateway is deployed as part of the SmartCloud 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 using the Public Cloud Gateway functionality.
Before you begin
You must ensure that the prerequisites are satisfied.
About this task
At a minimum, you must complete the following steps to configure the Public
Cloud Gateway for use with Amazon EC2.
Procedure
1. Ensure that the admin.json file is configured with the correct Keystone
credentials.
Note: The values in the admin.json file are populated by default during the
installation of SmartCloud Orchestrator.
admin.json
This file is used to store Keystone credentials that are used to create
Amazon EC2 region endpoints in Keystone. These endpoints are
created when the Public Cloud Gateway is started. For more
information about starting the Public Cloud Gateway, see
162 IBM SmartCloud Orchestrator 2.3: User's Guide
Command-line interface scripts on page 181. These values are
populated by default during the installation of SmartCloud
Orchestrator.
Go to the /opt/ibm/pcg/etc directory and open the admin.json file:
{
"auth":{
"passwordCredentials":{
"username":"xxx",
"password":"xxx"
},
"tenantName":"admin"
}
}
The parameters in the admin.json are explained in the following table.
These parameters are required to create Keystone endpoints that
correspond to the Amazon EC2 regions.
Table 16. Parameters that are used in the admin.json file
Parameter Description
username Keystone administrator user name.
password Keystone administrator password. This
value must be encoded by using the
encryptpassword.sh script that is available
in the /opt/ibm/pcg directory. For more
information about the encryptPassword.sh
script, see Command-line interface scripts
on page 181.
tenantName The project name that is associated with the
administrator user.
2. Edit the config.json file to enable the appropriate Amazon EC2 regions and
configure the Keystone endpoints:
config.json
This file is used to specify the Keystone admin, service endpoints,
Amazon EC2 endpoints, and the regions that must be created in
Keystone, thus allowing access to the different Amazon EC2 vCenters
using the Public Cloud Gateway.
Note: The Keystone admin and service endpoints are populated by
default during the installation of SmartCloud Orchestrator.
Go to the /opt/ibm/pcg/etc directory and open the config.json
property file:
{
"auth":{
"provider":"keystone",
"service_url":"http://sco-pcg.xxx:5000",
"admin_url":"http://sco-pcg.xxx:35357"
},
"vcenters":{
"ec2":[
{
"name":"EC2-US-EAST_NORTHERN-VIRGINIA",
"url":"https://ec2.us-east-1.amazonaws.com",
"enabled":true
},
{
Chapter 4. Administering 163
"name":"EC2-US-WEST_OREGON",
"url":"https://ec2.us-west-2.amazonaws.com",
"enabled":true
},
{
"name":"EC2-US-WEST_NORTHERN-CA",
"url":"https://ec2.us-west-1.amazonaws.com",
"enabled":false
}
]
}
}
The parameters in the config.json 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 17. Parameters used in the config.json file
Parameter Description
provider The security provider, only Keystone is
supported in the Public Cloud Gateway.
This is populated during the installation of
SmartCloud Orchestrator.
service_url Public access URL for Keystone. The default
port number is 5000. This is populated
during the installation of SmartCloud
Orchestrator.
admin_url Private access url for Keystone. The default
port number is 35357. This is populated
during the installation of SmartCloud
Orchestrator.
name Name of the region that must be created.
Default Amazon EC2 endpoints are defined.
url The URL of the Amazon EC2 vCenter that
must be associated with the region. Default
Amazon EC2 endpoints are defined.
enabled If set to true this region and all required
Nova, Glance and Keystone endpoints are
created. All Amazon EC2 endpoints are set
to false by default.
3. Obtain the Amazon EC2 credentials (Access key ID and Secret access key) and
use the encryptPassword.sh script to encode the Secret access key. For more
information about the encryptPassword.sh script, see Command-line interface
scripts on page 181.
4. Obtain the project names that will use the public cloud functionality. For more
information about managing projects, see Managing projects on page 155.
5. Edit the credentials.json file to add the appropriate Access key ID and the
encoded Secret access key for each project:
credentials.json
This file is used to specify Amazon EC2 credentials for each project. For
more information about defining projects, see Managing projects on
page 155. The Amazon EC2 credentials are mapped to specific projects
in SmartCloud Orchestrator. These mappings are specified in the
credentials.json configuration file:
164 IBM SmartCloud Orchestrator 2.3: User's Guide
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=="
},
{
"tenantName":"*",
"access_key_ID":"xxx",
"secret_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 18. Parameters that are used in the credentials.json file
Parameter Description
tenantName The project name that is associated with the
Amazon EC2 credentials. A default set of
credentials that can be used for projects can
also be specified by using the wildcard
configuration, for example,
"tenantName":"*".
access_key_ID This is the Amazon EC2 credentials user
name.
secret_access_key This is the Amazon EC2 credentials
password. This value must be encoded using
the encryptpassword.sh script that is
available in the ../opt/ibm/pcg directory.
6. 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 181.
7. Restart the IaaS Gateway by using the service openstack-iaasgateway restart
command.
8. Log in to the SmartCloud Orchestrator UI and go to the Cloud Groups page to
verify that the cloud groups for the availability zones in the new region are
listed.
Note: It may take a few minutes to verify that the region is now enabled.
What to do next
Enable root login to Amazon EC2 images
By default, some Amazon EC2 images do not allow you to log in as the
Chapter 4. Administering 165
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:
v 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
Create a supported image on Amazon EC2 for use with SmartCloud
Orchestrator
Note: The following instructions are applicable for Linux images only.
Windows images are not supported.
1. Download the following file to the Linux image: http://
<Workload_Deployer_machine>/downloads/cloud-init/scp-cloud-init
2. Run the following commands as the root user:
chmod 755 scp-cloud-init
and
./scp-cloud-init install
3. 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
4. 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.
5. 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.
Change an Amazon EC2 region name
1. Go to the /opt/ibm/pcg/etc directory and open the config.json
property file, replace the old name with new one.
For example, change the region name from EC2-001 to EC2region. The
original EC2 region is :
"ec2":[
{
"name":"EC2-001",
"url":"https://ec2.us-east-1.amazonaws.com/",
"enabled":true
}
change the region's name:
"ec2":[
{
"name":"EC2region",
"url":"https://ec2.us-east-1.amazonaws.com/",
"enabled":true
}
166 IBM SmartCloud Orchestrator 2.3: User's Guide
2. Configure SmartCloud Orchestrator for the new region and remove the
entry for the old region. For more information about configuring a
multiple region environment, see the Installing a multiple-region
environment on page 47.
3. Restart the Public Cloud Gateway by using the service pcg restart
command. For more information about starting the Public Cloud
Gateway, see the related CLI topic.
4. Restart the IaaS Gateway by using the service openstack-iaasgateway
restart command.
5. Delete the services of the old region from keystone:
[root@central-server-2 ~]# source ~/keystonerc
[root@central-server-2 ~]# keystone endpoint-list
WARNING: Bypassing authentication using a token and endpoint (authentication credentials are being ignored).
+----------------------------------+-----------+---------------------------------------------------------+
| id | region | publicurl |
+----------------------------------+-----------+---------------------------------------------------------+
| 0ff9e584b3d04c56af32e7b43ad5324d | EC2-001 | http://central-server-2:5000/v3 |
| 11924c78eca949ae939f2309a4e21bf9 | EC2-001 | http://central-server-2:9797/EC2-001/v1/%(tenant_id)s |
| 187dbc8c68b74d5f8e098d4c61544d0b | RegionOne | http://central-server-2:8776/v1/%(tenant_id)s |
| 19ded8422da445a7b6ceb0ce6d3c5f5e | RegionOne | http://central-server-2:8774/v2/%(tenant_id)s |
| 311e7c36c6b84ee3a5e2f39a04001481 | RegionOne | https://172.17.41.129:9443/ImageLibrary/ImageService/v1 |
| 3d8ff61f86f64838be5000b7efd60b89 | RegionOne | http://central-server-2:9292/ |
| 7f5a578d80684fcaaa473c9012ba7f46 | EC2-001 | http://central-server-2:9797/EC2-001/v2.0/%(tenant_id)s |
| bf8de63072ae453fb5ddf8b3027945cf | RegionOne | http://central-server-2:5000/v3 |
| e0a8c3d7c821424e94a0ef17c8c1a383 | EC2-001 | 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://172.17.41.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 |
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://172.17.41.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 command, for example:
[root@central-server-2 ~]# keystone endpoint-delete 0ff9e584b3d04c56af32e7b43ad5324d
Related reference:
Command-line interface scripts
Command Line Interface (CLI) scripts are available in the /opt/ibm/pcg directory.
These scripts are used to perform manual tasks, for example, starting the Public
Cloud Gateway, encrypting a password, changing port numbers and so on.
Password authentication on Amazon EC2 images on page 181
Use this topic if you want to allow password authentication and root login by
using password authentication on Amazon EC2 images.
Region names displayed incorrectly in the Virtual Image page on page 178
A known issue exists where SmartCloud Orchestrator removes the name after an
_ in the region name when registering images.
Chapter 4. Administering 167
Unable to connect to a public cloud due to missing credentials on page 179
Exceptions may occur in the Public Cloud Gateway stating that it is Unable to
connect to public cloud due to missing credentials. This is due to
tenants/projects being present on SmartCloud Orchestrator that are not accounted
for in the credentials.json file.
Loss of functionality in Public Cloud Gateway cloud groups on page 177
Loss of functionality may occur in Public Cloud Gateway cloud groups in
SmartCloud Orchestrator, where there has been heavy load on the Public Cloud
Gateway cloud groups.
Managing non-IBM supplied OpenStack using the Public
Cloud Gateway
SmartCloud 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 SmartCloud Orchestrator and non-IBM supplied OpenStack.
The Public Cloud Gateway provides a compatibility layer that enables SmartCloud
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 SmartCloud Orchestrator to manage non-IBM supplied OpenStack services
by accessing them through their Amazon EC2 API.
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.
Prerequisites
Before configuring the Public Cloud Gateway to manage non-IBM supplied
OpenStack, you must ensure that the requirements mentioned in this topic are
satisfied.
General requirements
v A configured and working non-IBM supplied OpenStack must be
available.
v The non-IBM supplied OpenStack must be the Folsom release or higher.
v Compute nodes must be configured to any OpenStack-supported
hypervisor type.
Network requirements
v Port requirements The Public Cloud Gateway requires access to a
number of ports in the installation environment and in the default
non-IBM supplied OpenStack security group. If these ports are blocked
by a firewall or used by another process, some Public Cloud Gateway
functions will not work.
168 IBM SmartCloud Orchestrator 2.3: User's Guide
Table 19. Ports used by Public Cloud Gateway
Port TCP or UDP Direction Description
22 TCP Outbound SSH communication
with:
v Virtual Machine
instances created
on the non-IBM
supplied
OpenStack a
network. This must
be allowed in the
default non-IBM
supplied
OpenStack security
group *.
ICMP ICMP communication
with:
v Virtual Machine
instances created
on the non-IBM
supplied
OpenStack
network. This must
be allowed in the
default non-IBM
supplied
OpenStack security
group *.
443 TCP Outbound HTTPS
communication with:
v non-IBM supplied
OpenStack
Amazon EC2
management
endpoints.
v Nameserver (DNS) requirements Ensure that the Nameserver is
configured correctly in both Central Server 1 and Central Server 2.
Both Central Server 1 and Central Server 2 instances must be able to
resolve the non-IBM supplied OpenStack management endpoints as
defined in /opt/ibm/pcg/etc/config.json. If the Nameserver is not
configured correctly, Public Cloud Gateway functions will not work.
Configure the Public Cloud Gateway to manage non-IBM
supplied OpenStack
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.
Chapter 4. Administering 169
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.
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
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":{
"ec2":[
{
"name":"EC2-US-EAST_NORTHERN-VIRGINIA",
"url":"https://ec2.us-east-1.amazonaws.com",
"enabled":false
},
{
"name":"EC2-US-WEST_OREGON",
"url":"https://ec2.us-west-2.amazonaws.com",
"enabled":false
},
],
"nios":[
{
"name":"nioRegion1",
"url":"http://172.16.108.12:8773/services/Cloud/",
"enabled":true
},
{
"name":"nioRegion2",
"url":"http://172.16.108.13:8773/services/Cloud/",
"enabled":true
}
]
},
170 IBM SmartCloud Orchestrator 2.3: User's Guide
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.
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.
Configure non-IBM supplied OpenStack flavors:
As stated in the related introduction topic, there are limitations to the functionality
provided by the Amazon EC2 API. One of the limitations is that there is no
support for managing the flavors of the compute instances.
Since the OpenStack API does support flavors, and SmartCloud Orchestrator must
query each region to collect a list of the available flavors, the Public Cloud
Gateway requires an alternative source for this information. This is required so that
it can answer the requests that it receives from SmartCloud Orchestrator.
The flavors are defined in a file on the Central Server 2 machine, which must be
manually updated to match the flavors available in each non-IBM supplied
OpenStack region. If the detail of the flavors is later changed, the file must be
updated again and the Public Cloud Gateway must be restarted.
1. To obtain the list of flavors that are supported on a particular non-IBM
supplied OpenStack region, logon 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 region and the default region can be
used for any non-IBM supplied OpenStack region not explicitly mentioned. The
region names must exactly match those defined in the config.json file.
3. 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:
{
"default": {
"m1.small": {"name":"Small", "cpu":1, "ram":1700, "disk":150},
"m1.medium": {"name":"Medium", "cpu":2, "ram":3750, "disk":400},
"m1.large": {"name":"Large", "cpu":4, "ram":7500, "disk":840},
"m1.xlarge": {"name":"Extra Large", "cpu":8, "ram":15000, "disk":1680},
"c1.xlarge": {"name":"High-CPU Extra Large", "cpu":20, "ram":7000, "disk":1680},
"m2.xlarge": {"name":"High-Memory Extra Large", "cpu":6, "ram":17100, "disk":410}
Chapter 4. Administering 171
},
"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, SmartCloud 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 flavors.json file does not alter the flavors for Amazon EC2 regions, even if
the Amazon EC2 region names are listed in the file.
v The id in the flavors.json file (m1.small in the above output) must match the
flavor name on non-IBM supplied OpenStack and not the flavor ID.
v SmartCloud Orchestrator requires at least 512 MB of memory to be defined in
flavors.
Related tasks:
Configuring the Public Cloud Gateway
The Public Cloud Gateway is deployed as part of the SmartCloud 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 using the Public Cloud Gateway functionality.
Related reference:
Configure IaaS Gateway and restart the Public Cloud Gateway on page 174
Configure SmartCloud Orchestrator for the new region. For more information
about configuring a multiple region environment, see the related configuring topic.
When all the configuration tasks are complete, the Public Cloud Gateway and the
IaaS gateway must be restarted.
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, it is necessary to
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 will be 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
172 IBM SmartCloud Orchestrator 2.3: User's Guide
Note: The user and tenant that is chosen must have sufficient access to do 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 2 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
+-----------+----------------------------------+
| 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 will be entirely
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.
Chapter 4. Administering 173
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 should be defined for all SmartCloud Orchestrator tenants.
v Save the file.
The following example of credentials.json shows the formatting:
{
"cred":{
"ec2":[
{
"tenantName":"admin",
"access_key_ID":"XXXXXXXXXXXXXXXXXXXX",
"secret_access_key":"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX=="
}
],
"nios":[
{
"tenantName":"admin",
"access_key_ID":"7e3d858e92324564a31e5d9b50fa62f0",
"secret_access_key":"OGQ3ZTE1YzBhZTY0OWI2YTkwYmNiZDhmOWRiYjcyNQ==",
"region":"nioRegion1"
}
]
}
}
The tenantName supplied as part of the credentials.json refers to SmartCloud
Orchestrator tenant. This tenantName signifies which tenant has access to non-IBM
supplied OpenStack. The tenant that is used by the non-IBM supplied OpenStack
is determined by the access (access_key_ID) and secret access keys
(secret_access_key).
Configure IaaS Gateway and restart the Public Cloud Gateway:
Configure SmartCloud Orchestrator for the new region. For more information
about configuring a multiple region environment, see the related configuring topic.
When all the configuration tasks are complete, the Public Cloud Gateway and the
IaaS gateway must be restarted.
Restart the Public Cloud Gateway service by logging on to Central Server 2 as root
and running the following command:
service pcg restart
Restart the IaaS Gateway by logging on to Central Server 2 as root and running the
following command:
service openstack-iaasgateway restart
For more information about managing the IaaS Gateway service, see the related
topic.
174 IBM SmartCloud Orchestrator 2.3: User's Guide
If the Public Cloud Gateway is properly configured, it starts to add the new
endpoints to the service catalog of the main SmartCloud Orchestrator Keystone
instance. You can check this by logging on Central Server 2 and running the
following command:
keystone endpoint-list
Review the region column for entries that match the names that are given to the
non-IBM supplied OpenStack regions. Log on to the SmartCloud Orchestrator
application and go to the Cloud Groups page to verify that the cloud groups for
the availability zones in the new region are listed.
Note: It may take a few minutes to verify that the region is now enabled.
Related reference:
Configure non-IBM supplied OpenStack flavors on page 171
As stated in the related introduction topic, there are limitations to the functionality
provided by the Amazon EC2 API. One of the limitations is that there is no
support for managing the flavors of the compute instances.
Post configuration tasks
After successful configuration of the Public Cloud Gateway to manage non-IBM
supplied OpenStack, the following tasks can be completed.
Create a supported image:
Create a supported image for use with SmartCloud Orchestrator.
Note: Windows images are not supported.
Check the prerequisites for a KVM or VMware image at Prerequisites for KVM or
VMware images on page 488.
Images activated by scp-cloud-init:
Manually creating images activated by cloud-init:
v Detailed information about creating images compatible with OpenStack
and activated by cloud-init can be found in OpenStack documentation:
http://docs.openstack.org/image-guide/content/
ch_creating_images_manually.html
v Additional information and documentation about cloud-init can be
found on the projects web site: https://launchpad.net/cloud-init, or in
it's latest documentation: http://cloudinit.readthedocs.org/en/latest/.
Images activated by cloud-init:
Example images activated by cloud-init:
v There are many ready to use GNU/Linux images available on the
internet. The OpenStack community has gathered some links for the
most popular Operating Systems: http://docs.openstack.org/image-
guide/content/ch_obtaining_images.html
Manually creating Linux images only:
1. Download the following file to the Linux instance:
http://<Workload_Deployer_machine>/downloads/cloud-init/scp-
cloud-init.
2. Run the following commands as the root user:
chmod 755 scp-cloud-init
and
Chapter 4. Administering 175
./scp-cloud-init install
Note: To run the scp-cloud-init script, you must have the following
commands installed on the system. Most of these commands are
already included in the default Linux installation: scp, awk, chmod, cat,
curl, find, grep, mkfs, parted, sed, od, unzip.
3. Create the ovf-env.done file on the file system by using the following
commands:
mkdir -p /opt/IBM/AE/AR/
and
touch /opt/IBM/AE/AR/ovf-env.done
4. At this point, you can create an image from the instance using the
Nova image-create command for use with SmartCloud Orchestrator.
For information about managing virtual images, see Chapter 5,
Managing virtual images, on page 287.
Create image using the Image Construction and Composition Tool
While there is no support available in the Public Cloud Gateway for the
Image Construction and Composition Tool, images created or extended
using this tool can be exported from the image repository configured in the
Image Construction and Composition Tool. These images are then
imported directly into the non-IBM supplied OpenStack:
1. Use the Image Construction and Composition Tool instructions for
creating a supported image using a different cloud provider, for
example, OpenStack cloud provider.
2. Export the image from the OpenStack environment using the
OpenStack glance command.
3. Import the image directly on to the non-IBM supplied OpenStack
environment using the glance command.
For more information about the glance command, see
http://docs.openstack.org/user-guide/content/glance_commands.html.
Related concepts:
Working with virtual images
You can build virtual images.
Related information:
Managing virtual images
Virtual images provide the operating system and product binary files that are
required to create a virtual system instance.
Troubleshooting
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
176 IBM SmartCloud Orchestrator 2.3: User's Guide
Loss of functionality in Public Cloud Gateway cloud groups
Loss of functionality may occur in Public Cloud Gateway cloud groups in
SmartCloud Orchestrator, where there has been heavy load on the Public Cloud
Gateway cloud groups.
Symptom
As stated in description.
Solution
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. This functionality provides for caching of servers,
availability zones, and image details internally when they are returned
from Amazon EC2. The Public Cloud Gateway queries Amazon EC2 every
"N" number of times that it is called, where "N" is the value that is defined
in the cacheCounter tag section of the config.json file. Use the following
steps if you want to update the default values in the cacheCounter tag
section:
1. Update the config.json file and add the cacheCounter tag section to
overwrite the default cache counter settings. The cacheCounter tag
section can be added as follows:
{
"auth":{
"provider":"keystone",
"service_url":"http://sco-pcg.xxx:5000",
"admin_url":"http://sco-pcg.xxx:35357"
},
"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":true
},
{
"name":"EC2-US-WEST_NORTHERN-CA",
"url":"https://ec2.us-west-1.amazonaws.com",
"enabled":false
}
]
},
"cacheCounter":{
"serversCounter":"N",
"glanceImagesCounter":"N",
"availabilityZoneCounter":N
}}
Note: If you do not specify the above values in the cacheCounter tag
section or it is not added to the config.json, then the values 5, 10, and
20 are used by default. For example:
"cacheCounter":{
"serversCounter":"5",
"glanceImagesCounter":"10",
"availabilityZoneCounter":20
}
The following table explains these parameters in more detail.
Chapter 4. Administering 177
Table 20. Parameters used in the cacheCounter tag section of the config.json file
Parameter Description
serversCounter Every time, for example 5 times,
SmartCloud Orchestrator attempts to get a
list of servers or a single server, it queries
Amazon EC2 once for a new list servers.
glanceImagesCounter Every time, for example 10 times,
SmartCloud Orchestrator requests a list of
images, the Public Cloud Gateway queries
Amazon EC2 once for a new list images.
availabilityZoneCounter Every time, for example 20 times,
SmartCloud Orchestrator requests a list of
availability zones, the Public Cloud Gateway
queries Amazon EC2 once for a new list of
availability zones.
2. Restart the Public Cloud Gateway.
Related tasks:
Configuring the Public Cloud Gateway on page 162
The Public Cloud Gateway is deployed as part of the SmartCloud 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 using the Public Cloud Gateway functionality.
Loss of functionality in Public Cloud Gateway cloud groups (2)
Loss of functionality might occur in Public Cloud Gateway cloud groups in
SmartCloud Orchestrator, where there has been outage in the endpoint being
managed by the Public Cloud Gateway.
Symptom
As stated in description.
Solution
Perform the following steps:
1. Restart the Public Cloud Gateway.
2. Manually start the hypervisors for the affected cloud groups in this
situation if there are no instances associated with this cloud group.
SmartCloud Orchestrator will rediscover the cloud groups after the
Public Cloud Gateway is restarted.
Region names displayed incorrectly in the Virtual Image page
A known issue exists where SmartCloud 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
178 IBM SmartCloud Orchestrator 2.3: User's Guide
3. Log in to SmartCloud 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 162
The Public Cloud Gateway is deployed as part of the SmartCloud 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 using the Public Cloud Gateway functionality.
Unable to connect to a public cloud due to missing credentials
Exceptions may occur in the Public Cloud Gateway stating that it is Unable to
connect to public cloud due to missing credentials. This is due to
tenants/projects being present on SmartCloud Orchestrator that are not accounted
for in the credentials.json file.
Symptom
As stated in description.
Solution
There are two methods that can be used to resolve this issue:
1. Add Amazon EC2 credentials for each tenant inSmartCloud
Orchestrator to the credentials.json file.
2. Add Amazon EC2 credentials, where the tenantName is * as stated in
step 5 in the related configuring topic. This ensures that these Amazon
EC2 credentials are applied to each tenant that is not explicitly stated in
credentials.json file.
Related tasks:
Configuring the Public Cloud Gateway on page 162
The Public Cloud Gateway is deployed as part of the SmartCloud 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 using the Public Cloud Gateway functionality.
Chapter 4. Administering 179
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, there 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 SmartCloud 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
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
Instances > Virtual Systems. You will notice that no information is
displayed for the MAC address field.
Solution
This information is not available when using the Public Cloud Gateway.
180 IBM SmartCloud Orchestrator 2.3: 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 deploy in a pattern.
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 SmartCloud Orchestrator UI 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 SmartCloud Orchestrator
UI is admin, the name of the key pair that is created in Amazon EC2 will be
deafult_admin. For information about managing key pairs, see the related topic.
Related tasks:
Managing key pairs
Manage pairs of SSH private and public keys in your environment to access
deployed virtual machines.
Command-line interface scripts
Command Line Interface (CLI) scripts are available in the /opt/ibm/pcg directory.
These scripts are used to perform manual tasks, for example, starting the Public
Cloud Gateway, encrypting a password, changing port numbers and so on.
Note: The default port number is 9797. To change this, you must edit the
startServer.sh script and change the value of -DHybrid.Port to the new port
number.
v encryptPassword.sh <secret_Access_key> used to encrypt the Amazon EC2
Secret_access_key to a form that can be used by the Public Cloud Gateway.
v service pcg start used to start the Public Cloud Gateway server with the
default settings.
v service pcg stop used to stop the Public Cloud Gateway server.
v service pcg restart used to restart the Public Cloud Gateway server.
Password authentication on Amazon EC2 images
Use this topic if you want to allow password authentication and root login by
using password authentication on Amazon EC2 images.
Log on to the Amazon EC2 image by using ssh and complete the following steps:
1. Edit the following file: /etc/ssh/sshd_config
2. Update the line that contains PasswordAuthentication as follows:
PasswordAuthentication yes
3. Update the line that contains PermitRootLogin as follows:
PermitRootLogin yes
4. Save the file.
5. Run the following command:
sudo service sshd restart
Related tasks:
Configuring the Public Cloud Gateway on page 162
The Public Cloud Gateway is deployed as part of the SmartCloud 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 using the Public Cloud Gateway functionality.
Chapter 4. Administering 181
Configuring the Public Cloud Gateway regions to use a proxy
server
You can configure the Public Cloud Gateway regions to use a proxy server.
About this task
You can specify proxy server details at region level or at vCenter level (ec2 or
nios). The proxy configuration that you specify at region level overrides the proxy
configuration specified at vCenter level.
The Public Cloud Gateway reads the proxy server details at startup from the
/opt/ibm/pcg/etc/config.json file on the Central Server 2.
In the following example, the proxy server configuration is defined at region level
for the EC2-EU-IRELAND region. Also a second proxy server configuration is
defined for the nios vCenter.
"vcenters":
{
"ec2":[
{
"name":"EC2-EU-IRELAND",
"url":"https://ec2.eu-west-1.amazonaws.com",
"enabled":true,
"proxy":{
"host":"proxy-server-host",
"username":"admin",
"password":"cGFzc3cwcmQ=",
"port": 3128
}
},
{
"name":"EC2-US-WEST_OREGON",
"url":"https://ec2.us-west-2.amazonaws.com",
"enabled":true
},
],
"nios":[
{
"name":"nioRegion1",
"url":"http://172.16.108.12:8773/services/Cloud/",
"enabled":true
}
]
},
"proxy":[
{
"vcenter":"nios",
"host":"172.17.41.129",
"username":"admin",
"password":"cGFzc3cwcmQ=",
"port": 3128
}
]
Note: The passwords specified in the proxy server configuration must be base-64
encoded by using the encryptpassword.sh script.
182 IBM SmartCloud Orchestrator 2.3: User's Guide
Building the cloud with topology resources
You can build clouds using your existing resources, for example hypervisors,
networks and storage, with SmartCloud Orchestrator. SmartCloud Orchestrator
manages these resources in the cloud.
About this task
You can work with resources to build your cloud. The following procedure
provides a layout of the information for each type of resource with links to the
specific section.
Procedure
1. Determine which interface you want to use.
v You can work with the user interface. Ensure that you have access to the
user interface.
v You can work with the command-line interface. Ensure that you have
downloaded and installed the command-line interface. For more information
about downloading and initializing the command-line interface, see
Downloading and configuring the command-line interface on page 909 and
Invoking the command-line interface on page 911.
2. You can work with the following resources to build your cloud:
Administering cloud groups on page 184
Cloud groups are collections of hypervisors.
Administering hypervisors on page 187
A platform virtualization software that allows multiple operating
systems to run on a host computer concurrently.
Administering virtual machines on page 194
The virtual machines running on a hypervisor.
Administering networks on page 203
A network object that is defined for a hypervisor.
Administering storage on page 206
The storage devices, and their configuration, that are linked to a
hypervisor.
Administering IP groups and IP addresses on page 208
Groups of IP addresses defined to enable granular assignment of IP
address ranges to hypervisors.
Managing cloud resources
Use the user interface or the command-line interface to manage the resources in
the cloud system.
Chapter 4. Administering 183
Administering cloud groups
In SmartCloud Orchestrator, a cloud group is identified by an availability zone in a
region of the related OpenStack environment.
Before you begin
Before starting to work with cloud groups in SmartCloud Orchestrator, define the
OpenStack availability zones as described in Managing availability zones in
OpenStack on page 185.
About this task
In the SmartCloud Orchestrator user interface, the availability zones already
defined in the regions of the related OpenStack environment are automatically
listed as cloud groups named region-name_availability-zone-name, where region-name
is the name of the region where the availability zone named availability-zone-name is
defined. A region is an OpenStack instance. For more information about creating
additional OpenStack regions in your environment, see Installing a
multiple-region environment on page 47.
For VMware regions, in SmartCloud Orchestrator a cloud group is listed for each
VMware cluster or resource pool that is defined in the vCenter. You can specify the
cluster or resource pool as a deployment target by specifying the related cloud
group in the environment profile.
Note: SmartCloud 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
SmartCloud Orchestrator to manage the resource limits.
To use the command-line interface, see the information provided in Cloud group
command-line interface reference on page 815.
Procedure
1. Access the Cloud Groups window by clicking Configuration > Cloud Groups
from the menu bar. The list of available cloud groups is listed in the left pane.
2. If you select a cloud group in the list, the cloud group details are displayed in
the right pane. See Fields on the Cloud Groups window on page 186 for
more information about the displayed details.
3. If you have administrative access to the cloud group, you can perform the
following tasks:
Editing the description
Click the description to edit it.
Changing the default base image
To change the default base image to be used when deploying virtual
application patterns, select a new image in the Default image field.
This value overrides the default base image that you specify in the
Settings for Default Deploy window. For more information about
deploying virtual application patterns, see Deploying virtual
application patterns on page 736.
Changing the URL
If the URL for the cloud changes, update it in the URL field.
184 IBM SmartCloud Orchestrator 2.3: User's Guide
Discovering the hypervisor and resetting the connections
To discover the hypervisor in the cloud group, click the Discover icon
at the top of the window. This task also resets the latest storage and
network connections in addition to discovering any new hypervisor.
Managing access
You can add or remove access for projects with the Access granted to:
field. You can also change the type of access provided. Valid types of
access are read, write and, all. Use the toggle link to change the type of
access.
Deleting the cloud group
Click the Delete icon at the top of the window.
Note: The cloud group is deleted in the SmartCloud Orchestrator
environment but the related availability zone is not deleted in the
OpenStack environment. If the availability zone still exists in your
OpenStack environment, the cloud group is listed again in the
SmartCloud Orchestrator user interface when the automatic
synchronization occurs. See Configuring OpenStack synchronization
on page 146, for more information about the OpenStack
synchronization. See Managing availability zones in OpenStack, for
more information about deleting availability zones in OpenStack.
Managing availability zones in OpenStack:
Create availability zones in your OpenStack environment to define the SmartCloud
Orchestrator cloud groups.
About this task
An OpenStack availability zone is a logical partition of hosts or volume services
within a single OpenStack deployment. Compute service availability zones are
defined at the host configuration level, providing a method to segment compute
nodes by arbitrary criteria, such as hardware characteristics, physical location, or
task designation.
To create an availability zone in OpenStack, run the following steps:
Procedure
1. On each Compute Node that you want include in the availability zone, add the
following statement in the /etc/nova/nova.conf:
node_availability_zone=availability_zone_name
2. Run the following commands:
service openstack-nova-metadata-api restart
service openstack-nova-compute restart
For more information about the OpenStack services, see the OpenStack
documentation.
Results
The availability zone is created in your OpenStack environment.
You can delete the availability zone by running the following steps on each
Compute Node that is included in the availability zone
1. Ensure there are not any virtual machines running on the Compute Node.
Chapter 4. Administering 185
2. Comment or delete the following statement in the /etc/nova/nova.conf file:
node_availability_zone=availability_zone_name
3. Run the following commands:
service openstack-nova-metadata-api restart
service openstack-nova-compute restart
For more information about the OpenStack services, see the OpenStack
documentation.
Fields on the Cloud Groups window:
You can administer your cloud groups by using the fields on the Cloud Groups
window of the SmartCloud Orchestrator user interface.
To work with a cloud group, first select it from the list in the left panel of the
Cloud Groups window. Selecting a cloud group shows the following fields:
Description
The description of the cloud group.
Created on
Provides the date when the cloud group was created.
Type Displays Managed by OpenStack.
Version
Shows the version of the cloud provider.
Current status
The status of the cloud group. One of the following states is shown:
Connected
The cloud group is connected to the hypervisor manager.
Unable to connect
The cloud group cannot connect to the hypervisor manager.
Discovering hypervisors, networks, and storage devices
The connections for hypervisors in this cloud group are being
reset.
Updated on
Shows the date and timestamp when the cloud group was updated.
Hypervisor type
Displays OpenStack .
Default image
Specifies the base image to be used when deploying virtual application
patterns in the cloud group. This value overrides the default base image
that you specify in the Settings for Default Deploy window. For more
information about deploying virtual application patterns, see Deploying
virtual application patterns on page 736.
URL Specifies the location of the hypervisor manager for the cloud group.
Cloud hardware
Shows the list of hypervisors with the following information:
Status Each hypervisor shows one of the following statuses:
v Started
v Maintenance mode
186 IBM SmartCloud Orchestrator 2.3: User's Guide
v Resetting
v System is powered off
Hypervisors
Provides a linked name of the hypervisor. Clicking the link opens
the Hypervisors window for that hypervisor.
Shared Network
Any shared networks configured for the hypervisor.
Access granted to:
You can add projects in the entry field to allow the users belonging to a
project to work with the cloud group. You can also click Everyone to add
all users. You can specify the access level of the projects and you can
remove any project to whom you previously granted access.
Related tasks:
Administering cloud groups on page 184
In SmartCloud Orchestrator, a cloud group is identified by an availability zone in a
region of the related OpenStack environment.
Related reference:
Cloud group command-line interface reference on page 815
You can work with cloud groups using the SmartCloud Orchestrator command-line
interface.
Administering hypervisors
You can use the SmartCloud Orchestrator user interface to work with the
hypervisors.
About this task
In the SmartCloud Orchestrator user interface, the hypervisors already defined in
the related OpenStack environment are automatically listed.
In your OpenStack environment, you can manage the following hypervisor types:
v KVM
v VMware ESX (through VMware vCenter)
v Power
For more information about defining hypervisors in an OpenStack environment,
see the OpenStack documentation. Detailed information about the hypervisor states
is available in Hypervisor states. To use the command-line interface, see the
information provided in Hypervisor command-line interface reference on page
830.
Procedure
1. Access the Hypervisors window by clicking Configuration > Hypervisors from
the menu bar. The list of available hypervisors is listed in the left pane.
2. If you select a hypervisor in the list, the hypervisor details are displayed in the
right pane. For more information about the displayed details, see Fields on the
Hypervisors window on page 191. You can access the hypervisor details also
clicking the hypervisor name in the Cloud hardware section of the related
cloud group in the Cloud Groups window.
3. If you have administrative access to the hypervisor, you can perform the
following tasks:
Chapter 4. Administering 187
Starting the hypervisor
Click the start icon in the upper right corner of the Hypervisors
window. If the start icon is unavailable, check the Current status field
for information about possible issues with your hypervisor
configuration.
Putting the hypervisor in maintenance mode
Take one of the following actions:
v If there are no started virtual machines that are managed by
SmartCloud Orchestrator, click the Maintenance icon on the upper
right of the window.
v If there are virtual machines that are started, perform the following
steps:
a. Click the Quiesce icon on the upper right of the window. In the
quiesce state, the hypervisor does not accept new deployment
tasks.
b. Click the Maintenance icon on the upper right of the window.
Administering virtual machines
For more information about this task, see Administering virtual
machines with the user interface on page 194.
Changing the network configuration
For more information about configuring the network, see
Administering networks with the user interface on page 204.
Managing the storage devices
For more information about managing the storage devices, see
Administering storage on page 206.
Deleting the hypervisor
Put the hypervisor in maintenance mode and click the Delete icon at
the top of the window.
Note: The hypervisor is deleted in the SmartCloud Orchestrator
environment but not in the OpenStack environment. The hypervisor is
listed again in the SmartCloud Orchestrator user interface when the
automatic synchronization occurs. For more information about the
OpenStack synchronization, see Configuring OpenStack
synchronization on page 146.
Related reference:
Hypervisors REST API on page 966
You can use the representational state transfer (REST) application programming
interface (API) to manage hypervisors.
vCenter management:
Refer to this topic for some basic information on how vCenter is managed in a
SmartCloud Orchestrator environment.
vCenter instances supported by one SmartCloud Orchestrator instance
As of version 2.3, a SmartCloud Orchestrator instance supports a single instance of
vCenter per OpenStack region.
188 IBM SmartCloud Orchestrator 2.3: User's Guide
Using distinct credentials to segment resources in vCenter
SmartCloud Orchestrator can access a given vCenter instance by only one set of
user credentials. See Restricting access to vCenter on page 190 for information on
how to restrict availability of VMware resources.
Modifying the configuration of clusters/servers/datastores assigned for
provisioning
You can control which managed resources are chosen for provisioning in two
ways:
v You can restrict access to a given resource at the VMware authorization level. If
the user name specified when defining the vCenter server to SmartCloud
Orchestrator does not have access to a given resource, it is unavailable to the
SmartCloud Orchestrator platform. If you use this method, no VMs or templates
on the restricted hosts or data stores are detected. This may be a problem
because a user might want to manage some existing VMs but not provision to
the hosting resources where those VMs are located.
v You can control data store placement in a given OpenStack flavor using Nova
extra specifications. To do this, run the nova flavor-key command to get a list of
the defined flavors, and update the ones you want by entering the following
command on one line:
nova flavor-key <flavor name>
set ibm-smartcloud:VMWareDatastoreIncludeList="<list of datastores separated by comma>"
Note: All SmartCloud Orchestrator extra specifications have ibm-smartcloud in
their name.
Discovery of the vCenter resources in SmartCloud Orchestrator
Discovery is performed using Java API for vCenter. SmartCloud Orchestrator is
also registered in order to receive vCenter events which allows for detection of
changes, such as VM movements, starting of a VM.
Discovery of resources in case more clusters and some stand-alone servers are
defined
SmartCloud Orchestrator treats each VMware cluster and stand-alone ESXi hosts as
a single hypervisor, referred to in the user interface by the name of the OpenStack
availability zone to which the openstack-smartcloud service belongs. You can run
nova-manage service list and nova-availability-zone-list to verify it. The
default name is openstack-nova-vmware. Any virtual machines that already exist
are exposed to SmartCloud Orchestrator as virtual machines running under that
openstack-nova-vmware hypervisor. Information on where those machines are
physically located is unavailable.
Virtual machines mobility scenarios
SmartCloud Orchestrator tolerates moving virtual instances in the same VMware
cluster by means of manual exercise of VMware vMotion feature or by means of
automatic migration capability (for example DRS). Moving deployed instances
across VMware clusters is not supported.
Chapter 4. Administering 189
Restricting access to vCenter:
You can use VMware security settings to restrict the vSphere resources available to
SmartCloud Orchestrator users.
Procedure
1. In your vCenter system, create a user that can be used by SmartCloud
Orchestrator to access VMware resources.
2. In your VMware system, create an administrative role for SmartCloud
Orchestrator.
a. In the vSphere Client Home page, click AdministrationRoles > Add roles.
The Add New Role panel opens.
b. Type the Name for the new role.
c. Select at least the privileges described in VMware administrative user
minimum rights.
3. Create/Select one or more datacenter for each region that you are going to
create leveraging the same vCenter.
Note: Two different SmartCloud Orchestrator users accessing same datacenter
is not a supported configuration.
4. In vSphere, assign to the SmartCloud Orchestrator user the newly created role
on the vCenter server (deselecting the propagate option), and assign same role
(selecting the propagate option) on the datacenters and clusters that you want
to use for your cloud.
Results
When the vCenter connection is created using the nova-cloud-create command,
then only the authorized resources are available using this new user ID.
VMware administrative user minimum rights:
This topic describes the minimum rights for an administrative VMware user.
Table 21. The minimum rights of a VMware administrative user
Privilege name Options to be selected
Data store
v Allocate space
v Browse DataStore
v Configure datastore
v Low level file operations
v Move datastore
v Remove datastore
v Remove file
v Rename datastore
v Update virtual machine files
Distributed Virtual Port Group
v Create
v Modify
v Delete
190 IBM SmartCloud Orchestrator 2.3: User's Guide
Table 21. The minimum rights of a VMware administrative user (continued)
Privilege name Options to be selected
Network
v Assign Network
v Configure
v Move Network
Resources
v Assign virtual machine to resource pool
v Create resource pool
v Remove resource pool
Virtual Machine Select all permissions in this group.
Task
v Create task
v Update task
Folder Delete folder
Global
v Act as vCenter
v Cancel Task
v Disable methods
v Enable methods
v Licenses
v Log Event
v Manage custom attribute
v Proxy
v Script action
v Set custom attribute
v Settings
Host Inventory:
v Remove cluster
v Remove host
Fields on the Hypervisors window:
You can administer your hypervisors using the fields on the Hypervisors window
of the SmartCloud Orchestrator user interface.
To work with hypervisors on the SmartCloud Orchestrator user interface, select it
from the list in the left panel of the Hypervisors window. Selecting a hypervisor
shows the following fields:
Type Shows OpenStack the type of the hypervisor.
Version
The type and version of the server.
Current status
The status, or hints about the state, of the hypervisor. If the hypervisor is
not started, this field provides hints about missing configuration that is
necessary before the hypervisor can be started. This field shows the status
of the hypervisor as one of the following states:
v Started
v Maintenance mode
v Resetting
Chapter 4. Administering 191
v Quiesced
v System is powered off
This field might, for example, provide details about a problem if the
hypervisor has been placed in an error state. For more information about
these states, see the Hypervisor states on page 207 information.
In cloud group
The name of the cloud group to which this hypervisor belongs. The name
is a link that can be clicked to view the cloud group details in the Cloud
Groups window.
Performance
Indicates, in a graphic display, the CPU usage and memory usage status.
Initially, only the Hypervisor line is shown. Clicking the show more link
expands the display to show all of the following machine usage:
Hypervisor
The actual processor and memory usage of the started hypervisor.
Included is any extra usage on the hypervisor from a SmartCloud
Orchestrator perspective, such as virtual machines that are not
managed by SmartCloud Orchestrator.
If stopped machines started
This hypothetical status would show the processor usage and
memory usage of the stopped and started hypervisors if the
following criteria were true:
v All active virtual machines were using full resources (in addition
to what they are currently actually using)
v All stopped virtual machines were using all their assigned
resources
If stored machines started
This hypothetical status would show the processor usage and
memory usage of the stopped, started, and archived hypervisors if
the following criteria were true:
v All active virtual machines were using full resources (in addition
to what they are currently actually using)
v All stopped virtual machines were using all their assigned
resources
v All archived virtual machines were using all of their resources
Active unmanaged virtual machines
Provides the processor and memory usage of any virtual machines
that are active but that are unmanaged. Unmanaged virtual
machines are those that were discovered on a hypervisor that was
already running and not started with SmartCloud Orchestrator.
If all unmanaged machines started
This hypothetical status shows what the processor and memory
usage would be if all of the unmanaged virtual machines were
started. Unmanaged virtual machines are those that were
discovered on a hypervisor that was already running and not
started with SmartCloud Orchestrator.
The show more or show less toggle either expands all of these displays or
shows only the Hypervisor status.
192 IBM SmartCloud Orchestrator 2.3: User's Guide
Deployment statistics
Summary information is initially shown in the Deployment statistics
section that provides a summary of deployments. For example, the
Deployment statistics summary line could show: 12 successful, 0 failed, 0
consecutive failures. Click to expand and show the following, more
detailed, information about the deployments on this hypervisor:
Successful deployments
The number of successful deployments on this hypervisor.
Failed deployments
The number of failed deployments on this hypervisor.
Note: This number includes only deployments that failed at
registration stage when the hypervisor is actually involved. Any
deployment that fails at other stages for reasons like, for example,
Not all cloud resources could be reserved or No physical
machines are found for the hypervisor are not included in the
deployment statistics.
Consecutive failures
The number of consecutive failures.
Updated on
The date on which the deployment status was last updated.
History
The summary line in the History section shows the last action performed
on this hypervisor. For example, the History summary line could show:
Maintenance mode (must select a storage to use to start). Click to expand
and show a list of actions performed on the hypervisor, with a time stamp
for each.
Virtual machines
Each virtual system instance contains a set of virtual machines that
represent a physical node in an application server environment. If you are
working with a hypervisor in a cloud group that has been deployed, this
field is available. When cloud groups have been deployed, the Virtual
machines field provides a list of the virtual machines linked to this
hypervisor. Summary information is provided for the total number of
virtual machines and the number of virtual machines that are started.
For information about configuring virtual system instances, see Managing
virtual system instances on page 562.
Networks
The summary line in the Networks section shows the status of the
networks in this hypervisor. For example, the Networks summary line
could show: 3 total, 2 in use, 1 mapped to IPGroups. See Network fields
on the Hypervisor window on page 205 for more information.
Storage devices
Clicking this link expands a list of storage devices that are linked to this
hypervisor. For more information about storage devices, see Storage fields
on the Hypervisor window on page 206.
Chapter 4. Administering 193
Administering virtual machines:
Virtual machines are assigned to and hosted by a hypervisor. You can access the
individual virtual machines using either the SmartCloud Orchestrator user
interface or the command-line interface.
Before you begin
You can administer virtual machines with the user interface or the command-line
interface. To use the command-line interface download and configure the tool. See
Downloading and configuring the command-line interface on page 909 and
Invoking the command-line interface on page 911 for more information.
About this task
With SmartCloud Orchestrator, you can access any of the virtual machines that are
hosted on your hypervisors.
Procedure
Determine the interface you want to work with and see the following information:
v Use the information provided in Administering virtual machines with the user
interface to work with your virtual machines on the user interface.
v Use the information provided in Virtual machines on the command-line
interface on page 899 to work with virtual machines on the command-line
interface.
Results
After completing these steps, you have accessed or managed your virtual
machines.
What to do next
You can work with your hypervisor, the cloud containing it, or your virtual system
instance.
Related reference:
Virtual machines on the command-line interface on page 899
This topic provides a reference for administering virtual machines using the
SmartCloud Orchestrator command-line interface.
Administering virtual machines with the user interface:
Each virtual system instance 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 access the individual virtual
machines from the Hypervisors window of the user interface.
Before you begin
You must specifically be granted access to the hypervisor you intend to access.
Optionally, you can be assigned the admin role to perform these steps.
194 IBM SmartCloud Orchestrator 2.3: User's Guide
About this task
With SmartCloud Orchestrator, you can access any of the virtual machines that are
hosted on your hypervisors.
Procedure
1. You can access virtual machines from the Hypervisors window by clicking
Configuration > Hypervisors on the menu.
Tip: You can also access virtual machines in a virtual system instance from the
Virtual System Instances window. For more information, see Accessing virtual
machines in your virtual system instance on page 573
2. From the left panel of the Hypervisors window, select the associated
hypervisor. Information about the hypervisor 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 on the selected
hypervisor. The number of virtual machines that exist for the hypervisor is
dependent on the number being hosted by the hypervisor. From the list of the
virtual machines included in this hypervisor, you can view both managed and
unmanaged virtual machines. For more detailed information about the fields of
information, see Virtual machine fields on the Hypervisor window on page
198.
4. View the details for your virtual machine. 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.
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
this, the DNS server must be correctly configured to resolve the virtual machine
host name. For more information about configuring DNS, see Configuring
DNS for the Workload Deployer IP groups on page 61.
Results
After completing these steps, you have accessed your virtual machine from the
user interface.
Chapter 4. Administering 195
Related tasks:
Administering hypervisors on page 187
You can use the SmartCloud Orchestrator user interface to work with the
hypervisors.
Monitoring your virtual machines:
Each virtual system instance 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 hypervisor you intend to access.
Optionally, you can be assigned the admin role to perform these steps.
About this task
You can view and monitor the details about each virtual machine by following
these steps.
Procedure
1. From the left panel of the Hypervisors window, select the associated
hypervisor. Information about the hypervisor 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 hypervisor. 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 1.
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 associated with this virtual machine. 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).
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 Manage link to show or hide the available actions for the virtual
machine.
Move This action is not currently supported.
Start If a virtual machine is stopped, then it can be restarted using
this action.
Stop If a virtual machine is running, then it can be stopped using the
stop action.
196 IBM SmartCloud Orchestrator 2.3: User's Guide
Note: If your application is running DB2, and the application is
stopped and an operation that cannot be interrupted (RESTORE
DATABASE, for example) is forced, the operation must be
successfully restarted before the database becomes available
again. See the DB2 information center topic, STOP DATABASE
MANAGER command, for more information.
Delete A virtual machine can be deleted to release the resources
associated with it.
Take Over
You can take over a virtual machine that was not provisioned
by using SmartCloud Orchestrator. For more information, see
Importing virtual machines.
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 more information about the fields for
each virtual machine, see Virtual machine fields on the Hypervisor window
on page 198.
Results
After you have completed these steps, you have reviewed the details for your
virtual machines.
What to do next
When you have your virtual machines ready, you can work with the hypervisor.
Related information:
STOP DATABASE MANAGER command
Importing virtual machines:
You can import a virtual machine that was not provisioned by using SmartCloud
Orchestrator.
Before you begin
You must be assigned the admin role to perform these steps.
About this task
You can import unmanaged virtual machines hosted by an hypervisor in the
SmartCloud Orchestrator environment.
Note: The imported virtual machine does not affect the quota usage.
To import an unmanaged virtual machine, perform the following steps:
Procedure
1. From the left panel of the Hypervisor window, select the hypervisor currently
hosting the virtual machines to be imported.
2. Expand the list of virtual machines to view by clicking the expand icon next to
Virtual Machines.
Chapter 4. Administering 197
3. Optional: You can expand the details for a virtual machine by clicking the
expand icon next to the <virtual_machine_name>.
4. Choose the virtual machine, or groups of virtual machines, to be imported. You
can import only unmanaged virtual machines.
Importing a single virtual machine
a. From the list of virtual machines, click the Manage link (under the
Actions column) beside any individual virtual machine to view the
actions you can perform.
b. Click the Import the virtual machine icon to import that single
virtual machine.
Importing a selection of virtual machines
a. From the list of virtual machines, check the check box on the far
right column beside any virtual machines you want to import as a
group. Likewise, you can remove the check from any virtual
machines you decide not to import.
b. Click the Group Actions link at the top right of the list of virtual
machines listing to display the available actions.
c. Click the Import selected virtual machines icon to import any
selected virtual machines.
Importing all the virtual machines
a. From the list of virtual machines, check the check box in the far
right column of the header row to select all of the virtual machines
in the list.
b. Click Group Actions to display the actions you can perform for the
virtual machines.
c. Click the Import selected virtual machines icon.
Results
After you completed these steps, you can manage the virtual machine in the
Imported Virtual Machines window. To access the Imported Virtual Machines
window, click Instances > Virtual Machines.
In the Imported Virtual Machines window, you can see details about virtual
machines and you can start, stop, or delete the virtual machine that you select.
Virtual machine fields on the Hypervisor window:
You can work with the virtual machines that are associated with a hypervisor
using the Virtual machines panel on the Hypervisors window.
Virtual machine summary fields
The Virtual machines section is shown on the right panel of the Hypervisors
window when a specific hypervisor is selected. Before being expanded, the Virtual
machines section shows a status summary line. The status line shows the total
number of virtual machines for this hypervisor, 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 in the
hypervisor and how many are in which state. When expanded, the Virtual
machines section lists the virtual machines in the hypervisor.
198 IBM SmartCloud Orchestrator 2.3: User's Guide
The following check boxes allow you to filter the virtual machines listed:
Show virtual machines that are
started only
Click this check box to show, in the listing of virtual machines,
only the virtual machines on this hypervisor that are started.
unmanaged
Click this check box to show, in addition to the managed machines
in the listing of virtual machines, the virtual machines on this
hypervisor that are not managed by SmartCloud Orchestrator.
Virtual machines, displayed on the Hypervisors window, can be
either managed by SmartCloud Orchestrator or unmanaged. Some
information is available about the unmanaged virtual machines
that were discovered with the hypervisor. More information is
available about the managed virtual machines that were started by
this SmartCloud Orchestrator.
You can import an unmanaged virtual machine to make it
managed by SmartCloud Orchestrator. For more information about
importing virtual machines, see Importing virtual machines on
page 197.
deleted
Click this check box to show, in addition to the current machines in
the listing of virtual machines, the virtual machines that have been
deleted from this hypervisor.
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 hosted by the hypervisor 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 Displays, graphically and numerically, the percentage of available
processor being used by this virtual machine.
Memory
Provides the graphic and numeric percentage of available memory being
used by this virtual machine.
SSH Clicking the Login link opens a dialog to log in to an SSH session. This
link is not available for virtual machines that were imported.
Actions
Clicking the Manage link under this column heading for any virtual
machine displays or hides the following set of icons to work with the
individual virtual machine:
Move This action is not currently supported.
Start If it is stopped, starts the virtual machine.
Stop If it is started, stops the virtual machine.
Delete If you have permission, you can delete the virtual machine.
Import
You can import a virtual machine that was not provisioned by
Chapter 4. Administering 199
using SmartCloud Orchestrator. For more information, see
Importing virtual machines on page 197.
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 provides basic information about that virtual machine. The
fields displayed in this section are different for managed and unmanaged virtual
machines.
The following fields are shown for managed virtual machines:
Created on
Specifies the time and the date the virtual machine was created. This field
is automatically generated.
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.
Part name
The name of the part.
Current status
Specifies the status of the virtual machine.
Updated on
Specifies the time and date of the last change to the virtual machine.
In virtual system
Specifies the virtual system instance in which this virtual machine
represent a physical node (in an application server environment). The
virtual system instance name is a link. You can click the link to display
details about the virtual system instance in which this virtual machine
resides.
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.
200 IBM SmartCloud Orchestrator 2.3: User's Guide
In virtual application
Specifies the virtual application that contains this virtual machine.
The following fields are shown for unmanaged virtual machines:
Registered as
Specifies how the virtual machine is registered on the hypervisor.
Current status
Specifies the status of the virtual machine.
Hypervisor
Specifies the hypervisor where the virtual machine is running.
Virtual CPU count
A numeric count of the CPU detected.
CPU shares on host
A numeric representation of the shares of CPU detected on the host.
CPU shares consumed on host
A numeric representation of the shares of CPU that the host has actually
used.
Virtual memory (MB)
A numeric representation of the virtual memory detected, in MB.
Memory consumed on host
A numeric representation of the memory detected as actually having been
used on the host.
Hardware and network
If the virtual machine is managed by SmartCloud Orchestrator, the Hardware and
network section is shown. If the virtual machine is unmanaged, this information is
not available.
Virtual CPU count
This field 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 on
page 511 for more details on the pattern options.
SSH public key
The name of, and a link to, the public key.
Network interface
The network interface address.
Multiple pairs of network interface and MAC address definitions show
multiple network interface controllers (NICs) defined. You could see a
default NIC and add-on NICs.
MAC address
Specifies the Media Access Control (MAC) address of the virtual machine.
Multiple pairs of network interface and MAC address definitions show
multiple NICs defined. You could see a default NIC and add-on NICs.
Chapter 4. Administering 201
Operating System
If the virtual machine is managed by SmartCloud Orchestrator, the Operating
System section is shown. If the virtual machine is unmanaged, this information is
not available.
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 command uname - a for the operating
system on the virtual machine.
Script Packages
If the virtual machine is managed by SmartCloud Orchestrator, the Script Packages
section is shown. If the virtual machine is unmanaged this information is not
available.
This field specifies 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. For more information about script packages,
see Managing script packages on page 234.
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 254.
Consoles
If the virtual machine is managed by SmartCloud Orchestrator, the Consoles
section is shown. If the virtual machine is unmanaged this information is not
available.
This field provides links to access your virtual machine. For more information
about accessing your virtual machines, see Administering virtual machines on
page 194.
Related tasks:
Administering virtual machines on page 194
Virtual machines are assigned to and hosted by a hypervisor. You can access the
individual virtual machines using either the SmartCloud Orchestrator user
interface or the command-line interface.
202 IBM SmartCloud Orchestrator 2.3: User's Guide
Administering networks:
You can administer networks using either the SmartCloud Orchestrator user
interface or the command-line interface.
Before you begin
SmartCloud Orchestrator can be run on two or more networks.
Note: When you are setting up an ESX network, select the default port group.
Selecting the default port group ensures that the IP groups you assign to networks
are associated with the correct NIC card. If you select incorrect network settings,
you receive no verification that you are setting up the IP group for the correct NIC
card. Your deployments then fail.
You can administer networks with the user interface or the command-line
interface. To use the command-line interface download and configure the tool. See
Downloading and configuring the command-line interface on page 909 and
Invoking the command-line interface on page 911 for more information.
About this task
You can provide network management and structure using the SmartCloud
Orchestrator to work with network resources, such as IP addresses within IP
groups. The simplest setup is to use one 24 bit subnet for the SmartCloud
Orchestrator, the hypervisors, and the virtual system instances.
Procedure
Determine the interface you want to work with and see the following information:
v Use the information provided in Administering networks with the user
interface on page 204 to work with networks on the user interface.
v Use the information provided in Network command-line interface reference on
page 843 to work with networks on the command-line interface.
Related tasks:
Building the cloud with topology resources on page 183
You can build clouds using your existing resources, for example hypervisors,
networks and storage, with SmartCloud Orchestrator. SmartCloud Orchestrator
manages these resources in the cloud.
Administering networks with the user interface on page 204
You can specify network information for hypervisors using the SmartCloud
Orchestrator user interface.
Related reference:
Network command-line interface reference on page 843
You can work with the network resource objects on the SmartCloud Orchestrator
command-line interface.
Networks REST API on page 991
You can use the representational state transfer (REST) application programming
interface (API) to manage networks.
Chapter 4. Administering 203
Administering networks with the user interface:
You can specify network information for hypervisors using the SmartCloud
Orchestrator user interface.
Before you begin
You must have administrative access to edit or provide hypervisor network
information.
About this task
You can view and configure the connection characteristics of a hypervisor (the
network information) on the Hypervisors window. For more information about the
Hypervisors window, see Administering hypervisors on page 187. Multiple
networks can be defined for a hypervisor and at least two networks are required.
Hypervisor networks cannot be manually defined to SmartCloud Orchestrator.
Hypervisor networks are automatically discovered when the hypervisor is defined
and you accept the security certification. You can also accept the security
certification when you reset the storage and network connections of the hypervisor.
Procedure
1. From the left panel of the Hypervisors window, select the hypervisor for which
to configure the network settings. If you have administrative access to a
hypervisor, you can edit it, or you can create a new one.
2. Put the hypervisor in maintenance mode. See Administering hypervisors on
page 187 for more information.
3. In the right panel, expand the Networks link.
4. Select the networks you want to include. Click the In use box for any networks
to be used. By default, when you add a hypervisor, none of the networks are
selected. To start the hypervisor, at least one network must be selected.
You can also remove the check from the In use box for any networks you do
not want to include.
Note: For VMware clusters, only the networks that are common to all the ESX
servers in the cluster are displayed. If the message No network found or no
common network found is displayed, ensure that there is at least one network
that is commonly defined to each ESX server in the cluster.
5. Expand the network you want to configure.
6. Edit the required IP group information for the network. See Administering IP
groups and IP addresses on page 208 for more information about IP groups.
SmartCloud Orchestrator cannot detect incorrect settings for the network;
therefore, be sure that you specify the correct information.
Note:
v An IP group must be specified for at least one network before the hypervisor
can be started.
v Assigning an empty IP group results in multiple network interface
controllers (NICs).
Related tasks:
Building the cloud with topology resources on page 183
You can build clouds using your existing resources, for example hypervisors,
networks and storage, with SmartCloud Orchestrator. SmartCloud Orchestrator
204 IBM SmartCloud Orchestrator 2.3: User's Guide
manages these resources in the cloud.
Related reference:
Network command-line interface reference on page 843
You can work with the network resource objects on the SmartCloud Orchestrator
command-line interface.
Network fields on the Hypervisor window:
You can work with the networks that are associated with a hypervisor using the
Networks panel on he Hypervisors window.
Network summary fields
The Networks section is shown on the right panel of the Hypervisors window
when a specific hypervisor is selected. Before being expanded, the Networks
section shows a status summary line. The status summary line shows the total
number of networks for this hypervisor, the number in use, and the number that
have an IP group assigned. For example, the status bar could read: 4 total, 2 in
use, 1 mapped to IPGroups to indicate the total number of networks in the
hypervisor and how many are in which state. When expanded, the Networks
section lists the networks in the hypervisor by name and shows whether or not the
network is in use. Expand an individual network to see the following fields for
each network in the list.
Note: For VMware clusters, only the networks that are common to all the ESX
servers in the cluster are displayed. If the message No network found or no common
network found is displayed, ensure that there is at least one network that is
commonly defined to each ESX server in the cluster.
In use Indicates whether the network attachment on this hypervisor is in use.
Click this check box to put a network in use.
VLAN The virtual local area network (VLAN), as defined for the hypervisor
network element, on the hypervisor console. The VLAN value cannot be
changed in SmartCloud Orchestrator; it is reported here for convenience.
IP group
Shows the IP group to be used with the network element of a hypervisor if
one has been selected. If an IP group has not been selected and the
hypervisor is in maintenance mode, use this field to select one. For more
information about IP groups, see Administering IP groups and IP
addresses on page 208.
Note: An IP group must be specified for at least one network in the
hypervisor before the hypervisor can be started.
Shared Network
Specifies if the network is shared in the cloud group.
Related tasks:
Administering networks with the user interface on page 204
You can specify network information for hypervisors using the SmartCloud
Orchestrator user interface.
Chapter 4. Administering 205
Administering storage:
You can administer storage using the SmartCloud Orchestrator user interface or the
command-line interface.
Before you begin
To use the command-line interface download and configure the tool. See
Downloading and configuring the command-line interface on page 909 and
Invoking the command-line interface on page 911 for more information.
About this task
Multiple storage devices can be defined for a hypervisor. Hypervisor storage
cannot be manually defined to SmartCloud Orchestrator. It is automatically
discovered when the hypervisor is defined or when you reset the connections. You
can administer storage specifications with the user interface or the command-line
interface tool.
Procedure
Determine the interface you want to work with and see the following information:
v Use the information provided in Storage fields on the Hypervisor window to
work with storage specifications on the user interface.
v Use the information provided in Storage command-line interface reference on
page 882 to work with storage specifications on the command-line interface.
Related tasks:
Building the cloud with topology resources on page 183
You can build clouds using your existing resources, for example hypervisors,
networks and storage, with SmartCloud Orchestrator. SmartCloud Orchestrator
manages these resources in the cloud.
Related reference:
Storage REST API on page 1006
You can use the representational state transfer (REST) application programming
interface (API) to manage storage.
Storage fields on the Hypervisor window:
You can work with the storage devices in use with the hypervisor using the
Storage panel on the Hypervisors window.
Storage fields
The Storage section is shown on the right panel of the Hypervisors window when
a specific hypervisor is selected. Before being expanded, the Storage section shows
a status summary line. The status summary line shows the total number of storage
devices for this hypervisor, the number in use, and a graphical representation of
what is in use Right now and what is Reserved. For example, the status bar could
read: 3 total, 1 in use and the graphical bars to indicate the amount currently in
use and what is reserved. This status indicates the total number of storage devices
in the hypervisor and how many are in which state. The following fields
graphically display summarized information about the storage devices associated
with this hypervisor:
206 IBM SmartCloud Orchestrator 2.3: User's Guide
Right now
The current percentage of storage device usage.
Reserved
The percentage of storage device space that has been reserved.
When expanded, the Storage section lists the storage devices in the hypervisor by
name. Expand an individual storage device to see the following fields for each
storage device in the list.
In use Indicates whether the storage device attachment on this hypervisor is in
use. It is always checked.
Device type
The type of storage device. For example, VMFS.
Used space (MB)
The space used on the storage device, reported in megabytes.
Reserved space (MB)
The space that has been reserved, but not yet used, on the storage device,
reported in megabytes.
Free space (MB)
The free space available on the storage device, reported in megabytes.
Total space
The total space on the storage device, reported in megabytes.
Unique ID
The identification string for the storage device.
Shared by other hypervisors
Displays the hypervisors, if any, for which this storage device is also
associated.
Related tasks:
Administering storage on page 206
You can administer storage using the SmartCloud Orchestrator user interface or the
command-line interface.
Hypervisor states:
SmartCloud Orchestrator manages hypervisors from the user interface or the
command-line interface.
In SmartCloud Orchestrator, hypervisors can be in the following states:
Maintenance mode
The hypervisor is not running or accepting work and can be configured.
You can reset the resource connections only when the hypervisor is in this
state. Hypervisors with virtual system instances that are started cannot be
put in maintenance mode until all virtual system instances are stopped.
Resetting
The hypervisor is resetting the storage and network information. This
information is being reset for one of the following reasons:
v A user has requested this action
v The security certificate is being obtained for the first time
The resetting state is a special case of the maintenance mode state.
Chapter 4. Administering 207
Started
The hypervisor is able to accept work and might already be running work.
It cannot be configured in this state.
Disconnected
A hypervisor enters the disconnected state when it is in the started state
and a temporary disruption occurs in the communication between
SmartCloud Orchestrator and the hypervisor. If the disruption is resolved
within approximately 15 minutes, the hypervisor goes back into the started
state in the console, with no user intervention required.
Quiesce
The hypervisor is in a suspended state and it is not accepting new
deployments.
Failed A failure occurred and has been reported. This status usually indicates a
connection problem between SmartCloud Orchestrator and the hypervisor.
In this case, the following status message is also displayed: The hypervisor
cannot be deleted due to existing instances.
A failed state also results if sufficient information cannot be gathered by
the hypervisor like the processor model or metric information.
Administering IP groups and IP addresses
IP groups contain IP addresses that are managed separately within each group.
Before you begin
You must have administrative access to the range of IP addresses to use with
SmartCloud Orchestrator. If you are creating IP groups, you must also decide how
you want to group these IP addresses into IP groups.
About this task
In SmartCloud Orchestrator, the networks defined in your OpenStack environment
are automatically listed as IP groups named region-name_network-name, where
region-name is the name of the region where the network named network-name is
defined. For more information about managing networks in OpenStack, see
Configuring Networking on the Compute Node in the OpenStack documentation.
Note: For OpenStack networks that do not use a DHCP server, the number of IP
addresses that are automatically listed for each IP group is limited to 20 by default.
For more information about modifying this number, see Configuring OpenStack
synchronization on page 146.
In addition to the IP groups defined in OpenStack, you can create and manage IP
groups directly in your SmartCloud Orchestrator environment.
You can administer IP groups with the SmartCloud Orchestrator user interface or
the command-line interface. If you use the command-line interface, download and
configure it. For more information, see Downloading and configuring the
command-line interface on page 909 and Invoking the command-line interface
on page 911.
Procedure
1. See the information about IP groups and IP addresses. Information about how
IP groups contain IP addresses is available in IP groups on page 209.
2. Determine the interface with which to work.
208 IBM SmartCloud Orchestrator 2.3: User's Guide
v To work with the user interface, use the information provided in
Administering IP groups and IP addresses with the user interface on page
210.
v To work with the command-line interface, use the information provided in
IP command-line interface reference on page 834 and IP group
command-line interface reference on page 838.
Related tasks:
Building the cloud with topology resources on page 183
You can build clouds using your existing resources, for example hypervisors,
networks and storage, with SmartCloud Orchestrator. SmartCloud Orchestrator
manages these resources in the cloud.
Related reference:
IP command-line interface reference on page 834
You can work with IP addresses, using the IPs and IP objects on the SmartCloud
Orchestrator command-line interface.
IP group command-line interface reference on page 838
You can work with IP groups on the SmartCloud Orchestrator command-line
interface using the IPgroups and IPgroup objects and attributes.
IP groups REST API on page 977
You can use the representational state transfer (REST) application programming
interface (API) to manage IP groups.
IP addresses REST API on page 973
You can use the representational state transfer (REST) application programming
interface (API) to manage IP addresses.
IP groups:
SmartCloud Orchestrator manages IP groups, or collections of IP addresses.
An IP group is a range of IP addresses that you can select to use them with
specific hypervisors. For example, you might split 100 IP addresses into four blocks
of 25 IP addresses to be used by four departments in your enterprise. Though
these IP addresses are all on the same real subnet in this example, creating the IP
groups enables you to manage them separately and to ensure that they are only
used by SmartCloud Orchestrator for a particular purpose. Alternatively, for IPv4
networks, you can create IP groups that obtain the IP addresses from a DHCP
server.
In SmartCloud Orchestrator, the networks defined in your OpenStack environment
are automatically listed as IP groups named region-name_network-name, where
region-name is the name of the region where the network named network-name is
defined. For more information about managing networks in OpenStack, see
Configuring Networking on the Compute Node in the OpenStack documentation.
Note: For OpenStack networks that do not use a DHCP server, the number of IP
addresses that are automatically listed for each IP group is limited to 20 by default.
For more information about modifying this number, see Configuring OpenStack
synchronization on page 146.
In addition to the IP groups defined in OpenStack, you can create and manage IP
groups directly in your SmartCloud Orchestrator environment.
IP addresses are only accessible to SmartCloud Orchestrator through IP groups.
When you create an IP group that obtains IP addresses from an IP address pool,
Chapter 4. Administering 209
you give it an address and a netmask that defines the IP group. You then define a
pool of IP addresses within the subnet (an IP group within a subnet) that are
available to SmartCloud Orchestrator. IP groups enable you to partition a subnet.
Therefore, blocks of IP addresses from the subnet can be assigned to a hypervisor,
department, or other entity. You can also partition the subnet into smaller
groupings. You can create IP groups with duplicate subnet information. You can
enter IP addresses by specifying a range in the user interface or the command-line
interface.
By default, SmartCloud Orchestrator uses all available IP addresses from the IP
group.
If you do not enter any IP address and you are not using an IP group that obtains
IP addresses from a DHCP server, you cannot deploy virtual systems to
hypervisors using that IP group. Messages alert you about possible errors.
The IP group must have available addresses for the maximum number of virtual
machines that you want to access in the cloud. To enhance performance, a
minimum of 10 available IP addresses is required, however for any significant
cloud deployments, substantially more available IP addresses are needed. To
determine how many IP addresses you need, you can count the number of virtual
image parts. Each virtual image part is equal to one unique IP address.
Related tasks:
Building the cloud with topology resources on page 183
You can build clouds using your existing resources, for example hypervisors,
networks and storage, with SmartCloud Orchestrator. SmartCloud Orchestrator
manages these resources in the cloud.
Administering IP groups and IP addresses with the user interface:
You can create, edit, or delete IP groups using the SmartCloud Orchestrator user
interface. You can also add IP addresses to an IP group or remove IP addresses
from an IP group.
Before you begin
You must have administrative access to the range of IP addresses to use with
SmartCloud Orchestrator.
About this task
In SmartCloud Orchestrator, the networks defined in your OpenStack environment
are automatically listed as IP groups named region-name_network-name, where
region-name is the name of the region where the network named network-name is
defined. For more information about managing networks in OpenStack, see
Configuring Networking on the Compute Node in the OpenStack documentation.
Note: For OpenStack networks that do not use a DHCP server, the number of IP
addresses that are automatically listed for each IP group is limited to 20 by default.
For more information about modifying this number, see Configuring OpenStack
synchronization on page 146.
In addition to the IP groups defined in OpenStack, you can create and manage IP
groups directly in your SmartCloud Orchestrator environment.
To work with IP groups and IP addresses, perform the following steps:
210 IBM SmartCloud Orchestrator 2.3: User's Guide
Procedure
1. Open the IP Groups window by clicking Configuration > IP Groups from the
menu bar.
2. Determine the task. You can perform the following tasks with the SmartCloud
Orchestrator user interface:
Adding an IP group
Add an IP group and define ranges of IP addresses using the
instructions provided in Creating an IP group.
Editing IP groups
If you have administrative access, you can edit IP groups using the
instructions provided in Adding IP addresses and IP groups on page
214.
Deleting IP groups
If you have administrative access, you can delete IP groups from a
hypervisor using the instructions provided in Deleting IP addresses
and IP groups on page 215.
Results
You have created, edited, or deleted your IP group or groups.
What to do next
When you have created the IP group or groups, define them to the hypervisor. See
Administering hypervisors on page 187 for more information about adding IP
groups to the hypervisor.
Related reference:
IP command-line interface reference on page 834
You can work with IP addresses, using the IPs and IP objects on the SmartCloud
Orchestrator command-line interface.
IP group command-line interface reference on page 838
You can work with IP groups on the SmartCloud Orchestrator command-line
interface using the IPgroups and IPgroup objects and attributes.
IP groups REST API on page 977
You can use the representational state transfer (REST) application programming
interface (API) to manage IP groups.
IP addresses REST API on page 973
You can use the representational state transfer (REST) application programming
interface (API) to manage IP addresses.
Creating an IP group:
You can create an IP group and specify a range of IP addresses, using the
SmartCloud Orchestrator user interface.
Before you begin
You must have administrative access to the range of valid IP addresses to add to
the IP group you are creating.
Chapter 4. Administering 211
Attention: Do not use host names in the .local domain, for example
machine1.mycompany.local. Ensure that the host names for your IP addresses are in
a domain other than .local. SmartCloud Orchestrator does not support host
names in the .local domain.
About this task
IP addresses are only accessible to SmartCloud Orchestrator when they are
included in IP groups. When you create an IP group that does not obtain IP
addresses from a DHCP server, you must specify an address and a netmask that
defines the IP group. Then you define a pool of IP addresses within the IP group
that are available to hypervisors which are also defined to SmartCloud
Orchestrator. SmartCloud Orchestrator validates the information and creates the IP
group.
Procedure
1. From the upper right of the left panel of the IP Groups window, click the Add
icon.
2. Provide the required information. Provide the following information in the
Describe the IP group you want to add window:
Name Enter a unique IP group name to represent and identify the IP group.
Version
Select IPv4 or IPv6 from the list to specify the version.
Attention: Workloads that require IP caching must be deployed to
cloud groups with only IPv4 IP groups.
Obtain IP addresses from
Select DHCP Server or IP Address Pool to specify from where the IP
group obtains the IP addresses available to the hypervisors. You can
select DHCP Server only for IPv4 IP groups.
3. If you specified to obtain IP addresses from an IP address pool or you are
creating a IPv6 IP group, provide the following information:
Subnet address
Enter a valid subnet address. This subnet address is associated with the
IP group represented as a string in dotted decimal notation, for
example: 192.168.98.0.
Netmask
If you are using IPv4, enter a value for the netmask. This network mask
is 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.
Gateway
Enter a gateway name. This default gateway is associated with the IP
group represented as a string in dotted decimal notation. For example,
if you are adding IPv4 or IPv6 IP addresses, the IP address might be
192.168.98.1. The gateway information is required.
Note: The gateway must be an IP address that can be resolved by the
address resolution protocol (ARP), even if the network itself is not
routed.
Primary DNS
Provide the primary Domain Name System (DNS) value for the IP
212 IBM SmartCloud Orchestrator 2.3: User's Guide
group. This DNS server is used for the IP group represented as a string
in dotted decimal notation, for example: 192.168.98.2.
Note: If the IP addresses for the DNS servers are not set up correctly,
the deployment can fail. The failure is due to the SSH connection with
the virtual machine failing.
Secondary DNS
Optionally, you can add a secondary DNS value for the IP group. This
secondary DNS server is used for the IP group represented as a string
in dotted decimal notation, for example: 192.168.98.2.
4. Click OK. The left panel of the IP Groups window shows the name of the IP
group you created. The right panel shows the configuration information.
5. If the IP group obtains IP addresses from an IP address pool, add the range of
IP addresses using one of the following methods:
v Add a range of IP addresses on the right panel of the IP Groups window in
the fields provided in IP Addresses: > Add range. Use the two entry fields
to specify the first and last IP addresses in the range of IP addresses to
include in the IP group. Click Add to add the IP address range.
v Add IP addresses as host names instead of the actual IP addresses. Clicking
Add Host Names provides an entry field in which you can enter the
space-delimited list of host names. When a host name is specified for an IP
address, the host name resolves to the IP address. However, what is entered
is what is stored. Therefore, if you enter the host name then the host name is
stored and not the IP address to which it resolves. If any of the host names
you enter cannot be resolved to an IP address, then a warning message is
shown beside any entry that cannot be resolved. If a host name is resolved to
an IP address but the IP address is not valid for the specified subnet, then an
error message is shown and the host name is not added to the IP Group.
Note: If an IP address cannot be resolved, it is marked with a red exclamation
point. The exclamation point indicates an error with the IP addresses you
entered that you must correct.
6. Optional: Add more addresses. Optionally, you can add more IP address ranges
to the IP group by repeating this procedure.
Results
You have defined your IP group with a range or ranges of IP addresses.
What to do next
Assign the IP group to the hypervisor using the Hypervisor panel as described in
Administering hypervisors on page 187.
Related reference:
IP command-line interface reference on page 834
You can work with IP addresses, using the IPs and IP objects on the SmartCloud
Orchestrator command-line interface.
IP group command-line interface reference on page 838
You can work with IP groups on the SmartCloud Orchestrator command-line
interface using the IPgroups and IPgroup objects and attributes.
IP groups REST API on page 977
You can use the representational state transfer (REST) application programming
interface (API) to manage IP groups.
Chapter 4. Administering 213
IP addresses REST API on page 973
You can use the representational state transfer (REST) application programming
interface (API) to manage IP addresses.
Adding IP addresses and IP groups:
You can add ranges of IP addresses to an IP group that obtains IP addresses from
an IP address pool, or add an IP group to a hypervisor. You can use the
SmartCloud Orchestrator user interface to add IP addresses or IP groups.
Before you begin
You must have created the IP group you want to edit or have administrative access
to it.
About this task
IP addresses are only accessible to SmartCloud Orchestrator when they are
included in IP groups. Edit an IP group to add the pools of IP addresses within the
IP group that are available to SmartCloud Orchestrator hypervisors. You can also
add or change the hypervisor to which this IP group is assigned.
Procedure
v Add IP addresses. Use the following steps to add IP addresses to an existing IP
group:
1. Select an IP group that obtains IP addresses from an IP address pool. From
the left panel of the IP Groups window, select the IP group to be edited.
2. Enter a range of IP addresses. On the right panel of the IP Groups window,
add IP addresses under the IP Addresses: section. Use one of the following
methods to add IP addresses under the Add range label:
Use the two entry fields, specifying the first and last IP addresses, and the
Add button to add a range of IP addresses.
Use the entry field and the Add Host Names button to enter space
delimited host names. Host names added are resolved to IP addresses and
checked for validity.
Added IP addresses are shown in the IP address list. If the IP address cannot
be located, an error message is shown beside the entry in the IP address list.
Likewise, if the host name cannot be resolved to an IP address, an error
message is shown beside the entry in the IP address list.
3. Add the IP addresses.
Note: If an IP address cannot be resolved, it is marked with a red exclamation
point. This icon indicates an error with the IP addresses you entered that you
must correct.
v Add an IP group to a hypervisor. You can add an IP group to a hypervisor from
the Hypervisors window using the following steps:
1. Select the hypervisor. Select the hypervisor in the left panel of the
Hypervisors window.
2. Put the hypervisor in maintenance mode. See Administering hypervisors
on page 187, for more information.
3. Select the IP group. Select the IP group to add under Networks > <network
name> > IP Group.
214 IBM SmartCloud Orchestrator 2.3: User's Guide
Results
You edited your IP group or changed the hypervisor to which it is assigned.
What to do next
When you have edited any needed IP group or groups defined to the hypervisor,
and hypervisor configuration is complete, you can start the hypervisor. You can
then run the hypervisor in the cloud. See Administering hypervisors on page 187
for more information about configuring the hypervisor.
Related tasks:
Administering hypervisors on page 187
You can use the SmartCloud Orchestrator user interface to work with the
hypervisors.
Related reference:
IP command-line interface reference on page 834
You can work with IP addresses, using the IPs and IP objects on the SmartCloud
Orchestrator command-line interface.
IP group command-line interface reference on page 838
You can work with IP groups on the SmartCloud Orchestrator command-line
interface using the IPgroups and IPgroup objects and attributes.
IP groups REST API on page 977
You can use the representational state transfer (REST) application programming
interface (API) to manage IP groups.
IP addresses REST API on page 973
You can use the representational state transfer (REST) application programming
interface (API) to manage IP addresses.
Deleting IP addresses and IP groups:
You can delete IP addresses from an IP group that obtains IP addresses from an IP
address pool, delete an IP group, or remove an IP group from a hypervisor. You
can use the SmartCloud Orchestrator user interface to delete IP addresses or IP
groups.
Before you begin
You must have created the IP groups and hypervisors or have administrative
access to them to edit these resources.
About this task
IP addresses are only accessible within IP groups. You can delete IP addresses from
IP groups or delete the entire IP group. When you delete an IP group you delete
the pool of IP addresses within the IP group that was available to SmartCloud
Orchestrator. You can also remove the IP group from the hypervisor. If you remove
the IP group from a hypervisor, the IP group is still available to use with another
hypervisor.
Procedure
v Remove IP addresses from an IP group that obtains IP addresses from an IP
address pool. To continue to use an IP group but to remove an IP address it
contains, use the following steps:
1. Select the IP group to be edited in the left panel of the IP Groups window.
Chapter 4. Administering 215
2. Locate the IP address. If it is not displayed, click the show more link at the
bottom of the list of IP addresses.
3. Remove the address. Click the remove link beside any IP addresses that you
want to remove.
v Remove an IP group from a hypervisor. To remove an IP group from a
hypervisor, use the following steps:
1. Select the IP group to be edited in the left panel of the IP Groups window. If
an IP group has been assigned to one or more hypervisors, the Hypervisor
field displays the hypervisors to which the IP group belongs.
2. Remove the IP group from the hypervisor. Click the remove link beside a
hypervisor in the Hypervisors field to remove the IP group from that
hypervisor. If the hypervisor is in maintenance mode and not started, you
can remove the IP group from a hypervisor. The remove option is
unavailable for started hypervisors.
Note: Hypervisors must have IP groups assigned to run in the cloud. If the
hypervisor is currently running in a cloud and not in maintenance mode,
you cannot remove the IP group from that hypervisor.
If the remove link is unavailable, then the hypervisor is in use. For more
information on stopping a hypervisor and putting it in maintenance mode,
see Administering hypervisors on page 187.
v Delete an IP group. To delete the IP group, you must first have removed it from
all hypervisors to which it was assigned. Active IP group resources cannot be
deleted. To delete the IP group, use the following steps:
1. Select the IP group to be deleted in the left panel of the IP Groups window.
2. Remove the IP group from hypervisors. Click the remove link beside any
hypervisors in the Hypervisors field. IP groups can only be removed from a
hypervisor if the hypervisor is in maintenance mode. If the hypervisor is not
in maintenance mode, you cannot remove the IP group. For more
information about the maintenance mode state, see Hypervisor states on
page 207.
3. Delete the IP group. Click the Delete icon on the top of the IP Groups
window.
Note: If the IP group is automatically defined from an OpenStack network,
the network is not actually deleted in OpenStack environment. If the network
still exists in your OpenStack environment, the IP group is listed again in the
SmartCloud Orchestrator user interface when the automatic synchronization
occurs. For more information about the OpenStack synchronization, see
Configuring OpenStack synchronization on page 146. For more information
about managing networks in OpenStack, see Configuring Networking on the
Compute Node in the OpenStack documentation.
What to do next
After you have removed the IP group or groups from your hypervisor, and the
other hypervisor configuration is complete, you can restart the hypervisor. If the
hypervisor still has an IP group, you can run the hypervisor in the cloud. For more
information about configuring hypervisors, see Administering hypervisors on
page 187.
Related reference:
IP command-line interface reference on page 834
You can work with IP addresses, using the IPs and IP objects on the SmartCloud
216 IBM SmartCloud Orchestrator 2.3: User's Guide
Orchestrator command-line interface.
IP group command-line interface reference on page 838
You can work with IP groups on the SmartCloud Orchestrator command-line
interface using the IPgroups and IPgroup objects and attributes.
IP groups REST API on page 977
You can use the representational state transfer (REST) application programming
interface (API) to manage IP groups.
IP addresses REST API on page 973
You can use the representational state transfer (REST) application programming
interface (API) to manage IP addresses.
Fields on the IP Groups user interface:
You can administer your IP groups and IP addresses within IP groups using the
fields on the IP Groups window of the SmartCloud Orchestrator user interface.
To work with IP groups and IP addresses within those IP groups on the
SmartCloud Orchestrator user interface you can use the IP Groups window. The
left panel of the IP Groups provides the following options to work with IP groups:
Add icon
Use the Add icon to define an IP group to add to SmartCloud Orchestrator.
Clicking Add opens a window in which you can define your new IP
group.
Search
Enter the name of an IP group in this field to search for it. You can use the
up and down arrow keys to sort through the listing of IP groups.
To work with an IP group, first select it from the list in the left panel of the IP
Groups window. Selecting an IP group shows the name of the IP group at the top
of the right panel and the following fields on the right panel.
Note: Some fields might not be available or valid depending on the type of the
hypervisor to which the IP group is assigned.
Version
Displays IPv4 or IPv6 as the version of the IP addresses specified when the
IP group was added.
Attention: Workloads that require IP caching must be deployed to cloud
groups with only IPv4 IP groups.
Description
An optional description of the IP group.
Obtain IP addresses from
Displays DHCP Server or IP Address Pool to specify from where the IP
group obtains the IP addresses available to the hypervisors.
Host name prefix
The prefix to be used in the deployed virtual machine host name. This
information is optional.
Computer name prefix
The prefix to be used in the computer name of the deployed virtual
machines. This information is optional.
Chapter 4. Administering 217
Workgroup
The Windows workgroup name to be used for the deployed virtual
machines. This information is optional and it is valid only for Windows
virtual machines.
Hypervisors
Provides a listing of the hypervisors to which the IP group is assigned. The
name of the hypervisor is a link that you can click to open the Hypervisors
window for that hypervisor. If the hypervisors are in maintenance mode
and not actively running in a cloud, the remove link is also available.
Clicking remove removes the IP group from the hypervisor.
For IP groups that obtain IP addresses from an IP address pool, also the following
fields are displayed in the right panel:
Subnet address
The subnet address for the IP addresses in the IP group. This information
is required when you are creating an IP group.
Netmask
The netmask address for the IP addresses in the IP group. This information
is required when you are creating an IPv4 IP group.
Gateway
The gateway address for the IP addresses in the IP group. This information
is required when you are creating an IP group.
Alternate gateway
The alternate gateway address for the IP addresses in the IP group. This
information is optional.
Primary DNS
The primary DNS for the IP addresses in the IP group. This information is
required when you are creating an IP group.
Secondary DNS
A secondary DNS address might have been provided when the IP group
was created. This information is optional.
DNS suffixes (in order)
A comma separated list of domain suffixes that should be added to the
network settings of the deployed virtual machines. For example:
ibm.com,us.ibm.com. This information is optional.
Domain name
The domain name to be used for the IP group network. This information is
optional.
Primary WINS address
The primary WINS address to be uses for the deployed virtual machines.
This information is optional and it is valid only for Windows virtual
machines.
Secondary WINS address
The secondary WINS address to be uses for the deployed virtual machines.
This information is optional and it is valid only for Windows virtual
machines.
IP Addresses
Provides a numerically sorted list of IP addresses that have been added to
the IP group. Hovering over a resolved host name of a defined IP address
218 IBM SmartCloud Orchestrator 2.3: User's Guide
displays either the IP address or user host name, whichever was used to
create the IP address. This shows how the IP was originally entered, and
therefore what is resolved.
Bold face text in the list of IP addresses also defines how the IP address
was added. The part of the line that is bold face is representative of the
way the IP address is added to the IP Group. For example:
v If the IP address is used when the IP address is added to the IP Group,
the IP address is bold face such as, 172.16.39.236 (esx-v4-039-
236.raleigh.ibm.com).
v If the host name is used when the IP address is added to the IP Group,
the host name is bold face such as, 172.16.39.236 (esx-v4-039-
236.raleigh.ibm.com).
To the left of each IP address is one of the following statuses:
Active The IP address is active.
Inactive
The IP address is not currently active
Locked
The IP address is locked so that it cannot be used. If the IP address
is locked with a correlation ID, then only users with that
correlation ID can use the IP address.
Unavailable
There is an error with the IP address and it is unavailable. Check
your access to the IP address.
The following functions are available to work with IP addresses:
Remove
The remove link is shown to the right of any IP addresses that are
inactive and can be removed.
show more or show less
The show more or show less toggle link controls the number of IP
addresses shown. The list shows either all of the IP addresses in
the IP group or only the first 4, numerically ordered, IP addresses.
Add range
Use the two entry boxes and the Add link to add strings of IP
addresses at a time. Entering the first IP address in the string in
the first box and the final IP address in the second box adds all IP
addresses, numerically, between the two addresses specified.
Add Host Names
You can add IP addresses as host names instead of the actual IP
addresses. Clicking Add Host Names provides an entry field in
which to enter the space-delimited list of host names. When a host
name is specified for an IP address, the host name resolves to the
IP address. However, what is entered is what is stored. Therefore,
if you enter the host name then the host name is stored and not
the IP address to which it resolves. If any of the host names
entered cannot be resolved to IP addresses, then a warning
message is shown beside any entry that cannot be resolved. If a
host name is resolved to an IP address but the IP address is not
valid for the specified subnet, then an error message is shown and
the host name is not added to the IP Group.
Chapter 4. Administering 219
Related tasks:
Administering cloud groups on page 184
In SmartCloud Orchestrator, a cloud group is identified by an availability zone in a
region of the related OpenStack environment.
Related reference:
Cloud group command-line interface reference on page 815
You can work with cloud groups using the SmartCloud Orchestrator command-line
interface.
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.
Before you begin
For more information about environment profiles, see Environment profiles
overview on page 221. For information about working with SmartCloud
Orchestrator catalog, see the following information:
v Chapter 5, Managing virtual images, on page 287, for information about
working with virtual images in the catalog.
v Managing script packages on page 234 for information about working with
script packages in the catalog.
About this task
To work with environment profiles, use either the user interface or the
command-line interface.
Procedure
v Use the user interface to work with environment profiles, as described in
Managing environment profiles in the user interface on page 222.
v Use the command-line interface to work with environment profiles, as described
in Environment profiles command-line interface reference on page 819.
Related concepts:
Environment profiles overview on page 221
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.
Related tasks:
Managing environment profiles in the user interface on page 222
You can manage environment profiles with the SmartCloud Orchestrator user
interface from the Environment Profiles window.
Related reference:
Environment profiles command-line interface reference on page 819
You can work with environment profiles on the SmartCloud Orchestrator
command-line interface.
Environment profiles REST API on page 962
You can use the representational state transfer (REST) application programming
interface (API) to manage environment profiles.
220 IBM SmartCloud Orchestrator 2.3: User's Guide
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 SmartCloud 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 SmartCloud 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 on page 220
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.
Managing environment profiles in the user interface on page 222
You can manage environment profiles with the SmartCloud Orchestrator user
interface from the Environment Profiles window.
Related reference:
Environment profiles command-line interface reference on page 819
You can work with environment profiles on the SmartCloud Orchestrator
command-line interface.
Environment profiles REST API on page 962
You can use the representational state transfer (REST) application programming
interface (API) to manage environment profiles.
Chapter 4. Administering 221
Managing environment profiles in the user interface
You can manage environment profiles with the SmartCloud 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. For more information about configuring cloud groups, see
Administering cloud groups on page 184. For more information about
configuring hypervisors, see Administering hypervisors on page 187.
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
SmartCloud Orchestrator user interface.
Procedure
1. Click 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 on page 223.
v Clone an existing environment profile for reuse with the information in
Cloning an environment profile on page 227.
v Edit an existing environment profile with the information in Editing an
environment profile on page 228.
Related concepts:
Environment profiles overview on page 221
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.
Related tasks:
Creating an environment profile on page 223
You can create an environment profile with the SmartCloud Orchestrator user
interface.
Cloning an environment profile on page 227
You can clone environment profiles that are created in SmartCloud 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.
Editing an environment profile on page 228
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.
Related reference:
Environment Profiles window fields on page 230
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.
222 IBM SmartCloud Orchestrator 2.3: User's Guide
Creating an environment profile:
You can create an environment profile with the SmartCloud 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. For more information about configuring cloud groups, see
Administering cloud groups on page 184. For more information about
configuring hypervisors, see Administering hypervisors on page 187.
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 add 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.
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 All
v Development
v Test
v Quality Assurance
v Performance
v 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 230.
4. Complete the configuration. Before the environment profile is ready to use, you
must provide additional configuration information in the following fields:
Chapter 4. Administering 223
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 SmartCloud Orchestrator or specified when the pattern is
being deployed. Use the following options:
Pattern deployer
To provide the IP address for a virtual machine at deployment,
you must also specify the following information for each part:
v Cloud group
v IP group
v Host name
v 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 SmartCloud Orchestrator at deployment.
IP Groups
If SmartCloud 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. SmartCloud 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.
224 IBM SmartCloud Orchestrator 2.3: User's Guide
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
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,
smartcloud.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=smartcloud,dc=company,dc=com
where Computers and ou1 are the organizational units created
under the Active Directory domain root, and smartcloud,
company, and com are derived from the domain name
smartcloud.company.com.
Windows key management service
Provide the following KMS server information to be used for KMS
client activation:
Chapter 4. Administering 225
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: SmartCloud 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 SmartCloud 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
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.
Related concepts:
Environment profiles overview on page 221
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.
Related tasks:
Cloning an environment profile on page 227
You can clone environment profiles that are created in SmartCloud 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.
Related reference:
226 IBM SmartCloud Orchestrator 2.3: User's Guide
Environment Profiles window fields on page 230
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.
Cloning an environment profile:
You can clone environment profiles that are created in SmartCloud 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. For more information about configuring cloud groups, see
Administering cloud groups on page 184. For more information about
configuring hypervisors, see Administering hypervisors on page 187.
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 230.
5. Edit the environment profile. You can edit the fields described in Editing an
environment profile on page 228.
Chapter 4. Administering 227
Results
When you have completed these steps, you have cloned and customized the
environment profile.
Related concepts:
Environment profiles overview on page 221
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.
Related tasks:
Creating an environment profile on page 223
You can create an environment profile with the SmartCloud Orchestrator user
interface.
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.
Related reference:
Environment Profiles window fields on page 230
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.
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 SmartCloud 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.
228 IBM SmartCloud Orchestrator 2.3: User's Guide
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:
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 SmartCloud Orchestrator.
IP Groups
If SmartCloud Orchestrator provides the IP address for a virtual
machine, you only specify the cloud group and IP group for the
pattern parts. SmartCloud 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.
Chapter 4. Administering 229
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.
Related concepts:
Environment profiles overview on page 221
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.
Related tasks:
Creating an environment profile on page 223
You can create an environment profile with the SmartCloud Orchestrator user
interface.
Cloning an environment profile on page 227
You can clone environment profiles that are created in SmartCloud 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.
Related reference:
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.
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 SmartCloud Orchestrator.
There are two interactive panels of the Environment Profiles window:
Left panel
The left panel provides the following function:
v The add icon to create new environment profiles
v A search function to locate existing environment profiles
v A list of environment profiles that have been created
230 IBM SmartCloud Orchestrator 2.3: User's Guide
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.
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:
Chapter 4. Administering 231
IP Groups
Indicates that the IP address is to be provided bySmartCloud
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 SmartCloud 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.
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:
232 IBM SmartCloud Orchestrator 2.3: User's Guide
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.
Related reference:
Fields on the Pattern Editor window on page 556
The SmartCloud 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.
Populating the catalog
The SmartCloud Orchestrator catalog contains the application templates, plug-ins,
reusable components, virtual images, virtual system patterns, script packages, and
add-ons that are used to build the virtual environment.
Before you begin
To add content to the catalog you must be assigned the catalogeditor role or the
admin role. To change the catalog content, you must explicitly be granted access to
the content that you want to modify or be assigned the admin role.
About this task
Use the following steps to manage and add content in the catalog.
Chapter 4. Administering 233
Procedure
1. Chapter 5, Managing virtual images, on page 287. Virtual images provide the
operating system and product binary files required to create a virtual system
instance.
2. Working with virtual system patterns on page 511. You can use a virtual
system pattern to describe the topology of a system that you want to deploy.
3. Managing script packages You can use script packages to customize the
behavior of parts by adding script packages to pattern topologies.
4. Managing add-ons on page 254 You can add user, disk and NIC parts to
your catalog and then edit them as parts on your patterns.
Results
After completing these steps, you have expanded the available catalog options to
build the virtual environment.
What to do next
Use the catalog content to create new virtual systems. For more information about
working with virtual system instances, see Managing virtual system instances on
page 562.
Managing script packages
You can use script packages to customize the behavior of parts in SmartCloud
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 SmartCloud Orchestrator and
used as input to create the script package. See Script packages overview on page
235 for more information about using script packages with SmartCloud
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 a script
package using a JSON object on page 250.
About this task
You can work with script packages with the user interface or the command-line
interface. Choose the interface with which to work.
For a description of the attributes of the script packages, refer to Script package
command-line interface reference on page 876.
Procedure
v Using script packages with the user interface on page 242, you can perform
the following tasks:
234 IBM SmartCloud Orchestrator 2.3: User's Guide
Add a script package. For information about adding a script package, see
Adding a script package on page 243.
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 247.
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 248.
v Using the command-line interface. You can work with script packages using the
command-line interface. For information about working with script packages on
the command-line interface, see Script package command-line interface
reference on page 876.
Results
When you have created a script package and associated it 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.
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 SmartCloud
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 4. Administering 235
(AUTOSTART=FALSE) to run a script before the server is started. For more information
about environment variables, see Script package environment variables on page
251.
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. Job Manager (version 7.0.0.x patterns only)
4. Administrative Agent (version 7.0.0.x patterns only)
5. Custom Nodes
6. IBM HTTP Server
7. 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 526.
When scripts are run by SmartCloud Orchestrator, the SmartCloud 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 251.
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.
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.
236 IBM SmartCloud Orchestrator 2.3: User's Guide
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 java.io import File
from java.lang import Boolean
from java.lang import String
from java.net import URL
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:
Chapter 4. Administering 237
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()
Related concepts:
Script packages overview on page 235
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.
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",
"ostype": "linux/unix",
"commandargs": "-lang jython -f /opt/tmp/configtrace/configure_trace.jy
$TRACE_SPEC",
"keys":
[
{
"scriptkey": "TRACE_SPEC",
"scriptvalue": "",
"scriptdefaultvalue": ""
238 IBM SmartCloud Orchestrator 2.3: User's Guide
}
]
}
]
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()
Related concepts:
Script packages overview on page 235
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.
Example script package to create a server:
This script creates an application server on all of the custom nodes in a
SmartCloud 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":
[
Chapter 4. Administering 239
{
"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()
Related concepts:
Script packages overview on page 235
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.
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
240 IBM SmartCloud Orchestrator 2.3: User's Guide
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
$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()
Related concepts:
Script packages overview on page 235
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.
Chapter 4. Administering 241
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 SmartCloud Orchestrator and
used as input to create the script package. See Script packages overview on page
235 for more information about using script packages with SmartCloud
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 a script
package using a JSON object on page 250.
About this task
You can use the user interface to work with script packages.
For a description of the attributes of the script packages, refer to Script package
command-line interface reference on page 876.
Procedure
1. Navigate to the Script Packages window by clicking Components -> 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 on page 243.
v Making a script package read-only. See Making script packages read-only
on page 246 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 247.
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 248.
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.
What to do next
To review and download a collection of script samples, see Sample Script Packages
for Workload Deployer
Related concepts:
242 IBM SmartCloud Orchestrator 2.3: User's Guide
Script packages overview on page 235
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.
Related reference:
Script package command-line interface reference on page 876
You can administer script packages using the SmartCloud Orchestrator
command-line interface.
Script package environment variables on page 251
When you are defining a script package to SmartCloud Orchestrator, there are a set
of supplied environment variables that can be used.
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 SmartCloud 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.
For a description of the attributes of the script packages, refer to Script package
command-line interface reference on page 876.
Procedure
1. From the upper left of the Script Packages window, click the add icon.
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 245
2. Enter the name of the script package. In the window that displays, enter the
name of the script package to create and click OK. 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 a script package using a JSON
object on page 250 for more information about configuring a script package
using a JSON object.
Chapter 4. Administering 243
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 SmartCloud
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. SmartCloud Orchestrator
supplies a set of environment entries for you.
See Script package environment variables on page 251 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 SmartCloud
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
SmartCloud 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
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 235 for
more information about when script packages are run.
244 IBM SmartCloud Orchestrator 2.3: User's Guide
at virtual system instance creation
This option specifies that the script is run when the virtual
system has finished starting during the initial creation.
at virtual system instance deletion
This option 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 on page 511 for more
information about patterns.
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.
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. See Working with
virtual system patterns on page 511 for more information about patterns.
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.
Chapter 4. Administering 245
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 on page 511 for more information about patterns.
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
246 IBM SmartCloud Orchestrator 2.3: User's Guide
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 on page 511 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 the script package before you can associate it with a pattern. The
script package must also be configured in the Script Packages window of the user
interface or using the command-line interface of SmartCloud Orchestrator. For
more information about configuring the script package with the user interface, see
Adding a script package on page 243.
About this task
Use this task to associate a script package with a pattern.
Procedure
1. Navigate to the Virtual System Patterns window by clicking Images & Patterns
> Virtual System Patterns.
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 editing views and parts on page 522 topic. Basic
information about the selected pattern displays in the right panel of the Virtual
System Patterns view.
3. Edit the pattern. Click the edit icon on the upper right of the Virtual System
Patterns window to edit the pattern. The pattern topology displays in the lower
right panel.
4. Select Scripts. From the drop-down box in the left panel of the Pattern Editor,
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
SmartCloud Orchestrator. Script packages can then be added to the virtual
image parts.
Chapter 4. Administering 247
5. Add a script package. Any script packages you have defined to SmartCloud
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 253
Results
You have added one or more script packages to the virtual images on the pattern.
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 SmartCloud Orchestrator user interface.
248 IBM SmartCloud Orchestrator 2.3: User's Guide
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 SmartCloud Orchestrator. To use it with
SmartCloud Orchestrator again, you must add it again.
Windows sample to check if a file already exists:
This topic provides a sample script that checks if a file already exists on Windows.
@echo off
goto :primo
:error
@echo off
call :setError
echo %errorlevel%
goto :eof
:setError
Exit /B 5
:primo
If not exist ciccio.txt goto :error
Echo If we get this far the file ciccio was found
Chapter 4. Administering 249
Configuring a script package using a JSON object
A special JSON object, cbscript.json can be used to populate all the information
needed to configure a script package when it is added to the catalog.
Overview
When you add a new script package to the catalog, you can include the
configuration information in the compressed file (.zip files and .tgz files are
supported) that is uploaded using a special JSON object. The JSON object must be
named cbscript.json and be included at the root of the compressed file that is
uploaded. Including a cbscript.json file in your script package is useful when
sharing scripts. An additional benefit is gained in limiting typographical errors as
the information only needed to be entered once because the default values are
pre-populated with the information in the cbscript.json file.
Note: You must provide a formatted JSON content in the cbscript.json file in
addition to following the JSON specification. For example, you must make sure it
always puts a carriage return after a JSON attribute:value entry, and avoid
multiple quoted sets on a single line.
Note: To better understand the meaning of the parameters in the JSON file, refer
to Script package command-line interface reference on page 876.
Example of cbscript.json file
[
{
"name": "MyScriptPackage",
"version": "1.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": ""
}
]
}
]
250 IBM SmartCloud Orchestrator 2.3: User's Guide
Script package environment variables
When you are defining a script package to SmartCloud Orchestrator, there are a set
of supplied environment variables that can be used.
Purpose of environment variables
You can use the environment variables provided by SmartCloud Orchestrator for
defining script packages. Environment variables are provided through the virtual
image and after deployment are located on each virtual machine at
/etc/virtualimage.properties (on Linux) and at \windows\setup\ibm\
virtualiamge.properties on Windows. The set of environment variables that are
available is determined by what environment variables exist on the virtual
machine.
Specify these environment variables in one of the following ways:
v In the user interface, specify the environment variables in the Environment field
of the Script Packages window. For more information about adding an
environment variable in the Script Packages window, see Adding a script
package on page 243.
v In the command-line interface, specify the environment variables environment
attribute of the script object. For more information about adding an environment
variable with the script object, see Script package command-line interface
reference on page 876.
You can use environment variables to define your script packages for use with
pattern topologies. For more information about pattern topologies, see Working
with virtual system patterns on page 511.
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"
Chapter 4. Administering 251
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 exist and 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"
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 Install Root
WAS_INSTALL_ROOT=/opt/IBM/WebSphere/AppServer
WebSphere Install Root
PROFILE_ROOT=/opt/IBM/WebSphere/Profiles
WebSphere Install Root
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
252 IBM SmartCloud Orchestrator 2.3: User's Guide
These two variables are dynamic. SmartCloud 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
Related concepts:
Script packages overview on page 235
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.
Related tasks:
Associating a script package with a pattern on page 247
You can associate a script package with a pattern and defined cell through the user
interface.
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
SmartCloud 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
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 ipaddr
v netmask
v gateway
v pri_dns
v sec_dns
Note: If you want to set the hostname variable for the Windows system,
consider that there is the following limitation: Setting the host name when
deploying a Windows system on page 1100
Locale-oriented variables
Chapter 4. Administering 253
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 247
You can associate a script package with a pattern and defined cell through the user
interface.
Working with virtual system patterns on page 511
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.
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
255.
About this task
Use one of the following methods to work with add-ons in the catalog.
Procedure
v Using the user interface. See the information in Managing add-ons with the
user interface on page 257 to perform the following tasks:
Adding add-ons to the catalog on page 258
Cloning an add-on on page 259
Deleting an add-on on page 264
v Using the command-line interface. You can work with add-ons using the
command-line interface. See AddOn command-line interface reference on page
810 for more information.
Results
After completing these steps you have an understanding of how to work with
add-ons in the catalog.
What to do next
After you have created or edited an add-on then you can add it as a part to a
pattern.
Related tasks:
254 IBM SmartCloud Orchestrator 2.3: User's Guide
Populating the catalog on page 233
The SmartCloud Orchestrator catalog contains the application templates, plug-ins,
reusable components, virtual images, virtual system patterns, script packages, and
add-ons that are used to build the virtual environment.
Chapter 5, Managing virtual images, on page 287
Virtual images provide the operating system and product binary files that are
required to create a virtual system instance.
Managing script packages on page 234
You can use script packages to customize the behavior of parts in SmartCloud
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.
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 Catalog >
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.
Chapter 4. Administering 255
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 RedHat 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.
Note: When using this add on for images to be deployed on VMware,
consider that SmartCloud Entry has a default configuration concerning the
maximum number of disks and their size. You can change the default
configuration, editing, on the system where SmartCloud Entry runs,
/root/.SCE/31/deployment.properties, modify com.ibm.cfs.vs.max.disks
and com.ibm.cfs.vs.max.disksize according to your needs and restart
SmartCloud Entry.
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: SmartCloud 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
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: When using this add on for images to be deployed on VMware,
consider that SmartCloud Entry has a default configuration concerning the
maximum number of disks and their size. You can change the default
configuration, editing, on the system where SmartCloud Entry runs,
/root/.SCE/31/deployment.properties, modify com.ibm.cfs.vs.max.disks
and com.ibm.cfs.vs.max.disksize according to your needs and restart
SmartCloud Entry.
Note: SmartCloud 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.
256 IBM SmartCloud Orchestrator 2.3: User's Guide
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 Components > Add-Ons from
the menu bar.
2. You can perform the following tasks:
v Adding add-ons to the catalog on page 258
v Cloning an add-on on page 259
v Editing an add-on on page 261
v Making add-ons read-only on page 262
v Associating an add-on with a pattern on page 263
v Deleting an add-on on page 264
For more information about the fields on the Add-Ons window, see Fields on
the Add-Ons user interface on page 265.
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 527. For more
information about working with patterns, see Working with virtual system
patterns in the user interface on page 513. If you are working with a NIC add-on,
it can be configured with an environment profile. See Managing environment
profiles on page 220 for more information.
Related concepts:
Add-ons in the catalog on page 255
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.
Related tasks:
Chapter 4. Administering 257
Populating the catalog on page 233
The SmartCloud Orchestrator catalog contains the application templates, plug-ins,
reusable components, virtual images, virtual system patterns, script packages, and
add-ons that are used to build the virtual environment.
Related reference:
Fields on the Add-Ons user interface on page 265
You can manage the add-ons in your catalog using the fields on the Add-Ons
window of the SmartCloud Orchestrator user interface.
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 259. 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 the add icon to add an
Add-On to the catalog.
2. Enter a name for the add-on. This field is used as the identifier for the new
add-on you are adding to the catalog.
3. Select the type of add-on. Add-ons can be one of the following types:
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.
4. Click OK. The right panel of the Add-Ons window shows additional fields
that are required to define the new add-on.
5. Optional: Add a description to help identify the add-on.
6. Optional: In the Add-on package files section, provide the customized add-on
package file with the Browse field and the Upload button.
7. Optional: Use the Environment section to add environment variables.
8. Optional: Specify the standard script package parameters for the following
directories:
v Working
v Logging
v Executable
v Arguments
9. Optional: Set a timeout value in the Timeout field.
258 IBM SmartCloud Orchestrator 2.3: User's Guide
10. 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.
Related concepts:
Add-ons in the catalog on page 255
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.
Related tasks:
Managing add-ons on page 254
You can configure user and NIC parts in your catalog and then use them as parts
in your patterns.
Working with virtual system patterns on page 511
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.
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
Chapter 4. Administering 259
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
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 on page 511 for more information about patterns.
Related concepts:
Add-ons in the catalog on page 255
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.
Related tasks:
Adding add-ons to the catalog on page 258
You can add new add-ons in addition to the add-ons already included in the
product.
Deleting an add-on on page 264
You can manually delete an add-on, disassociating it with the pattern and cell,
using the user interface.
260 IBM SmartCloud Orchestrator 2.3: User's Guide
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 265.
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 262. You can add the add-on to a part on a pattern.
For more information, see Working with virtual system patterns on page 511.
Related concepts:
Add-ons in the catalog on page 255
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.
Related tasks:
Populating the catalog on page 233
The SmartCloud Orchestrator catalog contains the application templates, plug-ins,
reusable components, virtual images, virtual system patterns, script packages, and
add-ons that are used to build the virtual environment.
Adding add-ons to the catalog on page 258
You can add new add-ons in addition to the add-ons already included in the
product.
Related reference:
Chapter 4. Administering 261
Fields on the Add-Ons user interface on page 265
You can manage the add-ons in your catalog using the fields on the Add-Ons
window of the SmartCloud Orchestrator user interface.
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 on page 511.
Related concepts:
Add-ons in the catalog on page 255
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.
Related tasks:
Editing an add-on on page 261
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.
262 IBM SmartCloud Orchestrator 2.3: User's Guide
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 in the Add-Ons window of the user interface or
using the command-line interface of SmartCloud Orchestrator. For more
information about configuring the add-on with the user interface, see Editing an
add-on on page 261.
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 Images & Patterns
> Virtual System Patterns.
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. For more information about patterns and editing them, see Virtual
system pattern editing views and parts on page 522. Basic information about
the selected pattern displays in the right panel of the Virtual System Patterns
view.
3. Edit the pattern. Click the edit icon on the upper right of the Virtual System
Patterns window to edit the pattern. The pattern topology displays in the lower
right panel.
4. Select Add-Ons. 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 SmartCloud
Orchestrator. Add-ons can then be added to the virtual image parts.
5. Add an add-on. Any add-ons defined to SmartCloud Orchestrator are available
in the list of add-ons on the left panel of the Virtual System Patterns view. 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.
6. 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. 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 253.
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.
Related concepts:
Chapter 4. Administering 263
Add-ons in the catalog on page 255
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.
Related tasks:
Adding add-ons to the catalog on page 258
You can add new add-ons in addition to the add-ons already included in the
product.
Deleting an add-on
You can manually delete an add-on, disassociating it with the pattern and cell,
using the user interface.
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 SmartCloud Orchestrator user interface.
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.
264 IBM SmartCloud Orchestrator 2.3: User's Guide
Results
The add-on is deleted from SmartCloud Orchestrator. To use it with SmartCloud
Orchestrator again, you must add it again.
Related concepts:
Add-ons in the catalog on page 255
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.
Related tasks:
Adding add-ons to the catalog on page 258
You can add new add-ons in addition to the add-ons already included in the
product.
Cloning an add-on on page 259
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.
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 SmartCloud Orchestrator user interface.
To work with add-ons with the SmartCloud 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:
Add Use the Add icon to define an add-on. Clicking Add opens 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.
Sort Click to sort the list of add-ons. You can sort by the following attributes:
v Sort by name
v Sort by status
v Sort by ID
v Sort by type
List of add-ons
The listing of add-ons contains the default add-ons that are already defined
to SmartCloud Orchestrator, by name.
To work with an add-on, first select it from the list in the left panel of the Add-Ons
window.
Icons on the upper right
The upper right of the Add-Ons window provides the following icons:
Chapter 4. Administering 265
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 SmartCloud 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 262.
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.
Default add disk
Download the defaultadddisk.zip package.
Default AIX add disk
Download the defaultaixadddisk.zip package.
266 IBM SmartCloud Orchestrator 2.3: User's Guide
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
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
Chapter 4. Administering 267
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.
Related tasks:
Adding add-ons to the catalog on page 258
You can add new add-ons in addition to the add-ons already included in the
product.
Editing an add-on on page 261
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.
Managing key pairs
Manage pairs of SSH private and public keys in your environment to access
deployed virtual machines.
About this task
Key pairs are needed to access the virtual machines that you deploy in a pattern.
When you deploy a virtual machine, these keys are injected into the instance to
allow password-less SSH access to the instance.
Important: SSH key pairs are supported only for KVM hypervisors.
By default, SmartCloud Orchestrator uses the key pair named default, if it is
defined in the OpenStack region in which you are deploying the virtual machine.
If a default key pair is not defined, SmartCloud Orchestrator uses a key pair only
if just one key pair is defined in the OpenStack region in which you are deploying
the virtual machine.
To add a new key pair in your environment, perform the following steps:
Procedure
1. From the menu bar, select Components > Keypairs. The Keypairs window is
displayed.
2. Click the Add icon.
3. In the displayed panel, specify a Name and select the OpenStack Region in
which you want to generate the key pair.
4. Choose one of the following options:
v To generate a new pair of public and private keys, perform the following
steps:
a. Ensure Generate a new keypair is selected.
b. Click Generate Keypair. A new key pair is generated in the OpenStack
region.
Important: Save the private key on your system before you close the
dialog. You cannot retrieve the private key later.
c. Click Close.
v To import an existing public key, perform the following steps:
a. Select Import the public key of an existing key pair.
b. Enter the Public Key that you want to import.
c. Click Import Keypair. The key pair is added to the OpenStack region.
268 IBM SmartCloud Orchestrator 2.3: User's Guide
Results
The key pair is now available to access the virtual machines that you deployed in
the OpenStack region.
You can delete a key pair that you do not need any more by selecting the key pair
in the Keypairs window and clicking the Delete icon.
Monitoring the task queue
SmartCloud Orchestrator provides a task queue to display tasks. The tasks can
include currently running and tasks that are schedule to run in the future.
Before you begin
You must be assigned the admin role to perform these steps.
About this task
Procedure
1. Open the task queue. From the menu bar on top of the SmartCloud
Orchestrator user interface, click Administration > Task Queue.
2. View all running tasks and the tasks scheduled to run in the future. The
following types of tasks are displayed in the task queue.
v Creating a virtual system instance
v Deleting a virtual system instance
v Stopping a virtual system instance
v Starting a virtual system instance
v Storing a virtual system instance
v Applying service to a virtual system instance
v Adding a virtual image
v Deleting a virtual image
v Importing a virtual image
v Exporting a virtual image
3. Click the remove icon next to a task to remove that task from the task queue.
Most tasks are only made up of a single stage, but creating a virtual system
instance is a multiple stage task. If you remove this type of task before it has
finished, then the incomplete virtual system instance must be removed. See
Removing a virtual system instance on page 567 for more information about
removing a virtual system instance.
Results
After completing these steps, you have reviewed the tasks that are currently
running and the tasks scheduled for the future.
Related tasks:
Managing virtual system instances on page 562
A virtual system instances is the virtual environment that is being managed by
your SmartCloud Orchestrator.
Related information:
Chapter 5, Managing virtual images, on page 287
Virtual images provide the operating system and product binary files that are
Chapter 4. Administering 269
required to create a virtual system instance.
Auditing
SmartCloud 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; SmartCloud
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
v and more
For each event, the collected information identifies the user who initiated the
operation, and whether it succeeded. SmartCloud Orchestrator makes this audit
data available for download in the form of event records.
See Audit events on page 271 for a complete list of tracked events.
Note: Auditing for creation or deletion of users, projects, and domains is not
supported.
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 SmartCloud 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 272.
270 IBM SmartCloud Orchestrator 2.3: User's Guide
Working with the event log
The SmartCloud Orchestrator event log stores the event records that contain audit
data. To download the records, you can use any of the following interfaces:
v User interface
v Command-line interface
v Direct calls to the REST API - Note that for working with this API, SmartCloud
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 277 for more information
about using these interfaces to download audit data.
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, SmartCloud Orchestrator suspends the auditing function
until storage frees up. You can use the user interface to monitor storage
consumption of the auditing function. When consumption nears 90%, clean the
audit log storage. See Deleting audit data to free storage on page 284 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.
Audit events
With the SmartCloud 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. This reference
article lists the events about which the product generates audit data.
Table 1 organizes the audit events in two broad categories, as indicated by the
column headings.
Table 22. Events that are tracked by audit data
User activity on the product User activity on cloud objects and data
Every occurrence of product startup and shutdown
per user
Security violation
Success or failure of login attempts Data deletion
Every user permission assignment Success or failure of attempts to access a security file or protected resource (To provide
context about these attempts, SmartCloud Orchestrator includes a list of protected resources
and users who can access them.)
Configuration changes Process invocation
Session timeout Session timeout
Backup profile
(creation, deletion or update)
Virtual system instance
(creation, deletion or update)
Virtual machine
(creation, deletion or update)
Task
(addition, deletion or update)
Hypervisor
(addition, deletion or update)
IP
(creation, deletion or update)
IP group
(creation, deletion or update)
Chapter 4. Administering 271
Table 22. Events that are tracked by audit data (continued)
User activity on the product User activity on cloud objects and data
Storage device
(addition, deletion or update)
Network interfaces
(addition, deletion or update)
Pattern
(creation, deletion or update)
Virtual image
(creation, deletion or update)
Disk image
(addition, deletion or update)
Script package
(creation, deletion or update)
Event records
SmartCloud Orchestrator collects audit data about each of the previously listed
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, consult the article Audit event record attributes and usage tips.
Related tasks:
Retrieving audit data with the user interface on page 278
The user interface provides two options to retrieve 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
SmartCloud Orchestrator logged those records. This article provides instructions
for both download options.
Retrieving audit data with the REST API on page 279
For retrieving audit event records with the REST API, SmartCloud 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.
Related reference:
Audit logging command-line interface reference on page 813
This topic provides a reference for collecting your audit reports using the
command-line interface tool.
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 SmartCloud 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
followed by attribute name-value pairs that can vary from record to record. Table 2
in the section "Attribute name-value pairs" lists the pairs that you can use in your
analysis of cloud activity.
272 IBM SmartCloud Orchestrator 2.3: User's Guide
Example: The following example depicts a short, but still typical, event record. The
first line (from 3.1.0.0 to 127.0.0.1) is comprised of values for the eight attributes
that are common to all records. The subsequent lines consist of attribute
name-value pairs.
3.1.0.0,2011-11-11 02:43:11.011 UTC,user,login,1,Administrator,{system},127.0.0.1,
event_component_type=user,event_action_parms=null,
event_correlator_id=8a784fdb-dc37-4de7-b8a4-06a7118aa1e2,event_request_method=login,
username=cbadmin,event_request_uri=Administrator,event_message_id=null,
event_user_name={system},email=null,isinternal=0,event_message_parms=null,
currentstatus=RM01062,currentmessage=RM02013,event_timestamp=2011-11-11 02:43:11.67,
deploymentoptions=0,uuid=u-0
Note: In the event records you might see cbadmin as user ID because this is a
built-in internal user of the product.
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 23. Universal event record attributes
Order of appearance in record Attribute Definition
1 Product version Version of the SmartCloud Orchestrator product
2 Timestamp Time (in UTC time zone) when the event record was generated
3 Resource type Type of resource on which an action was attempted
4 Action Action that was attempted on the specified resource
5 Resource ID Resource instance number
6 Resource name Name of the specified resource instance
7 User Who attempted to perform the specified action
8 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 SmartCloud
Orchestrator.
Table 24. 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
Chapter 4. Administering 273
Table 24. Attribute name-value pairs (continued)
Attribute name Data value example Description
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.
event_authz_header [{"attributes":
"{\"authorizationAttributes\":
. . . }
| {"attributes":
"{\"authorizationAttributes\":
. . . }]
Values for the event_authz_header
attribute can include multiple
elements, which are security
tokens in the form of JSON objects.
Thus, to accommodate the CSV
format of the overall record,
multiple tokens within this
attribute value are separated by
vertical bars (|) rather than
commas.
Note that the objects in this
particular data value example are
abbreviated. See the "Security
token format" section that follows
this table for a complete example
of a token.
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.)
v Each subsequent token represents an intermediate
server that relayed the request on behalf of the
original caller. These tokens are endorsement security
tokens, or endorsement tokens.
v Altogether, the caller token and endorsement
tokens of a multi-token stack represent the path
that a request travelled to reach a resource.
Note: The last security token in the stack
represents the most recent endorsement server,
which can assert additional security roles, if
necessary, when making downstream request
invocations.
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 172.16.65.4_172.16.65.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.
274 IBM SmartCloud Orchestrator 2.3: User's Guide
Table 24. Attribute name-value pairs (continued)
Attribute name Data value example Description
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 SmartCloud
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.)
{ "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 -
Chapter 4. Administering 275
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:
/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 strategize other ways to use the rich
audit data that SmartCloud Orchestrator provides to protect your environment
and, consequently, your business data.
Related tasks:
Retrieving audit data with the user interface on page 278
The user interface provides two options to retrieve 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
SmartCloud Orchestrator logged those records. This article provides instructions
for both download options.
Retrieving audit data with the REST API on page 279
For retrieving audit event records with the REST API, SmartCloud 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.
Related reference:
Audit logging command-line interface reference on page 813
This topic provides a reference for collecting your audit reports using the
command-line interface tool.
276 IBM SmartCloud Orchestrator 2.3: User's Guide
Download options for audit event records
You have three choices of interface for downloading audit event records: the user
interface, command-line interface (CLI), and the REST API. All of these options
provide the records that you request in comma-separated value (CSV) format
(wherein the attribute values of each record are separated by commas). However,
the packaging of the records differs according to your choice of download option.
What is more, the user interface and CLI options return your requested records
along with additional content. Use this article to understand the differences among
the file sets that each download option provides.
File names
With the REST API and CLI download options, you can specify the name of the
.zip file to which your records are written for the download operation. However,
with the user interface, you cannot specify a file name. You automatically receive
your records in a file named audit.zip.
Additional files and content
If you use either the user interface or CLI to download event records, you receive
two additional files that you do not receive when you use the REST API download
option. You can see the names of those additional files in column 2 of Table 1. (Use
the links in column 3 of the table to reach instructions on how to use each interface
to download event records.)
Table 25. Download options for audit data
Download option Files that you receive Link to download instructions
User interface audit.zip, which contains:
v license-audit.csv - Currently not supported.
v pvu-audit.csv - Currently not supported.
v audit-events.zip - This file contains four files: another .zip file of the event records that
you request, as well as three other files. All four file names are:
audit-events.csv - This file contains the audit event records that you specified, in
CSV format.
audit-events-signed-events-checksum - Contains the digital signature that verifies
both the integrity and authenticity of your audit data.
audit-events-record-IDs
audit-events-signed-record-IDs
Retrieving audit data with the
user interface on page 278
CLI XXX.zip, where XXX is a name that you specify by parameter. This .zip file contains:
v license-audit.csv - Currently not supported.
v pvu-audit.csv - Currently not supported.
v audit-events.zip - This file contains four files: another .zip file of the event records that
you request, as well as three other files. All four file names are:
audit-events.csv - This file contains the audit event records that you specified, in
CSV format.
audit-events-signed-events-checksum - Contains the digital signature that verifies
both the integrity and authenticity of your audit data.
audit-events-record-IDs
audit-events-signed-record-IDs
Audit logging command-line
interface reference on page 813
REST API XXX.zip, where XXX is a name that you specify by parameter. This .zip file contains:
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 on page 279
Note: For working with the REST
API, SmartCloud Orchestrator
provides sample scripts that you
can customize and run with a job
scheduler to automate download of
audit data on a regular basis.
Chapter 4. Administering 277
Retrieving audit data with the user interface
The user interface provides two options to retrieve 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
SmartCloud Orchestrator logged those records. This article provides instructions
for both download options.
Before you begin
You must be assigned the admin role to perform these steps.
Procedure
1. Navigate to Administration > Auditing and expand Download. Note that this
section is divided into two subsections:
v Download all data, in which you specify only the maximum number of
event records that you want to retrieve.
v Download filtered data, in which you specify both a time frame filter and
the number of records that you want to retrieve.
Proceed to either Step 2 or Step 3, according to the download option that you
prefer.
2. To specify a maximum number of records and download them:
a. Type the number of records that you want to retrieve in the Maximum
event log size field. You can specify up to 20,000 records. If you type a
greater value in the field, the product automatically adheres to the
maximum of 20,000 and writes 20,000 records to the .zip file that you
download.
b. Click Download.
3. To specify a time frame for the records that you want to retrieve:
a. Adjust the start and end dates. The default date range is to include data
from the last 30 days.
About time zone: The selections within the Time zone list are currently
inactive. When you specify a date and time range for downloading your
audit data, those date and time values are automatically defined with the
time zone of the Workload Deployer machine. You cannot refine your date
and time selections with a different time zone. Additionally, be aware that
every audit event record that you download has a UTC timestamp.
b. Type the number of records that you want to retrieve in the Maximum
event log size field. You can specify up to 20,000 records. If you type a
greater value in the field, the product automatically adheres to the
maximum of 20,000 and writes 20,000 records to the .zip file that you
download.
c. Click Download.
Results
Regardless of which data retrieval option you chose, you have now downloaded
the file audit.zip, which 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:
278 IBM SmartCloud Orchestrator 2.3: User's Guide
audit-events.csv - This file contains the audit event records that you just
specified for download via the user interface.
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 when deleting your
event records from the Workload Deployer machine. See Deleting audit data
to free storage on page 284, for more information.
What to do next
Because SmartCloud 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. See Deleting audit
data to free storage on page 284 for information about auditDelete.sh.
Related reference:
Audit events on page 271
With the SmartCloud 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. This reference
article lists the events about which the product generates audit data.
Audit event record attributes and usage tips on page 272
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 SmartCloud Orchestrator
environment.
Retrieving audit data with the REST API
For retrieving audit event records with the REST API, SmartCloud 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 You must follow the procedure described in Downloading and configuring the
command-line interface on page 909. All of the scripts are located in CLI
directories.
v You must have the admin role in SmartCloud Orchestrator.
You also might want to review general information about the REST API in the
article REST API reference on page 940. For this particular procedure, you need
to understand that invocation of the API is accomplished through HTTP requests.
Chapter 4. Administering 279
Tip: If you want to create your own scripts for retrieving audit data, consult the
reference article Auditing REST API on page 950 for the syntax to use in your
HTTP requests. You can browse this procedure and the sample scripts for an
understanding of how your code must integrate the fundamental tasks
(authenticating with the REST API, issuing the HTTP requests, and specifying a
.zip file for the returned data).
About this task
Table 1 lists the sample scripts that you can use to download the .zip file of audit
data and decompress it. The following procedure steps provide guidelines for
using the scripts.
Table 26. 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 SmartCloud 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:
v Runs the create_basicauth_header.py script to create the
authentication header.
v Issues a Curl command to SmartCloud Orchestrator with the
authentication header to authenticate your credentials. The
Curl command targets the URL of the SmartCloud
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.
...\deployer.cli-XXX\deployer.cli\lib\XXX\
deployer, where XXX is the version number of
the CLI
auditFetch.sh This sample script provides a very simple demonstration of how
you can automate the entire process, and thus adopt it as another
job that you run regularly in your IT organization.
...\deployer.cli-XXX\deployer.cli\samples,
where XXX is the version number of the CLI
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 decompress 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 decompress 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 SmartCloud 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
SmartCloud 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/.
280 IBM SmartCloud Orchestrator 2.3: User's Guide
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 SmartCloud Orchestrator to the name that is used in the root certificate,
IBMWorkloadDeployer.
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 SmartCloud
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 SmartCloud 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
Chapter 4. Administering 281
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.
7. Decompress 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 SmartCloud 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 SmartCloud 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 Decompresses 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.
282 IBM SmartCloud Orchestrator 2.3: User's Guide
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.
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 SmartCloud 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 on page 284 for information about auditDelete.sh.
Monitoring the status of audit data storage
In the SmartCloud Orchestrator user interface, you can view the usage levels of
storage resources that are dedicated to logging audit data. Use this information to
determine when to delete audit event records from the Workload Deployer
machine, in order to free up storage and maintain the regular audit data logging
process.
Before you begin
v You need to understand the following terms, which are specific to SmartCloud
Orchestrator auditing:
Event record refers to a record that contains audit data for a security or
administrative event. One record corresponds with each event.
Event log refers to SmartCloud Orchestrator storage that is dedicated to
archiving audit data.
v Also understand that when audit data storage reaches a pre-set capacity limit on
the Workload Deployer machine, SmartCloud 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.
v You must have the admin role to view the status of audit data storage in the
user interface.
Procedure
1. Go to Administration > Auditing.
2. Expand General Status. Note the read-only field Maximum event log size. The
value of 2500000 records is the maximum number of event records that can be
stored in the event log at any given time.
3. Check the Current event log utilization field. It displays the percentage of the
event log that is currently used to store event records. When that percentage
approaches 90%, you need to clean the event log. See the article Deleting audit
Chapter 4. Administering 283
data to free storage for more information about deleting event records from
the Workload Deployer machine.
Important: When the Current event log utilization value exceeds 90%, you see
display of the following text: Continue operation with event auditing temporarily
disabled. This message indicates that SmartCloud Orchestrator has suspended
collection of audit data until storage frees up. Normal operation of the rest of
the product, of course, continues.
Deleting audit data to free storage
To help safeguard your auditing processes, SmartCloud 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 SmartCloud 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,
SmartCloud 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 Downloading and configuring the command-line interface on page 909 (CLI).
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.
Procedure
1. Locate the auditDelete.sh script in the samples library of the SmartCloud
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.
284 IBM SmartCloud Orchestrator 2.3: User's Guide
2. Download your SmartCloud 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.
What to do next
Review the article Audit event record attributes and usage tips on page 272 for
an understanding of how you can best exploit SmartCloud Orchestrator event
records in your auditing analyses.
Chapter 4. Administering 285
286 IBM SmartCloud Orchestrator 2.3: User's Guide
Chapter 5. Managing virtual images
Virtual images provide the operating system and product binary files that are
required to create a virtual system instance.
SmartCloud Orchestrator supports virtual images that contains the scp-cloud-init
script and the Activation Engine. SmartCloud Orchestrator also supports virtual
images that run on VMware, if the images contain the Activation Engine and the
VMware tools are installed. Use the Image Construction and Composition Tool to
create images that are supported by SmartCloud Orchestrator. For more
information, see Working with IBM Image Construction and Composition Tool
on page 387.
To view a virtual image, you must be granted access to the virtual image or
assigned the admin role. For more information, see User roles in SmartCloud
Orchestrator on page 151.
Before working with a virtual image in SmartCloud Orchestrator, you must
perform one of the following tasks:
v Importing the virtual image by following the procedure described in Importing
a virtual image to the catalog on page 289.
v Registering the virtual image by following the procedure described in
Registering a virtual image on page 290. To register an image to SmartCloud
Orchestrator, the image must be available in your OpenStack environment. If
you are using a VMware hypervisor, the images are automatically discovered in
your OpenStack environment when the vCenter connection is established. If you
are using a KVM hypervisor, you must register the image to your OpenStack
environment by following the procedure described in Adding images to
OpenStack on page 294.
You can use the user interface, the command-line interface, the REST API, or the
IBM Image Construction and Composition Tool to manage your virtual images.
For more information, see:
v Managing virtual images with the user interface on page 288
v Virtual images command-line interface reference on page 893
v Virtual images REST API on page 1019
v Working with IBM Image Construction and Composition Tool on page 387
You can also perform advanced image management tasks by using the Virtual
Image Library user interface. For more information, see Working with Virtual
Image Library on page 295.
After working with the virtual images, you can manage the patterns associated
with them. For more information, see Working with virtual system patterns on
page 511.
Copyright IBM Corp. 2013, 2014 287
Managing virtual images with the user interface
You can work with virtual images, to provide the operating system and product
binary files that are required to create a virtual system instance, with the user
interface.
Before you begin
To view a virtual image, you must explicitly be granted access to the virtual image
or be assigned the admin role. See User roles in SmartCloud Orchestrator on
page 151, for more information about user roles.
About this task
Use the following steps to manage your virtual images.
Procedure
1. To display a list of all the virtual images that you are authorized to manage,
From the menu bar in the SmartCloud Orchestrator user interface, click Images
& Patterns > Virtual Images.
2. Click the <virtual_image_name> of a virtual image to select the virtual image
you want to view or modify. If this is the first time you are viewing a virtual
image, you must accept the license. With some images, multiple license options
are available. This allows you to account for operating system licenses that you
have already purchased.
Tip: Because patterns are associated with virtual images, you might have to
accept a license before you can clone a pattern associated with that image. If
you accept a license that you do not intend to use to clone the pattern, and you
change the cloned pattern to use another image, you are not charged for the
license usage. See Cloning an existing virtual system pattern on page 517 for
more information.
Results
After completing these steps, you can start performing all the virtual image
management tasks. To perform advanced image management tasks, you can launch
the Virtual Image Library user interface by clicking Images & Patterns > Virtual
Image Library in the menu bar.
For more information on how to manage the patterns associated with the virtual
images, see Working with virtual system patterns on page 511.
Related tasks:
Importing an image on page 321
Import a local virtual image into the reference repository to perform image
management operations on the imported image.
Related reference:
Virtual image fields on the user interface on page 292
This topic provides a reference for the fields associated with a virtual image.
288 IBM SmartCloud Orchestrator 2.3: User's Guide
Importing a virtual image to the catalog
Import virtual images to the catalog to use them in a pattern.
Before you begin
You must be assigned the catalogeditor role or the admin role to perform these
steps.
Note: The images that are imported with catalogeditor role from a non-default
domain are not visible to other users that belong to the same project.
About this task
You can import OVA virtual images that you created. You can also download new
virtual images from IBM and then import them to SmartCloud Orchestrator.
For PowerVM Hypervisor Edition (HVE) images, you must import the related
OVA file to load the image metadata before you can register them. For information
about registering images, see Registering a virtual image on page 290.
To import a new virtual image to the SmartCloud Orchestrator catalog, perform
the following steps:
Procedure
1. From the menu bar, select Images & Patterns > Virtual Images.
2. Click the Add icon to import a new virtual image.
3. In the new window check the option Import an image.
4. Enter the image location in the OVA file location field. The image location can
be either an HTTP URL or you can transfer the image using Secure Copy
Protocol (SCP) with the following format: <hostname>:/path.
The images that are located in the /data/repos/scp directory on Central Server
1 can be accessed by specifying the HTTP URL in the following format:
http://central-server-1/scp/my_virtual_image.ova
where central-server-1 is the host name or the IP address of Central Server 1.
5. Optional: If the OVA file location is secured, enter the credentials to access it in
the User name and Password fields.
Results
The new virtual image is now available in the catalog.
Important: The virtual image is stored in the reference repository in the Virtual
Image Library. Before you can deploy the virtual image in a pattern, you must
copy the image to an OpenStack operational repository (KVM or VMware). Access
the Virtual Image Library user interface by clicking Images & Patterns > Virtual
Image Library, and follow the procedure described in Copying an image from the
reference repository on page 322.
If you are using a KVM hypervisor, you can only import single-disk images. In
SmartCloud Orchestrator you can add additional disks at deployment time. For
more information, see Add-ons in the catalog on page 255.
Chapter 5. Managing virtual images 289
What to do next
You can use the new virtual image to create patterns. See Working with virtual
system patterns on page 511 for more information about patterns.
Related reference:
Virtual image fields on the user interface on page 292
This topic provides a reference for the fields associated with a virtual image.
Registering a virtual image
You can register virtual images that are stored on external hypervisors of an
OpenStack region. The registration of images from external hypervisors allows a
more scalable and flexible way to manage images in the cloud.
Before you begin
You must be assigned the admin role to perform these steps.
Note: For PowerVM Hypervisor Edition (HVE) images, you must import the
related OVA file to load the image metadata before you can register them. For
information about importing images, see Importing a virtual image to the
catalog on page 289.
When you register an imported PowerVM image, use the Map to image field to
map the registered image to the imported image.
About this task
You can use the SmartCloud Orchestrator user interface to register images from
external hypervisors.
Procedure
1. From the menu bar, select Images & Patterns > Virtual Images.
2. Click the Add icon to start registering a new image.
3. A new window opens. Click Register an image from a region.
4. From the Regions list, select the region from which you want to register the
virtual images.
5. Click Refresh to display the list of unregistered images that are available for
the selected region.
Note: If an image name is highlighted in red, another image is already
registered with that name. To avoid errors in such cases, change the name of
the unregistered image. To change an image name, click the image name and
type a new name.
a. If you are using a PowerVM hypervisor, the images that you imported by
using VMControl are automatically available in your OpenStack
environment.
b. If you are using a KVM hypervisor, and a particular image does not appear
in the list of unregistered images when you click Refresh, add the image to
the OpenStack environment, as described in Adding images to OpenStack
on page 294.
6. Use the Filter field if you need to search for specific images.
7. Select one or more images from the list.
290 IBM SmartCloud Orchestrator 2.3: User's Guide
8. If an image from an OVA file is already imported into the Workload Deployer,
and an image that is already registered in an OpenStack region represents the
same image, you do not need to check the image out of the Virtual Image
Library to the target region. Instead, you can use the Map to image field to
logically link the Workload Deployer OVA image to the image from the region.
a. Click on the Map to image entry for the new image.
b. In the Map to image field, select the target image from the list of registered
images.
9. Click Register.
Results
You registered your virtual image from an OpenStack region.
Removing a virtual image from the catalog
You can remove a virtual image from the catalog.
Before you begin
You must be assigned the catalogeditor role and be granted all access to the virtual
image that you want to remove. You can also perform these steps if you are
assigned the admin role.
About this task
When you remove a virtual image, any patterns that refer to that virtual image are
no longer deployable. You must clone these patterns and link them to a new
virtual image before they can be deployed.
You can use the following steps to remove a virtual image from the catalog.
Procedure
1. From the left panel of the Virtual Images window, select the virtual image to
remove from SmartCloud Orchestrator.
2. Verify that the virtual image selected is not currently being used by any of the
virtual system instances managed by the SmartCloud Orchestrator. A virtual
image cannot be deleted if a virtual system instance that is referencing that
virtual image is currently running. To confirm that a virtual image is not being
used in the cloud, ensure that the In the cloud now field does not show any
virtual system instance. If no virtual system instances are being used in the
cloud, (none) is displayed.
3. Click the remove icon to remove the virtual image from the catalog. A window
is displayed requesting your confirmation that this virtual image can
permanently be removed.
4. Click OK to confirm that you want to remove the virtual image.
Results
After you have completed these steps, the virtual image has been removed from
the catalog.
Chapter 5. Managing virtual images 291
What to do next
Clone any patterns that referenced the virtual image that you removed. You must
link these patterns to a new virtual image before they can be deployed. For more
information about cloning a pattern, see Cloning an existing virtual system
pattern on page 517.
If you want to remove the virtual image from the infrastructure, follow this
procedure:
1. Remove the image from SmartCloud Orchestrator user interface. This step is
only removing the link to the image from the
SmartCloud Orchestrator user interface (in other words, you can not longer use
SmartCloud Orchestrator to deploy images based on that template).
2. For a VMware region: remove the image from the vCenter. This step
automatically removes the image from glance as well.
3. For a KVM region, remove the image from glance running the command
glance image-delete.
4. Remove the image metadata from glance.
Related reference:
Virtual image fields on the user interface
This topic provides a reference for the fields associated with a virtual image.
Virtual image fields on the user interface
This topic provides a reference for the fields associated with a virtual image.
Virtual Image fields
The following fields are used when working with a virtual image:
Description
This optional field is available so you can provide a text description for
your virtual image.
Created on
This automatically generated field specifies the date when this virtual
image was created.
Current status
The Current status field is automatically populated to display the state of
this virtual system instance.
Updated on
This automatically generated field specifies the date when this virtual
image was last updated.
License agreement
This field specifies if the license agreement to use this virtual image has
been accepted. If the license agreement has not been accepted, then the
virtual images are not displayed in the drop-down menu to be used in a
pattern.
Hypervisor type
This field is set when the virtual image is created and cannot be modified.
It specifies the type of hypervisor this virtual image requires.
Operating System
This field specifies the guest operating system for the virtual image.
292 IBM SmartCloud Orchestrator 2.3: User's Guide
Region
This field specifies the region where the virtual image is registered.
Version
The version field specifies the version of WebSphere Application Server
that is included on the virtual image. Though this required field can be set
to any value, it must contain a valid version of WebSphere Application
Server. It can be set when the virtual image is cloned in the catalog.
The version of the virtual image is propagated down to parts on pattern
using the virtual image. The version can be changed, on an individual part,
on the editing canvas. For more information, see Virtual system pattern
editing views and parts on page 522.
Image reference number
This field is set when the virtual image is created and cannot be modified.
It specifies the WebSphere Application Server build number for the virtual
image.
Product IDs
This field specifies the IBM product ID of the product or products included
in the virtual image.
Location
The Location is the place where virtual images are stored; registered
images are stored on the hypervisor; imported image are stored locally.
Contains Parts
This field lists the available parts for the virtual image. Parts that are not
available because advanced options are not enabled are marked as inactive.
Included in patterns
This field specifies a list of links to all the patterns that are constructed
using this virtual image. You can click any <pattern_name> to display the
details for that pattern.
In the cloud now
The field specifies a list of links to all the virtual system instances that
were created using patterns constructed with this virtual image. You can
click any <virtual_system_name> to display the details for that virtual
system instance.
Mapped images
This field lists the current image and any other images that are mapped to
the current image. For more information about image mapping, see
Registering a virtual image on page 290.
Access granted to
The creator of a virtual image is automatically granted all access to the
virtual image as the owner. If you want additional users to access this
virtual image, then you need to manually grant access to the projects to
which those users belong. For more information about object level
permissions, see User roles in SmartCloud Orchestrator on page 151.
Hardware
This section can be expanded to display additional details about the
hardware configuration of the virtual image.
v Virtual CPU count
This field specifies the number of processors the virtual image
represents.
v Virtual machine memory (MB)
Chapter 5. Managing virtual images 293
This field specifies the amount of memory, in megabytes, on the
hypervisor that this virtual machine is allocated. This value is specified
in the pattern that was deployed to create the virtual system instance.
v Network interfaces
This field is used to set the number of network interfaces require by this
virtual image during deployment. This function allows you to take
advantage of multiple network interfaces when applicable. This field
cannot be modified after the image has been extended.
v <volume names>
These fields specify the volume names and the sizes that make up the
virtual image. These fields cannot be modified after the image has been
extended.
Comments
This field can be used to include additional comments about a virtual
image.
Related tasks:
Populating the catalog on page 233
The SmartCloud Orchestrator catalog contains the application templates, plug-ins,
reusable components, virtual images, virtual system patterns, script packages, and
add-ons that are used to build the virtual environment.
Importing a virtual image to the catalog on page 289
Import virtual images to the catalog to use them in a pattern.
Removing a virtual image from the catalog on page 291
You can remove a virtual image from the catalog.
Related information:
Chapter 5, Managing virtual images, on page 287
Virtual images provide the operating system and product binary files that are
required to create a virtual system instance.
Adding images to OpenStack
Add images to your OpenStack environment to be able to register them in
SmartCloud Orchestrator.
About this task
If you are using a KVM hypervisor, before registering an image to SmartCloud
Orchestrator, you must add the image to your OpenStack environment.
Note: If you are using a KVM hypervisor, you can only add single-disk images. In
SmartCloud Orchestrator, you can add additional disks at deployment time. For
more information, see Add-ons in the catalog on page 255.
If you are using a VMware hypervisor, the images are automatically discovered in
your OpenStack environment when the vCenter connection is established
To add an image in OpenStack, perform the following steps on the Region Server
where OpenStack is installed:
Procedure
1. Set the environment by running the following command:
source /root/keystonerc
294 IBM SmartCloud Orchestrator 2.3: User's Guide
2. Run the following command:
glance image-create --name image_name --disk-format disk_format --container-format=bare
--is-public [True|False] < image_path
where
image_name
Specifies a name for the new image 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.
--container-format
Specifies the container format for the image. The acceptable formats
are: ami, ari, aki, bare, and ovf.
--is-public
Specifies if 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.
Results
The image is added to your OpenStack environment. You can register the image to
SmartCloud Orchestrator by following the procedure described in Registering a
virtual image on page 290.
Working with Virtual Image Library
Use Virtual Image Library to perform advance management tasks on the virtual
images in your SmartCloud Orchestrator environment.
Overview
The IBM Virtual Image Library component provides extended services for image
management.
After images are created, the lifecycle management of those images presents a
challenge. With a traditional approach, it is not always possible to identify the
contents of any particular image and any image can resemble a black box, the
contents of which are unknown. You might know that the image contains a
particular operating system, but you probably do not know at any point in time if,
for example, a monitoring agent is installed on the image, or what images do not
comply with security policies. As new software patches become available, you
might not know which images need to be updated. If your image management
process cannot adequately meet these challenges, the value of your images is
diminished.
In Virtual Image Library, the following types of operational image repositories are
supported:
Chapter 5. Managing virtual images 295
v VMware
v OpenStack
v VMControl
After you define the operational repository to Virtual Image Library and index the
images that it contains, all the information about the images is stored in the Virtual
Image Library database.
You can perform the following operations on the indexed images:
v Search images for specific software products
v Compare two images and determine the differences in files and products
v Find similar images
v Track image versions and provenance
In Virtual Image Library, you can use a local image store, called the reference
repository, to save copies of key images from any operational repository or to
replicate copies of images from the reference repository to any operational
repository.
You can also import images from the Virtual Image Library file system to the
reference repository to perform image management operations on the imported
images.
Note: Virtual Image Library might delegate tasks related to virtual disks to a
remote proxy. This means that if you have distributed environments or slow
networks, Virtual Image Library can use a remote proxy installed close to the
repository. The advantage of this configuration is that heavy operations at the
network level are made locally and only the information retrieved is sent to the
server.
Restriction: Check in, check out and indexing for Power images is not supported
in Virtual Image Library.
Virtual Image Library basics
Find out more about Virtual Image Library basics, primary users, key examples
and terms for this component. Review troubleshooting information and the log file
names and location for this component and also additional resources that help you
complete your Virtual Image Library tasks.
296 IBM SmartCloud Orchestrator 2.3: User's Guide
Process
The following diagram shows typical image management processes followed by Virtual
Image Library configuration librarians and operators.
Copy images to
reference repository
Copy images to
operational repositories
Import images
Index images
Perform image
management operations
(search, compare,
find similar images,
track image version
and provenance)
Add
operational repositories
Configuration Librarian
Virtual Image Library Operator
Legend
User roles
You must be assigned to the appropriate user role to use Virtual Image Library.
Table 27. User roles
Role Description Skills
Operator The operational role for day-to-day
activities such as indexing and
analytics. An operator can perform
tasks such as searching and
comparing images, finding similar
images, and listing products and
files.
Knowledge of the operational Virtual
Image Library environment
Configuration Librarian The role for maintaining the image
catalog. In addition to operator tasks,
the configuration librarian can
perform tasks such as adding
operational repositories, checking in
and out images, importing local
images, and deleting images from the
reference repository.
v Knowledge of the Virtual Image
Library environment
v Knowledge of the virtualization
technologies
Chapter 5. Managing virtual images 297
Table 27. User roles (continued)
Role Description Skills
Administrator A super user role to access all the
Virtual Image Library capabilities.
Knowledge of the Virtual Image
Library environment and
configuration
Key terms
deployed virtual machine
An instance of a virtual image deployed on a hypervisor manager.
hypervisor
A program or a portion of Licensed Internal Code that allows multiple instances of
operating systems to run simultaneously on the same hardware. Typically, it
represents the server that hosts the virtual servers. For ESX, for example, the
hypervisor is the VMware ESX server that hosts the virtual servers.
operational repository
A repository for virtual images and deployed virtual machines that is managed by
a hypervisor.
Open Virtualization Appliance (OVA)
A single file distribution of an OVF package. It is stored in TAR format.
Open Virtualization Format (OVF)
A platform-independent open standard for packaging and distributing virtual
appliances.
reference repository
The local image store used by the Virtual Image Library component to store the
virtual images.
virtual image
A virtual representation of a computer program and its related data, such as the
kernel, file systems, libraries, and programs of the managed system at a particular
time.
Troubleshooting
If you encounter a problem with the Virtual Image Library component, see
Troubleshooting on page 330.
Log files
For information about log files, see Log files on page 330.
298 IBM SmartCloud Orchestrator 2.3: User's Guide
Resources
To learn more about using the Virtual Image Library component and how this component is
integrated into the product you are using, see the official product documentation.
Installing and configuring
Follow these procedures to install, configure, uninstall, back up, or restore Virtual
Image Library.
Installing
Follow this procedure to install Virtual Image Library and any distributed proxy
components.
Before you begin
Virtual Image Library is automatically installed during the SmartCloud
Orchestrator installation. Follow this procedure only if you want to manually
install Virtual Image Library for specific reasons that are related to your
environment. Only one Virtual Image Library can be installed and connected to
your SmartCloud Orchestrator environment.
Note: Upgrading from a previous version of Virtual Image Library is not
supported in this release.
For the Virtual Image Library installation, be sure to meet the following
requirements:
v Hardware requirements
See the requirements that are listed in step 2 of the installation procedure
depending on the value you specify for the checkSize parameter.
v Software requirements
Red Hat Enterprise Linux versions 6.3 or 6.4
RPM packages that are listed in the rpmList_vil.txt file in the Virtual Image
Library server installation and rpmList_proxy.txt file for the proxy
installation. These files are in the Virtual Image Library installation package.
These packages are available in the Red Hat Enterprise Linux 6.3 or 6.4
installation image or in the Red Hat Network, and they are installed during
the installation procedure by using Yum.
Note: The following package MUST be available in a Yum repository but is
NOT included in the installation image:
libguestfs-winsupport-1.0-7.el6.x86_64.rpm
Make sure that this package is available in the Yum repository and that the
related public keys are correctly imported into the repository. For more
information about Yum, see the Red Hat Enterprise Linux documentation.
For a Virtual Image Library installation, be sure that there is no WebSphere
Application Server installed in the /opt/IBM/WebSphere/AppServer directory.
Chapter 5. Managing virtual images 299
About this task
The installation procedure automatically detects if Virtual Image Library is already
installed.
To install Virtual Image Library, complete the following steps:
Procedure
1. Unpack the Virtual Image Library installation package into a temporary
directory.
2. From the directory where you unpacked the installation package, run the
following script:
install_vil.sh -u vil_admin_name -p vil_admin_password
[-checkSize prodEnv|testEnv|customEnv] [-sso]
where
-u vil_admin_name
Specifies the Virtual Image Library administrator ID to be used during
the installation. This parameter is required.
-p vil_admin_password
Specifies the Virtual Image Library administrator password. This
parameter is required.
-checkSize prodEnv|testEnv|customEnv
Specifies the type of environment you are installing. This parameter is
optional. Use this parameter to define the hardware requirements that
are checked during the installation procedure. The valid values are:
prodEnv
The default value. For a production environment, the following
hardware requirements are checked:
v 2 CPU
v 8 GB RAM
v 10 GB free disk space in the /opt file system
v 40 GB in the /tmp file system
v 30 GB free disk space in the /home/library file system. The
actual disk space requirement depends on the size of the
virtual images that you want to store in the reference
repository.
testEnv
For a test environment, the following hardware requirements
are checked:
v 2 CPU
v 8GB RAM
v 5 GB free disk space in the /opt file system
v 10 GB free disk space in the /home/library file system
v 30 GB in the /tmp file system
customEnv
Specify the hardware requirements to be checked during the
installation procedure in the install_vil.config file. The
minimum hardware requirements that you can specify are:
v 1 CPU
300 IBM SmartCloud Orchestrator 2.3: User's Guide
v 4 GB RAM
v 3 GB free disk space in the /opt file system
v 5 GB free disk space in the /home/library file system
v 10 GB in the /tmp file system
If you specify any value less than the listed ones, the value is
ignored and the installation procedure checks the minimum
allowed value.
-sso You can start the Virtual Image Library user interface from the
SmartCloud Orchestrator user interface. This parameter is
optional.
3. You can check the installation results that are found in one of the following log
files in the /tmp directory: fresh_install_vil.log
If the installation procedure does not complete successfully, correct the problem
that is described in the error message and run the procedure again. The
procedure continues to run from the last successful step.
To restart the installation procedure from the first step after you manually
cleaned up a previous unsuccessful installation, you must delete the following
file in the /tmp directory: fresh_install_vil.step
Results
Virtual Image Library is now installed and started.
Note: No user lockout policy is set in the Virtual Image Library environment.
Because Virtual Image Library manages user security through WebSphere
Application Server, to improve your environment security, see the WebSphere
Application Server documentation for information about setting security policies.
Installing the proxy component:
Follow this procedure to install the Virtual Image Library distributed proxy
components.
Before you begin
The distributed proxy is a component of Virtual Image Library that is involved
with image management operations. You can optionally install distributed proxies
on remote nodes.
About this task
If you choose to install only the distributed proxy component without the Virtual
Image Library server, complete the following steps:
Procedure
1. Unpack the Virtual Image Library proxy installation package into a temporary
directory.
2. From the directory where you unpacked the installation package, run the
following script:
install_vil.sh -proxy -vilServer <hostnameFqdn>
[-checkSize prodEnv|testEnv|customEnv]
where
Chapter 5. Managing virtual images 301
-proxy Runs an installation of the distributed proxy component only on a
different machine than the Virtual Image Library server.
-vilServer
Specifies the fully qualified host name or the IP address of the Virtual
Image Library server. To be used only together with the -proxy option.
If you specify th fully qualified host name of the Virtual Image Library
server, the proxy must be able to resolve that host name. If it cannot,
add the IP address and host name to /etc/hosts before installing the
proxy.
-checkSize prodEnv|testEnv|customEnv
Specifies the type of environment you are installing. This parameter is
optional. Use this parameter to define the hardware requirements that
are checked during the installation procedure. The valid values are:
prodEnv
The default value. For a production environment, the following
hardware requirements are checked:
v 2 CPU
v 8 GB RAM
v 10 GB free disk space in the /opt file system
v 100 GB free disk space in the /home/library file system. The
actual disk space requirement depends on the size of the
virtual images that you want to store in the reference
repository.
testEnv
For a test environment, the following hardware requirements
are checked:
v 2 CPU
v 4 GB RAM
v 5 GB free disk space in the /opt file system
v 10 GB free disk space in the /home/library file system
customEnv
Specify the hardware requirements to be checked during the
installation procedure in the install_vil.config file. The
minimum hardware requirements that you can specify are:
v 1 CPU
v 4 GB RAM
v 3GB free disk space in the /opt file system
v 5 GB free disk space in the /home/library file system
If you specify any value less than the listed ones, the value is
ignored and the installation procedure checks the minimum
allowed value.
3. You can check the installation results that are found in one of the following log
files in the /tmp directory: fresh_install_proxy.log.
Results
The proxy component of Virtual Image Library is now installed.
302 IBM SmartCloud Orchestrator 2.3: User's Guide
Configuring
Follow these procedures to configure Virtual Image Library and the proxy
component.
Configuring Virtual Image Library server and remote proxy components:
Follow this procedure to configure Virtual Image Library and any remote proxy
components.
To perform image management operations against a hypervisor manager, you must
configure a proxy. The proxy with which you manage a hypervisor manager can be
on the Virtual Image Library server or on a remote node that you installed.
The origami configuration file is located in /etc/origami/origami.config. It
contains the main configuration properties that allow Virtual Image Library to
identify which proxy is managing which domain. You can find this file on both the
Virtual Image Library server and any remote proxy node. The structures of the
files are the same but the one related to the server contains some additional
configuration sections to identify the knowledge base as well as all the proxies that
are deployed. This is so that the Virtual Image Library server can distribute the
actions to the correct node when needed.
Note: Restart your proxy services after any configuration change by running:
service vilProxy restart.
Configuring a Virtual Image Library server to manage a VMware hypervisor
manager using a remote proxy
To define a new proxy, run the following commands on the Virtual Image Library
server:
cd /home/library
./configureProxy.sh --addProxyDef -h <PROXYAGENT_IP> -c <Hypervisor_Manager_IP>
where
v PROXYAGENT_IP is the IP address or host name fqdn of the proxy
v Hypervisor_Manager_IP is the same string shown by nova-cloud-show in the name
field, so, if you have an IP address there, you use the IP address, if you have a
hostname you must pass the hostname.
The new proxy definition is added in the /etc/origami/origami.config file.
Restart the proxy service on the Virtual Image Library server by running the
following command:
service vilProxy restart
Install the Virtual Image Library proxy on the machine delegated to manage the
hypervisor manager image operations by following the procedure described in
Installing the proxy component on page 301.
On the proxy machine, configure the Virtual Image Library proxy by running the
following commands:
cd /home/library
./configureProxy.sh --addRepDef -c <Hypervisor_Manager_IP>
Chapter 5. Managing virtual images 303
where Hypervisor_Manager_IP is the IP address of the hypervisor manager. If your
hypervisor manager is VMware, you must specify the IP address and port in the
format <Hypervisor_Manager_IP>:<port>. The default port value is 443.
The new proxy definition is added in the /etc/origami/origami.config file.
Restart the proxy service on the proxy machine by running the following
command:
service vilProxy restart
Results
Virtual Image Library has been configured.
Configuring a Virtual Image Library server to directly manage a VMware
hypervisor manager
To add the VMware hypervisor manager to the Virtual Image Library server proxy
configuration, run the following commands:
cd /home/library
./configureProxy.sh --addRepDef -c <Hypervisor_Manager_IP>:<Port>
where Hypervisor_Manager_IP is the IP address of the hypervisor manager. The
default port value is 443.
The new proxy definition is added in the /etc/origami/origami.config file.
Restart the proxy service on the Virtual Image Library server by running the
following command:
service vilProxy restart
Results
Virtual Image Library has been configured.
Configuring Virtual Image Library proxies with slow connectivity:
If you have Virtual Image Library proxies with slow connectivity, follow this
procedure to avoid timeout problems during check in and check out operations.
Procedure
1. Edit the /opt/p2pdiff/TransferClient/GlobalTracker.properties file on
Central Server 2 and set the following parameter:
sequentialTransfers=true
2. Restart the proxy service by running the following command:
service vilProxy restart
304 IBM SmartCloud Orchestrator 2.3: User's Guide
Configuring Virtual Image Library for VMware:
To complete the registration of a vCenter to OpenStack, you must configure the
Virtual Image Library proxies.
About this task
You must configure Virtual Image Library for VMware so that the program can
understand which proxy is going to manage the vCenter and where to redirect
indexing and check out requests that are related to VMware. To do this, perform
this procedure on both the Virtual Image Library server and the proxy that
manages vCenter. In this example, the proxy is installed on OpenStack.
Note:
v To improve performance, install a proxy on a virtual machine hosted on vCenter.
Perform these steps to manage a VMware vCenter that is already federated or
that will be federated to an OpenStack hypervisor.
v The Virtual Image Library proxy machine that manages the VMware vCenter
must be able to resolve all the ESX servers by their host names and by the
names shown in vCenter.
Procedure
1. On the Virtual Image Library server machine (Central Server 2), open the
/etc/origami/origami.config file.
2. In the origami.config file, there is an entry for proxies. There might be multiple
agent-id entries under the proxies entry. You must find the connectivity json
object (agent-id) which lists the host name that OpenStack is running on, that
is, Region Server, and the url entry value that contains the IP address that
OpenStack is running on. In the following example, the agent ID is
region-server which is the hostname of the machine OpenStack is running,
and the url value has the IP address of the OpenStack server which is 10.10.0.1:
{
"enabled": true,
"connectivity": [
"region-server",
"10.10.0.1",
],
"capabilities": [
"crawl",
"cache",
"portability"
],
"agent_id": "region-server",
"url": "http://10.10.0.1:8123/origami"
}
],
3. Add the vCenter_IP_address:Port running the following commands on the
Virtual Image Library Server:
cd /home/library
./configureProxy.sh --addRepDef -h <PROXYAGENT_IP> -c <Hypervisor_Manager_IP>:Port
where
v PROXYAGENT is the IP address or host name fqdn set in the proxies URL
related to OpenStack. In the example, it is 10.10.0.1 which is the IP address
that OpenStack is running on.
v <Hypervisor_Manager_IP>:Port is the vCenter IP address with the port. The
default port value is 443.
Chapter 5. Managing virtual images 305
To find the value of the vCenter IP address, on the OpenStack server, that is,
Region Server, go to /opt/ibm/openstack/iaas/smartcloud/bin and run the
following command:
./nova-cloud-show
Check the value of "external_uri": and then update the proxy configuration
adding this IP address as shown in the example at the bottom of this topic.
4. After the configuration change, restart the proxy service by running "service
vilProxy restart".
5. On the Region Server, configure the proxy to manage the vCenter by running
the command:
# cd /home/library
# ./configureProxy.sh --addRepDef -c <Hypervisor_Manager_IP>:port
where Hypervisor_Manager_IP is the vCenter IP address with the port. The
default port value is 443.
6. Restart the proxy service by running "service vilProxy restart".
Results
Virtual Image Library is now configured for VMware.
Example
Example for the server:
cd /home/library
./configureProxy.sh --addRepDef -h 10.10.0.1 -c 10.10.100.17:443
Note: In this example, "10.10.100.17" is the vCenter IP address retrieved with the
nova-cloud-show command. "10.10.0.1" is the proxy agent.
Example for the proxy:
cd /home/library
./configureProxy.sh --addRepDef -c 10.10.100.17:443
Uninstalling
Uninstall Virtual Image Library and the proxy component.
Uninstalling Virtual Image Library:
Follow this procedure to uninstall the Virtual Image Library component.
Before you begin
If you uninstall the Virtual Image Library component, you cannot use any
SmartCloud Orchestrator features until you reinstall the component.
About this task
To uninstall Virtual Image Library, run the script /var/library/uninstall/
uninstall_vil.sh.
Results
Virtual Image Library is now uninstalled.
306 IBM SmartCloud Orchestrator 2.3: User's Guide
Uninstalling the distributed proxy:
Follow this procedure to uninstall any distributed proxy components.
About this task
To remove the distributed proxy, run the script /var/proxy/uninstall/
uninstall_vil.sh -proxy -vilServer <hostnameFqdn> where
-proxy Runs an uninstallation of the distributed proxy component only on a
different machine than the Virtual Image Library server.
-vilServer
Specifies the fully qualified host name or the IP address of the Virtual
Image Library server. To be used only together with the -proxy option. If
you specify the fully qualified host name of the Virtual Image Library
server, the proxy must be able to resolve that host name.
Results
The proxy component is now uninstalled.
Best practices
Best practices for managing images in the Virtual Image Library reference
repository and for the remote proxy.
Managing reference images:
Best practices for managing images in the Virtual Image Library reference
repository.
If you add an image in the reference repository, either importing it from an OVA
file or checking it in from an operational repository, the image is physically stored
in the proxy that has managed the request. The reference repository is distributed
among all the connected proxies. As a consequence, if a proxy becomes unavailable
and an image is only available on it, this image becomes unusable for indexing or
for checking out until the proxy is back online.
The following scenarios provide some best practices you can use to manage
reference repository images:
Managing a dismissal of a proxy:
Follow this procedure to dismiss a proxy and avoid discontinuity in the service.
About this task
To remove or substitute a proxy, perform the following steps:
Procedure
1. On the proxy that is going to be dismissed, run the /home/library/
copyImages.sh script to copy the images to the Virtual Image Library server or
to another proxy connected to it.
2. To dismiss the proxy, run "service vilProxy stop".
3. On the proxy that substitutes the dismissed one:
Chapter 5. Managing virtual images 307
a. Update the "connectivity" section in the origami.config by adding the
repositories:
/home/library/configureProxy.sh -addRepDef -c <domain1>,<domain2>
b. Restart the vilProxy service.
4. On the VIL server
a. Modify the "proxies" section in the origami.config by disabling the stopped
proxy and adding the repositories listed in its "connectivity" section to
another proxy:
/home/library/configureProxy.sh -migrateProxy -s source_hostname -d destination_hostname -e false
b. Restart the vilProxy service
Manage a planned shutdown of a machine hosting a proxy:
Follow this procedure if you must temporarily stop a proxy or shut down the
machine where the proxy is installed avoiding discontinuity in the service.
To shut down the machine where the proxy is installed to avoid discontinuity in
the service, you can run the steps needed to dismiss a proxy. When the machine is
back online, restore the original origami.config files and restart the vilProxy service
on the Virtual Image Library server and on the relevant proxies.
Managing an unplanned outage of the machine where the proxy is installed:
Follow this procedure to reduce the risk that an unplanned outage of a machine
that hosts a proxy causes problems in using some images.
To shut down the machine where the proxy is installed to avoid discontinuity in
the service, you can run the steps needed to dismiss a proxy. When the machine is
back online, restore the original origami.config files and restart the vilProxy service
on the Virtual Image Library server and on the relevant proxies.
You can use one of the following approaches:
Consolidate all the images to a proxy dedicated to this backup role
v Install the proxy to act as backup.
v Modify the origami.config file of the Virtual Image Library server by
adding the new proxy:
/home/library/configureProxy.sh --addProxyDef -h <hostname>
v Do not add any repository definitions to this proxy.
v To periodically back up the content of each proxy, run the following
command for each of them:
/home/library/copyImages.sh -d <backup_proxy_hostname> -s <src_proxy_hostname>
Maintain a distributed approach
v For each proxy, identify another proxy on which to back up its
information.
v To periodically back up the content of proxies, run the following
commands for each identified couple:
/home/library/copyImages.sh -d <proxy1_hostname> -s <proxy2_hostname>
/home/library/copyImages.sh -d <proxy2_hostname> -s <proxy1_hostname>
308 IBM SmartCloud Orchestrator 2.3: User's Guide
Managing the outage:
If an unplanned outage occurs, you can at least work with all the images in the
reference repository checked in before the last backup.
Procedure
On the proxy that substitutes the unavailable one
1. Update the "connectivity" section in the origami.config by adding the
repositories:
/home/library/configureProxy.sh -addRepDef -c <domain1>,<domain2>
2. Restart the vilProxy service.
On the Virtual Image Library server
3. Modify the "proxies" section in the origami.config file by disabling the
unavailable proxy and adding the repositories listed in its "connectivity" section
to another proxy:
/home/library/configureProxy.sh -migrateProxy -s source_hostname -d destination_hostname -e false
4. Restart the vilProxy service.
What to do next
When the machine is back online, restore the original origami.config files and
restart the vilProxy service on the Virtual Image Library server and on the relevant
proxies.
Managing the remote proxy:
Best practices for managing the Virtual Image Library remote proxy.
With Virtual Image Library you can federate operational repositories to support
geographically distributed data centers. Using proxy components, you can
decentralize tasks related to virtual disks over distributed sites.
In the SmartCloud Orchestrator installation, Virtual Image Library is installed on
the Central Server 2 virtual machine. On the Region Server, you have the
OpenStack hypervisor manager and a proxy. Virtual Image Library is configured to
delegate OpenStack management to the proxy.
The following scenarios provide some best practices you can use to manage
operational repository images:
Configuring Virtual Image Library for a new repository:
You can configure Virtual Image Library for a new repository.
When you add a new operational image repository, you might want to delegate
tasks related to virtual disks to a remote proxy installed close to the repository. The
advantage of this configuration is that heavy operations at network level are made
locally and only the information retrieved is sent to the server. This reduces
network traffic and accelerates check in and check out operations.
In particular, if you are adding a VMware operational repository, either from the
Virtual Image Library user interface or through the OpenStackcommand
nova-cloud-create, you might want to create a virtual machine hosted by the
vCenter and install a proxy. The nested virtualization capabilities must be enabled
Chapter 5. Managing virtual images 309
on this virtual machine.
Changing the WebSphere account password:
You can change the WebSphere account password that is supplied during the
installation.
About this task
The Virtual Image Library server is registered as a service of the Linux machine. At
boot time, Virtual Image Library is started automatically. The user name and
password to manage the Virtual Image Library server are stored in the following
file:
/opt/IBM/WebSphere/AppServer/profiles/imageLibraryProfile/properties/
soap.client.props at the following key:
com.ibm.SOAP.loginUserid=wasadmin
com.ibm.SOAP.loginPassword={xor}Lz4sLChvLTs=
The password is stored in encrypted form.
To change the password, perform the following steps:
Procedure
1. Change the password from the WebSphere Application Server service console:
https://<VirtalImageLibraryHostname>:9043/ibm/console-> Users and Groups
-> Manage Users. Select the account defined at installation and change the
password.
2. Enter a new password in plain text as a value of the key
com.ibm.SOAP.loginPassword.
3. Run the WebSphere Application Server password encryption tools.
/opt/IBM/WebsSphere/AppServer/bin/PropFilePasswordEncoder.sh
/opt/IBM/WebSphere/AppServer/profiles/imageLibraryProfile/properties/soap.client.props
com.ibm.SOAP.loginPassword
Backing up and restoring the proxy:
Back up your Virtual Image Library proxy, especially when you apply a fix pack or
upgrade, so that you can restore the existing environment, if necessary.
Before you begin
After you have backed up the Virtual Image Library server, stop the server and
perform the following steps:
1. Ensure that you are the root user and navigate to the directory where the
media was extracted: /install_media/vil-proxy
2. Extract the script into a path, for example /root, from the package by running
the following command: > unzip -p il_proxy_install_package.zip
backupRestore_proxy.sh > /root/backupRestore_proxy.sh
3. Move the script to the machines where the proxy is installed, for example, into
the directory /root/.
4. Assign execution permission by running the following command: > chmod 750
/root/backupRestore_proxy.sh
5. Run the command without parameters for usage: > /root/
backupRestore_proxy.sh
310 IBM SmartCloud Orchestrator 2.3: User's Guide
About this task
To back up the proxy, run the following command: backupRestore_proxy.sh
-backup -dir <backup_directory> where<backup_directory> is the local directory to
store the backup. For example, > /root/backupRestore_proxy.sh -backup -dir
/root/backup. The backup is stored as /root/backup/
proxy_backup_<timestamp>.tgz. Copy this file to a secure remote machine.
To roll back the Virtual Image Library proxy, perform the following steps:
Procedure
Note: You must restore the proxy before you roll back the server.
1. Copy the backup .tgz file to the proxy machines.
2. To restore the proxy, run the following command: backupRestore_proxy.sh
-restore -file <backup_file> where <backup_file> is the .tgz absolute file path
on local obtained by the backup command. For example, >
/root/backupRestore_proxy.sh -restore -file /root/backup/
proxy_backup_1373616171.tgz.
Getting started
Learn how to get started with Virtual Image Library.
To start and stop Virtual Image Library, you can use the following commands:
/home/library/il.sh start
/home/library/il.sh stop
The Virtual Image Library interface is a web-based user interface and can be
accessed with a web browser by entering https://vil_hostname:9443/
ImageLibraryUI/ where vil_hostname is the fully qualified domain name of the
Virtual Image Library server.
You can also access the Virtual Image Library interface from the SmartCloud
Orchestrator user interface by clicking Images & Patterns > Virtual Image Library
in the menu bar.
Before you use the Virtual Image Library interface, ensure that you meet the
requirements that are listed in Accessing SmartCloud Orchestrator user interfaces
on page 135.
Ensure that the correct image library roles are assigned to the user ID that you are
using depending on the Virtual Image Library tasks that you want to perform. For
information about Virtual Image Library roles, see User roles and requirements
on page 312.
Before performing management operations on virtual images and deployed virtual
machines, define the operational repositories to the Virtual Image Library
environment. For more information about defining operational repositories, see
Adding an operational repository on page 314.
Chapter 5. Managing virtual images 311
User roles and requirements
For image management tasks in the Virtual Image Library, ensure that you have
the required knowledge and access rights for your role.
Table 28. User roles
Role Description Skills
Operator The operational role for day-to-day
activities such as indexing and
analytics. An operator can perform
tasks such as searching and
comparing images, finding similar
images, and listing products and
files.
Knowledge of the operational Virtual
Image Library environment
Configuration Librarian The role for maintaining the image
catalog. In addition to operator tasks,
the configuration librarian can
perform tasks such as adding
operational repositories, checking in
and out images, importing local
images, and deleting images from the
reference repository.
v Knowledge of the Virtual Image
Library environment
v Knowledge of the virtualization
technologies
Administrator A super user role to access all the
Virtual Image Library capabilities.
Knowledge of the Virtual Image
Library environment and
configuration
Note: User names with non-ASCII characters are not supported in the Virtual
Image Library environment.
If you installed SmartCloud Orchestrator, Virtual Image Library is automatically
configured to use OpenLDAP to manage users and roles.
If you manually installed Virtual Image Library and you did not specify to use an
LDAP server during the installation procedure, to configure Virtual Image Library
to use an LDAP server to manage users and roles, complete the following steps.
1. Specify the LDAP server properties in the external LDAP configuration section
in the install_vil.config file. This file is contained in the Virtual Image
Library installation package.
The parameters in the external LDAP configuration section in the
install_vil.config file contains the default values to configure Virtual Image
Library to use the default OpenLDAP server that is installed in the SmartCloud
Orchestrator environment.
Note: Before you change the install_vil.config file, back up this file to save
the default values that you need if you want to configure Virtual Image Library
to use the default OpenLDAP server again.
If you are using this LDAP server, you must specify the value of the following
parameters:
LDAPHostName
Specify the host name of the LDAP server.
LDAPPrimaryAdminId
Specify a user that is already defined on the LDAP server and that you
use as Virtual Image Library administrator.
312 IBM SmartCloud Orchestrator 2.3: User's Guide
LDAPServerId
Specify the same value that you specified for the LDAPPrimaryAdminId
parameter.
LDAPPassword
Specify the password of the user you specified for the
LDAPPrimaryAdminId parameter.
If you want to use an LDAP server other than OpenLDAP, you must specify
the value of the other parameters according to your LDAP server configuration.
For information about the value of these parameters, see your LDAP
administrator.
2. Run the following commands:
cd /opt/IBM/WebSphere/AppServer/profiles/imageLibraryProfile/bin
./wsadmin.sh -user vil_admin_name -password vil_admin_password
-f ChangeSecurityProperties.jacl install_vil_config_file
where
v vil_admin_name and vil_admin_password are the credentials of the Virtual
Image Library administrator you specified during the installation procedure.
v install_vil_config_file is the full path to the install_vil.config file
where you specified the LDAP server properties.
3. If the wsadmin.sh command completes successfully, restart Virtual Image
Library by issuing the following commands:
/home/library/il.sh stop vil_admin_name vil_admin_password
/home/library/il.sh start vil_admin_name vil_admin_password
where vil_admin_name and vil_admin_password are the credentials of the
Virtual Image Library administrator you specified during the installation
procedure.
4. Assign the Virtual Image Library Administrator role to the user you specified
in the LDAPPrimaryAdminId parameter by following the procedure that is
described in Assigning a role to a user. After assigning the Administrator
role, you can use the credentials of this user to start and stop Virtual Image
Library and to log on to the user interface.
Assigning a role to a user:
Assign roles to a user, or to a group of users, to allow them to perform image
management tasks.
About this task
To assign a role to a user, or to a group of users, complete the following steps:
Procedure
1. Log on to the WebSphere Integrated Solutions Console with a web browser by
entering https://vil_hostname:9043/ibm/console, where vil_hostname is the
fully qualified domain name of the Virtual Image Library server. To log on,
specify the credentials of a Virtual Image Library administrator.
2. In the left pane, click Applications > Application Types > WebSphere
enterprise applications.
3. In the Enterprise Applications pane, click ImageManager.
4. In the Detail Properties section, click Security role to user/group mapping.
Chapter 5. Managing virtual images 313
5. In the role table, select one of the Virtual Image Library roles and click Map
Users.
6. Search for the users or the groups that you want to map and move them from
the Available to the Selected list. Click OK to confirm your changes.
7. In the Security role to user/group mapping, click OK.
8. Click Save to save the changes to the master configuration.
For more information about managing users and roles from the WebSphere
Integrated Solutions Console, see the WebSphere Application Server
documentation.
Adding an operational repository
Add an operational repository to Virtual Image Library to work with the virtual
images and the deployed virtual machines contained in the repository.
Before you begin
To add an operational repository, you must have the Configuration Librarian or
the Administrator role. See User roles and requirements on page 312 for more
information about Virtual Image Library roles.
If a firewall is installed between the Virtual Image Library server and the
hypervisor manager containing the repository you want to add, ensure that the
Virtual Image Library server is correctly authenticated to the firewall.
About this task
To add an operational repository, perform the following steps.
Note: When you create a cloud in OpenStack using the command
nova-cloud-create, the cloud and all the related resources are automatically added
to the Virtual Image Library Operational Repositories tree.
The list of the virtual images related to an operational repository contained in the
cloud group is synchronized with the SmartCloud Orchestrator image catalog
related to the cloud group.
Procedure
1. In the Images tab, click . The Add Operational Repositories dialog is
displayed.
2. Optionally, specify a name and a description for the hypervisor manager.
3. In the Hypervisor Manager Type list, select one of the following types:
v VMware Virtual Center
v OpenStack
v VMControl
4. Specify the parameters needed to connect to the hypervisor manager containing
the repository.
If you selected VMware Virtual Center or VMControl as hypervisor manager
type, specify:
v The host name or the IP address of the VMware vCenter server or
VMControl
314 IBM SmartCloud Orchestrator 2.3: User's Guide
v A user that is part of the Administrators group on the VMware vCenter
server or VMControl
v The user password
Note: User names containing non-ASCII characters are not supported in the
Virtual Image Library environment.
If you selected OpenStack as hypervisor manager type, specify:
v The Keystone server host name or IP address
v An OpenStack administrator
v The administrator password
Note: You can register domain users by entering <user_name>.<domain_name>
into the user name field of the domain registration panel. For example, for a
user called ibm_user in the ibm.com domain, enter ibm_user.ibm.com as the user
name.
5. Click OK.
You can track the status of the task you submitted in the task pane displayed in
the lower part of the window. In addition to the overall process task, the
following tasks are submitted:
v Discovering of all the virtual images and deployed virtual machines
v Basic indexing of all the virtual images
Note: To perform image management operations, including the automatic
indexing that starts when you add an operational repository, the host name or
IP address of the VMware vCenter server, VMControl, or of the Glance service
must be specified in the proxy configuration files.
Results
The operational repositories belonging to the hypervisor manager that you
specified are now displayed in the Operational Repositories tree.
When adding an operational repository, the virtual images contained in the
repository are automatically basic indexed but the deployed virtual machines are
not automatically indexed.
By default, the information related to the Virtual Image Library resources is
refreshed every two minutes. This information includes updates about add, modify,
and remove operations related to all the resources managed by the hypervisor
manager you specified.
You can change the refresh interval by specifying a new value for the
DomainPollingInterval parameter (in milliseconds) in the installedApps/
cell_name/ImageManager.ear/ImageManagerWeb.war/WEB-INF/web.xml file. Restart
Virtual Image Library to make effective your change by issuing the following
commands:
/home/library/il.sh stop
/home/library/il.sh start
Note: When an image is deleted on the repository, you still see the deleted image
in the Virtual Image Library views until the information related to the image is
refreshed. If you try to perform any operation on the deleted image, an error
message is displayed.
Chapter 5. Managing virtual images 315
Note: If you select Operational Repositories in the resource tree, the number of
the registered hypervisor managers is displayed in the Repositories field. If you
select an hypervisor manager or a location in the resource tree, the number of the
related operational repositories is displayed in the Repositories field.
Changing server access credentials:
If you change the credentials (user name or password) to access the hypervisor
manager, you must also update this information in the Virtual Image Library
database.
About this task
To change the hypervisor manager access credentials in the Virtual Image Library
database, perform the following steps:
Procedure
1. Select the hypervisor manager in the Operational Repositories tree.
2. Click Actions > Change Credentials. The Change Server Credentials dialog is
displayed.
3. Enter the values for the current and new password, and, optionally, for the
current and new user to access the hypervisor manager.
4. Click OK.
Results
The access credentials are updated with the new values you specified.
Note: If you change the user ID to access the hypervisor manager, ensure that the
new user ID can access the same images as the previous user ID. Because the
repository is not added again, even if the new user ID can access more images
than the previous user, the information related to those additional images is not
available in the Virtual Image Library environment. Also, if the new user ID can
access fewer images than the previous user, you get an error when trying to
perform any operation on an image that is no longer accessible.
Removing an operational repository:
Remove an operational repository if you no longer need to manage the related
virtual images or deployed virtual machines.
Before you begin
To remove an operational repository, you must have the following requirements:
v Configuration Librarian or the Administrator role. See User roles and
requirements on page 312 for more information about Virtual Image Library
roles.
v owner access to the related hypervisor manager. See Managing the resource
access control list on page 319 for more information about resource access
permissions.
About this task
To remove an operational repository from the Virtual Image Library resource tree,
perform the following steps:
316 IBM SmartCloud Orchestrator 2.3: User's Guide
Procedure
1. Select the hypervisor manager in the Operational Repositories tree.
2. Click on the toolbar.
Note: In Virtual Image Library, you cannot remove an operational repository
related to a cloud created in OpenStack.
3. Click OK.
Results
The hypervisor manager and all the repositories it contains are removed from the
resource tree. All information about the images contained in the repositories you
are removing is deleted from the Virtual Image Library database.
Indexing an image
Analyze the content of the virtual images and the deployed virtual machines
contained in an operational repository to store the related information in the
Virtual Image Library database.
About this task
The basic indexing operation collects and stores information about the operating
system and the software products running on the virtual image or on the deployed
virtual machine.
In addition to what the basic indexing operation does, the full indexing operation
analyzes every file and directory in the virtual image or machine and stores the
related information in the image library database.
An image is automatically full indexed when it is imported or copied to the
reference repository.
When you add an operational repository, the virtual images contained in the
repository are automatically basic indexed.
To index a virtual image or a deployed virtual machine, perform the following
steps:
Note: Indexing of Openstack VMs is supported on VMware Regions only. Images
and VMs from VMControl regions cannot be indexed.
Procedure
1. In the Images tab, navigate to the operational repository containing the virtual
image or machine to index.
2. In the repository view, click the Virtual Images or the Deployed VMs tab.
3. Select the virtual image or machine that you want to index.
Alternatively, click the name of the virtual image or machine. The related view
is displayed in a tab. From this view you can perform the same action.
Note: Before indexing a deployed virtual machine, ensure that the virtual
machine is powered off.
Chapter 5. Managing virtual images 317
4. Click Actions > Start Full Indexing or Actions > Start Basic Indexing. You
must index the virtual images and machines that you want to compare and the
virtual images and machines for which you want to find similar images or
machines.
You can track the status of the task you submitted in the task pane displayed in
the lower part of the window.
Results
The information related to the virtual image or machine is now stored in the
Virtual Image Library database.
Enabling the Keystone user registry
You can enable the Keystone user registry in Virtual Image Library.
To enable the Keystone user registry, run the following command:
/home/library/enableKeystoneRegistry.sh -u <vilAdminName> -p <vilAdminPassword> -e <true|false>
-k <protocol:keystoneURL:port> -ku <admin_user> -kp <admin_password> -kt <admin_tenant>
where
-u <vilAdminName>
Specifies the Virtual Image Library administrator ID to be used during the
installation.
-p <vilAdminPassword>
Specifies the Virtual Image Library administrator password.
-e <true|false>
True to enable registry. False to disable registry.
-k <protocol:keystoneURL:port>
Specifies the Keystone service base URL.
-ku <admin_user>
Specifies the Keystone administrative user.
-kp <admin_password>
Specifies the password for Keystone administrative user.
-kt <admin_tenant>
Specifies the Keystone administrative tenant password.
Then from the Virtual Image Library user interface, run the action Synchronize
User and Group List twice. The first time the task goes into a cancelled state at
20% as the application is restarted. The second time, it completes successfully.
Managing Virtual Image Library
Learn how to perform tasks to manage your virtual images and deployed virtual
machines in Virtual Image Library.
318 IBM SmartCloud Orchestrator 2.3: User's Guide
Managing the resource access control list
Allow access to an image or any other Virtual Image Library resource only to users
or to groups of users that actually need to perform operations on the specific
resource.
About this task
In Virtual Image Library, an access control list is associated to each resource so
users or group of users can perform operations on the resource.
To modify the access control list related to a Virtual Image Library resource,
perform the following steps:
Procedure
1. In the Images tab, click a resource in the All Resources tree.
2. In the Summary tab related to the selected resource, you can see the resource
access control list in the Access granted to section. The type of granted access
is specified on the right of each user or group in the list and it can be one of
the following:
user The user or any user in the group can perform any action allowed by
the associated role on the resource.
owner The user or any user in the group can modify the resource access
control list in addition to perform any action allowed by the associated
role on the resource.
For additional information about user roles, see User roles and requirements
on page 312.
When an operational repository is added to Virtual Image Library, the owner
access to the repository and to all the related resources is granted to the user
who added the repository. The user access to the repository and to all the
related resources is granted to the Everyone group.
Note: If you upgraded Virtual Image Library from the previous version, the
owner access to all the repositories that were added before upgrading and to
all the related resources is granted to the Everyone group.
3. To modify the access type for a user or a group, click the access type on the
right of the user or group name. If the access type is user, it is changed to
owner, and vice versa.
Note: When you modify the access type to the selected resource for a user or a
group, the change is applied to all the nested resources in the resources tree.
For example, if you modify the access type to a repository, the same change is
applied to all the virtual images and the deployed virtual machines contained
in the repository.
4. To add a user or a group to the access control list, type the user or group name
in the Search field and select it in the displayed list.
The list contains all the users and groups available in the Virtual Image Library
environment and is periodically refreshed. If you want to refresh the list
immediately, click Actions > Synchronize User and Group List on the resource
tree toolbar in the Images tab.
Note: If you recently assigned a Virtual Image Library role to a group, the
group name might be displayed twice in the list of the available users and
Chapter 5. Managing virtual images 319
groups. To correct the list, click Actions > Synchronize User and Group List
on the resource tree toolbar in the Images tab.
The user or group is added to the access control list with user access.
Note: When you add a user or a group to the access control list of the selected
resource, the user or group is also added to the access control list of all the
nested resources and of all the resources from the parent resource to the related
root resource. In the reference repository the access control list is only related to
virtual images. For example, if you add a user to the access control list of a
repository, the user is added also to the access control list of the following
resources:
v All the virtual images and the deployed virtual machines contained in the
repository
v The parent location
v The related hypervisor manager
5. To remove a user or a group from the access control list, click remove on the
right of the user or group name. You cannot remove all the users or groups
from the access control list.
Note: When you remove a user or a group from the access control list of the
selected resource, the user or group is also removed from the access control list
of all the nested resources in the resources tree. For example if you remove a
user from the access control list of a repository, the user is also removed from
the access control list of all the virtual images and the deployed virtual
machines contained in the repository.
Results
The resource access control list has been modified.
Copying an image to the reference repository
Check in a virtual image or a deployed virtual machine from an operational
repository to the reference repository to locally store a copy of your image or
machine or to replicate it to another operational repository.
About this task
To copy a virtual image or a deployed virtual machine from an operational
repository to the reference repository, perform the following steps:
Procedure
1. In the Images tab, navigate to the operational repository that contains the
virtual image or machine to copy.
2. In the repository view, click Virtual Images or Deployed VMs.
3. Select the virtual image or machine that you want to copy.
Alternatively, click the name of the virtual image or machine. The related view
is displayed in a tab. From this view you can perform the same action.
Note: If you select a deployed virtual machine in a VMware or VMControl
repository, ensure that the virtual machine is powered off before checking in
the image.
320 IBM SmartCloud Orchestrator 2.3: User's Guide
4. Click . The Check in Virtual Image or the Check in Deployed VM dialog
is displayed.
5. Enter a name to identify the image in the reference repository. You can also
enter an image description and comments.
6. Specify the version chain to which the image will be connected. You can start a
new version chain or connect the image to an existing chain. By default the
image is connected to a specific version chain depending on the image
relationship, if it exists, with the other images already stored in the reference
repository. For more information about the version chain, see Tracking image
version and provenance on page 323.
7. Click OK.
You can track the status of the task you submitted in the task pane displayed in
the lower part of the window. In addition to the checking-in task, a task to full
index the image is also submitted.
Results
The image is now in the reference repository and it is full indexed. The image is
also added to the specified version chain and a version number is assigned to it.
Importing an image
Import a local virtual image into the reference repository to perform image
management operations on the imported image.
Before you begin
If you are running a version of Virtual Image Library prior to version 2.1, before
importing an OVA image, ensure that you correctly set the WebSphere Application
Server class loader policy, as described in Configuring WebSphere Application
Server on page 337. In versions 2.1 and higher, this configuration is set by default.
About this task
To import a local virtual image, perform the following steps:
Procedure
1. In the Images tab, navigate to the Reference Repository.
2. In the reference repository view, click Virtual Images.
3. Click Actions > Import Image in the action toolbar. The Import Image to the
Reference Repository dialog is displayed.
4. Select the file name of the virtual image you want to import. The following
types of image file are supported:
v .raw
v .vmdk
v .ova (only contains disk files of one of the previously listed supported types)
By default, the virtual image files must be stored in the /home/library/imlib/
import directory in the Virtual Image Library server. You can change this value
by setting the import.directory parameter in the /etc/imageLibrary/
library.properties file in the Virtual Image Library server.
Note: To import a vmdk virtual image, the following files must be stored in the
import directory:
Chapter 5. Managing virtual images 321
v virtual_image_filename.vmdk
v virtual_image_filename-flat.vmdk
where virtual_image_filename is the name of the virtual image file that you want
to import.
5. Enter a name to identify the image in the reference repository. You can also
enter an image description and comments.
6. Click OK.
You can track the status of the task you submitted in the task pane displayed in
the lower part of the window. In addition to the importing task, a task to full
index the image is also submitted.
Results
The virtual image is now in the reference repository and is full indexed. The image
is also added to a version chain that has the same name as the image and a
version number is assigned to it.
Copying an image from the reference repository
Copy a virtual image from the reference repository to an operational repository to
manage the image in different repositories or in different virtualization
technologies.
Before you begin
To modify the default check out time in Virtual Image Library, see Modifying the
default check out settings on page 337.
Note: A user in a non-default domain cannot copy an imported image from the
reference repository to an operational repository. Because images imported by
users in a non-default domain are not visible to users in the default domain, you
must guarantee the access to the image to a user in the default domain before you
can copy it from the reference repository.
About this task
Note: If you move a Linux image from KVM to VMware or vice versa, the final
image might have problems starting, if, in /etc/fstab, it is using:
v /dev/sda1 for VMware
v /dev/vda1 for KVM
For Linux images that are internally using a disk name in /etc/fstab, moving
these images from KVM to VMware or vice versa, the disk name changes from
/dev/vda1 to /dev/sda1 and vice versa. To avoid complications, modify the images
before migrating them or modify the fstab file after migration.
To copy a virtual image from the reference repository to an operational repository,
perform the following steps:
Procedure
1. In the reference repository view, click the Virtual Images tab and select the
image you want to copy. Make sure that the image indexing is completed by
checking the Indexing State column, before proceeding to the next step.
2. Click . The Check out Virtual Image dialog is displayed.
322 IBM SmartCloud Orchestrator 2.3: User's Guide
3. Specify a name for the image in the target operational repository.
4. Select the hypervisor manager, the location, and the operational repository
where you want to copy the image. You can also enter an image description
and comments. Select the target image format for OpenStack images. Your
options are RAW, VHD ,VMDK, VDI, QCOW2, ISO, AKI, ARI, and AMI. For
VMware, the only target image format is VMDK.
5. Click OK.
You can track the status of the task you submitted in the task pane displayed in
the lower part of the window.
Results
The virtual image is now copied to the operational repository you specified.
In the version chain, a new branch is created for the virtual image that was copied
and a version number is assigned to the image to identify it with this branch.
Removing an image from the reference repository
Remove a virtual image from the reference repository.
About this task
If you delete an image, it is removed from both Virtual Image Library and on the
disk, freeing up disk space. You can also enable secure delete, which means that
before removing the image from the disk, the file is filled by empty spaces.
Note: An image in the reference repository is stored on the filesystem of one or
more of the connected proxies. If a proxy is unavailable when the image is
removed, the remove task completes successfully but the disk space on the
unavailable proxy file system is not freed until the proxy is started.
To remove a virtual image from the reference repository, add a property to
following file: /opt/p2pdiff/TransferClient/GlobalTracker.properties. The
property to add is:
secureDelete=true
Results
The virtual image is now removed from the reference repository.
Tracking image version and provenance
Check how the virtual image or deployed virtual machine was created and its
relationship with the other images and machines in the repository.
About this task
To track the versions and the provenance of a virtual image or machine, perform
the following steps:
Procedure
1. In the Images tab, navigate to the repository containing the virtual image or
machine to track.
2. In the repository view, click Virtual Images or Deployed VMs.
Chapter 5. Managing virtual images 323
3. Click the image or machine that you want to track. The image or machine view
is displayed in the related tab.
4. Click Version.
Results
If you selected an image in the reference repository, you see the Version Chain
pane and the Family Tree pane. If you selected a virtual image or machine in an
operational repository, you see only the Family Tree pane.
In the Version Chain pane, you see a graphical representation of the relationship
among the different versions of the image depending on the criteria used when the
image is checked in or imported into the reference repository.
The version numbers that are assigned to the virtual images in the reference
repository are of the form 1.x where x is a number that increases every time a
virtual image is added to the version chain. When a virtual image is checked out
from the reference repository, a branch is created and a version of the form 1.x.y is
assigned to the checked-out virtual image, where 1.x is the version number of the
virtual image in the reference repository, and y is a number representing the
branch that is increased by 1 for each new branch.
For example, the first time that the image with version number 1.8 is checked out
from the reference repository, version number 1.8.1 is assigned to the checked-out
image. The second time that the image with version number 1.8 is checked out
from the reference repository, version number 1.8.2 is assigned to the checked-out
image.
When a checked-out image is used to create a deployed virtual machine, a version
number of the form 1.x.y.z is assigned to the deployed virtual machine, where 1.x.y
is the version number of the checked-out image, and z uniquely identifies the
deployed virtual machine.
For example, the first time that the checked-out image with version number 1.8.2 is
used to deploy a virtual machine, the version number 1.8.2.1 is assigned to the
deployed virtual machine. In this way you can track both the virtual images and
the deployed virtual machines back to the specific image in the reference
repository that was used to create them.
You can decide the version chain to which the image is assigned during the
check-in operation. For more information about checking in an image, see
Copying an image to the reference repository on page 320.
You can also modify the version chains by moving the images to different version
chains, as described in Moving an image to a different version chain on page
325.
In the Version Chain pane, you can edit the version chain name, description, and
comments by clicking .
In the Family Tree pane, you see a graphical representation of the relationship
between the selected virtual images or machines and the other images or machines.
Relationships are established when an image is copied to create a new image,
checked in or checked out from the reference repository, and when the image is
used to deploy a virtual machine.
324 IBM SmartCloud Orchestrator 2.3: User's Guide
In the tree, the following icons are shown:
represents a virtual image in the reference repository
represents a virtual image in an operational repository
represents a deployed virtual machine
represents a virtual image or a deployed virtual machine that has been
deleted
If you click a virtual image or machine icon in the tree, the related image or
machine view is opened in a new tab and the related summary information is
displayed.
Moving an image to a different version chain:
Move a virtual image and all related child images to a new or different existing
version chain to better track the version history of your images depending on your
specific image management needs.
About this task
To move a virtual image to a different version chain, perform the following steps.
Note: You cannot move a virtual image to a different version chain while the
image is being indexed.
Procedure
1. Follow the procedure described in Tracking image version and provenance
on page 323 to display the Version Chain pane.
2. Click . The Move Reference Image dialog is displayed.
3. Specify if you want to start a new version chain by using the selected image as
the starting point or if you want to connect the selected image to a different
version chain.
4. Depending on your choice in the previous step, specify a name for the new
version chain or select an existing version chain in the list.
5. Click OK.
Results
The selected virtual image and all the related child images are moved to the
specified version chain. You can edit the version chain name, description, and
comments by clicking in the Version Chain pane.
Chapter 5. Managing virtual images 325
Searching for images
Search for a virtual image or a deployed virtual machine by specifying attributes
such as operating system or installed software.
About this task
To search for a virtual image or a deployed virtual machine, perform the following
steps.
Note: Searching for images by software products cannot be performed on SUSE
Linux images because Virtual Image Library cannot correctly detect the list of the
software installed on SUSE Linux images.
Procedure
1. In the Images tab, select an item in the resource tree as the scope of the search
operation. If you want to search in the entire resource tree, select All
Resources.
2. Click . A new Search tab opens.
3. Specify if you want to search only for virtual images, only for deployed virtual
machines, or for both of them. You can specify search criteria such as name,
description, guest OS, software products installed on the image or machine, or
the last modified time. Search fields takes regular expressions as input.
Note: To search for virtual images or machines using the installed software
products or patches as search criteria, the images or machines must be basic
indexed. For more information about indexing, see Indexing an image on
page 317.
4. Click Search.
Results
The search result is displayed in the Image Search Results pane. In this pane you
can select a virtual image or a deployed virtual machine in the related tab and
perform management actions on the image or machine that you selected.
Note: If you upgraded Virtual Image Library from version 1.2 and you specified
by software products as search criteria, the search result might not be correct if the
selected products had already been added to the Virtual Image Library 1.2
database.
Comparing images
Compare two virtual images or deployed virtual machines to find any differences
in files and products that they have installed.
About this task
To compare two virtual images or deployed virtual machines, perform the
following steps.
Note: Comparing images by products cannot be performed on SUSE Linux images
because Virtual Image Library cannot correctly detect the list of the software
installed on SUSE Linux images.
326 IBM SmartCloud Orchestrator 2.3: User's Guide
Procedure
1. In the Images tab, navigate to the repository containing the virtual image or
machine to compare.
2. In the repository view, click Virtual Images or Deployed VMs.
3. Select the first virtual image or machine to compare and click . The name
of the virtual image or machine is displayed in an information message in the
upper part of the window.
Note: You can compare only virtual images or machines that are indexed. If the
images or machines are basic indexed, you can compare them by software
products. If the images or machines are full indexed, you can compare them
also by files. For more information about indexing, see Indexing an image on
page 317.
4. Select the second virtual image or machine to compare by following the steps
from 1 to 3. The comparison tab opens.
5. In the comparison tab, select Products or Files and click Compare to see the
comparison result by products or files.
Results
In the comparison tab, you can view the list of differences in files, if the images are
full indexed, and products between the two selected virtual images or deployed
virtual machines.
Finding similar images
Find the percentage of similarity of a virtual image or a deployed virtual machine,
in terms of installed software and files, compared to the other images and
machines in your registered repositories.
About this task
To find similar virtual images or deployed virtual machines, perform the following
steps.
Note: Finding similar images by products cannot be performed on SUSE Linux
images because Virtual Image Library cannot correctly detect the list of the
software installed on SUSE Linux images.
Procedure
1. In the Images tab, navigate to the repository containing the virtual image or
machine for which you want to find similar images or machines.
2. In the repository view, click Virtual Images or Deployed VMs.
3. Select the virtual image or machine for which you want to find similar images
or machines.
Alternatively, click the name of the virtual image or machine. The related view
is displayed in a tab. From this view you can perform the same action.
Note: Only virtual images and machines that are indexed can be searched for
similarity. If the virtual images or machines are basic indexed, you can search
only images and machines similar for software products. If the virtual images
or machines are full indexed, you can also search images and machines similar
for files. For more information about indexing, see Indexing an image on
page 317.
Chapter 5. Managing virtual images 327
4. Click . A new Similar tab is displayed.
5. Specify if you want to show the similar images or machines by products or by
files and click Show Similar.
Results
All the indexed virtual images and deployed virtual machines are listed ordered by
percentage of similarity.
Synchronizing repositories
When the resources shown in Virtual Image Library on federated domains are
misaligned, missing virtual images, out of sync, or deployed virtual machines, run
Synchronize Repositories from the Virtual Image Library user interface.
Using the plug-in for vSphere Client
Integrate Virtual Image Library functions in your VMware vSphere Client by using
the related plug-in.
Before you begin
To install the plug-in for vSphere Client, ensure you have the Configuration
Librarian or the Administrator role. For more information about Virtual Image
Library roles, see User roles and requirements on page 312.
About this task
After a VMware vCenter has been added to your Virtual Image Library
environment, you can install the plug-in for the vSphere Client to perform Virtual
Image Library tasks from the vSphere Client user interface.
To install the plug-in for vSphere Client, perform the following steps:
Procedure
1. In the Virtual Image Library user interface, select the VMware hypervisor
manager in the Operational Repositories tree.
2. Click Actions > Install vSphere Client Plug-in. You can track the status of the
task you submitted in the task pane displayed in the lower part of the window.
Results
The plug-in for vSphere Client is installed.
Note: Ensure that Virtual Image Library, VMware vCenter Server, and vSphere
Client are able to correctly communicate among themselves. If the machine where
VMware vCenter Server is running has more than one NIC, ensure that VMware
vCenter Server uses the same NIC to communicate with both the vSphere Client
and Virtual Image Library. In addition to this, ensure that the machine where
vSphere Client is running is able to resolve the Virtual Image Library server host
name.
What to do next
You can run the following tasks from the vSphere Client user interface:
328 IBM SmartCloud Orchestrator 2.3: User's Guide
Launching the Virtual Image Library user interface
In the Home page, double-click the IBM Virtual Image Library icon in the
Solutions and Application section, to launch the Virtual Image Library user
interface inside the vSphere Client.
Copying a virtual machine or a template to the Virtual Image Library reference
repository
In the Inventory tree, right-click a virtual machine or a template and click
IBM Virtual Image Library > Copy to Reference Repository in the menu.
The virtual machine or template is copied to the reference repository as a
virtual image with the same name. You can track the status of the task you
submitted in the task pane displayed in the lower part of the window.
Indexing a virtual machine or a template
In the Inventory tree, right-click a virtual machine or a template and click
IBM Virtual Image Library > Start Basic Indexing or IBM Virtual Image
Library > Start Full Indexing in the menu. You can track the status of the
task you submitted in the task pane displayed in the lower part of the
window.
Note: Before indexing a virtual machine, ensure that it is powered off.
For more information about indexing, see Indexing an image on page
317.
Viewing the virtual machine or template details
In the Inventory tree, select a virtual machine or a template, and then click
the IBM Virtual Image Library Details tab to see the related deployed
virtual machine or virtual image view in Virtual Image Library.
Viewing the Virtual Image Library reference repository
In the Inventory tree, select a host, a datacenter, or a folder, and then click
the IBM Virtual Image Library Reference Repository tab to see the
reference repository view in Virtual Image Library. From this view, you can
also perform all the actions related to the reference repository.
Note: To launch the Virtual Image Library user interface and perform any Virtual
Image Library task, the credentials you used to log in to the vSphere Client must
be valid credentials in the Virtual Image Library environment. In addition to this,
you must have the required Virtual Image Library role to perform the specific task.
Note: vSphere Client uses the Internet Explorer browser to launch the Virtual
Image Library user interface. Ensure that you installed a supported version of
Internet Explorer as described in Accessing SmartCloud Orchestrator user
interfaces on page 135.
To uninstall the plug-in for vSphere Client, perform the following steps:
1. In the Virtual Image Library user interface, select the VMware hypervisor
manager in the Operational Repositories tree.
2. Click Actions > Uninstall vSphere Client Plug-in. You can track the status of
the task you submitted in the task pane displayed in the lower part of the
window.
3. When the uninstall task is completed, restart vSphere Client.
Chapter 5. Managing virtual images 329
Troubleshooting
Get troubleshooting guidance and information about known problems and
limitations.
If you encounter a problem with the Virtual Image Library component, perform
the following steps:
1. Ensure that the WebSphere application server is running. Check if there are any
errors in the /opt/IBM/WebSphere/AppServer/profiles/imageLibraryProfile/
logs/imageLibraryServer/SystemOut.log log file.
2. Ensure that HBase is correctly working by checking if there are any errors in
the log files in the /opt/hbase/logs directory.
3. Try to stop and restart the Virtual Image Library-related processes by running
the following commands:
/home/library/il.sh stop
/home/library/il.sh start
4. Review the other log files listed in Log files.
5. Review the known problems and limitations listed in Known problems and
limitations on page 333.
If you cannot find the cause of the problem, look for help on the IBM Support
website (http://www.ibm.com/support).
Log files
Review the following log files to recover from problems that you might encounter
when working with the Virtual Image Library component.
Note: To change the default values for log roll back, see the WebSphere
Application Server documentation at http://pic.dhe.ibm.com/infocenter/wasinfo/
v8r0/index.jsp.
v /opt/IBM/WebSphere/AppServer/profiles/imageLibraryProfile/logs/
imageLibraryServer/SystemOut.log
This is the main Virtual Image Library log file. Check this file for any
information about the product status and for any occurring error. To change the
logging options of the SystemOut.log file, perform the following steps:
1. Log on to the WebSphere Integrated Solutions Console with a web browser
by entering https://vil_hostname:9043/ibm/console, where vil_hostname is
the fully qualified domain name of the Virtual Image Library server. To log
on, specify the credentials of a Virtual Image Library administrator.
2. In the left pane, click Troubleshooting > Logs and trace.
3. In the Logging and tracing pane, click imageLibraryServer.
4. In the General Properties section, click JVM Logs.
5. In the General Properties section, specify the settings for the log file rotation
and the number of historical log files you want to store.
6. Click OK.
7. Click Save to save the changes to the master configuration.
8. To apply the changes, restart Virtual Image Library by issuing the following
commands:
/home/library/il.sh stop vil_admin_name vil_admin_password
/home/library/il.sh start vil_admin_name vil_admin_password
330 IBM SmartCloud Orchestrator 2.3: User's Guide
where vil_admin_name and vil_admin_password are the credentials of the
Virtual Image Library administrator you specified during the installation
procedure.
For more information about setting the logging options from the WebSphere
Integrated Solutions Console, see the WebSphere Application Server
documentation.
v /home/library/rbagent.log
/home/library/rbagent.trc
These are the log files for the rbagent component. Check these files in addition
to the SystemOut.log file for problems about operations related to the compare
images. To change the logging options of the rbagent.log and rbagent.trc files,
specify the following parameters in the /etc/imageLibrary/library.properties
file:
rbagent.logfilesize
Specifies the size (in MB) of each log file. The default value is 2.
rbagent.logfilenumber
Specifies the number of the rbagent.log files and the number of the
rbagent.trc files that are stored at run time. The default value is 3.
To apply the changes, restart Virtual Image Library by issuing the following
commands:
/home/library/il.sh stop vil_admin_name vil_admin_password
/home/library/il.sh start vil_admin_name vil_admin_password
where vil_admin_name and vil_admin_password are the credentials of the Virtual
Image Library administrator you specified during the installation procedure.
v /opt/hbase/logs
This is the log file of the HBase database used by Virtual Image Library to store
information about resources.
v /opt/origami/logs/origami.log
This is the log file for the origami component. For problems with image
management operations on the reference repository, check the log file on the
Virtual Image Library server. For problems related to image management to or
from an operational repository, for example, check in, check out, or indexing,
check the log file on the proxy that manages that hypervisor manager.
v On the Virtual Image Library server: /opt/p2pdiff/TransferClient/
globaltracker.out
If there is a check in, check out, or import to the reference repository, the error
depends on the p2pdiff.
v On the remote proxy: /opt/p2pdiff/TransferClient/agent.out
If there is a check in, check out, or import to the reference repository, the error
depends on the p2pdiff.
Chapter 5. Managing virtual images 331
Changing the time zone
If you are in the need of changing the time zone on the system where Virtual
Image Library runs, follow this procedure.
Procedure
1. Stop the Virtual Image Library service:
# service vil stop
2. Check the current time zone:
# date
You see something like this:
mar nov 13 14:53:56 CET 2012
where CET stands for Central European Time.
3. To change the time zone, check to see which time zones are available by
running the following command on the command-line interface:
# ls /usr/share/zoneinfo/
You see something like this:
[root@server ~]# ls /usr/share/zoneinfo/
Africa Asia Canada Cuba EST Factory GMT0 Hongkong Iran
Japan Mexico Navajo Poland PRC ROK Universal W-SU
America Atlantic CET EET EST5EDT GB GMT-0 HST iso3166.tab
Kwajalein Mideast NZ Portugal PST8PDT Singapore US zone.tab
Antarctica Australia Chile Egypt Etc GB-Eire GMT+0 Iceland Israel
Libya MST NZ-CHAT posix right Turkey UTC Zulu
Arctic Brazil CST6CDT Eire Europe GMT Greenwich Indian Jamaica
MET MST7MDT Pacific posixrules ROC UCT WET
4. Delete the current time zone:
rm /etc/localtime
5. Create a symbolic link to the new time zone file:
# ln s /usr/share/zoneinfo/America/New_York/etc/localtime
Synchronize the system clock to a Network Time Protocol (NTP) server. NTP is
a standard way of synchronizing computer clocks across a network. Using NTP
you can keep your servers clock synchronized with accurate atomic clocks
located around the world. Computer clocks tend to slowly become inaccurate,
so synchronize them regularly with NTP servers.
6. Synchronize to the NTP server:
# ntpdate <ntp server ip see ntp.conf>
7. Save your current time to your hardware clock:
# hwclock --systohc
or:
#hwclock --systohc utc
8. Start the Virtual Image Library service:
# service vil stop
332 IBM SmartCloud Orchestrator 2.3: User's Guide
Known problems and limitations
Review the following known problems and limitations you can encounter when
using the Virtual Image Library component.
Limitations:
Review the following list of limitations of the Virtual Image Library component.
v Only one Virtual Image Library can be installed and connected to your
SmartCloud Orchestrator environment.
v A Linux dpkg item in an image is not recorded as installed software for the
image in Virtual Image Library, because the dpkg format is not supported by the
indexing procedure.
v When an ESXi hypervisor is disconnected from the vCenter, all the virtual
images managed by the server become unavailable. You cannot index
unavailable images. To index the images, set the image status to available by
reconnecting the ESX hypervisor.
v If an ESXi hypervisor is disconnected from the vCenter, the changes you make
to the virtual images or to the deployed virtual machines on the ESXi hypervisor
might not be detected by Virtual Image Library when the ESXi hypervisor is
reconnected to the vCenter.
v Virtual Image Library cannot perform analytic operations and compatibility
checks on SUSE Linux images if the related devices are referenced by ID in the
/etc/fstab file. To correctly manage a SUSE Linux image, the related devices
must be referenced by device name or UUID. Compatibility checks are not
available anymore.
v Virtual Image Library cannot index Linux images containing an empty
/etc/HOSTNAME file, because of the Red Hat bug described at
https://bugzilla.redhat.com/show_bug.cgi?id=823821.
v In the Configure Options window, the changes you make to the layout of the
tables displayed in the user interface are reset to the default value when you
restart the browser.
v If you are using a browser in languages other than English, the Filter function in
the tables displayed in the user interface might not work correctly if you are
filtering for translated terms. Use the corresponding English term to correctly
filter the table items.
v Image conversion during check out is not supported.
v During OVA import, Virtual Image Library REST API waits for the operation to
complete. If you check the log files, you might see warnings about the thread
hanging. You can disregard these warnings because Virtual Image Library
resolves them automatically.
v Virtual Image Library does not support encrypted disk images.
v On VMware virtual machines, non-administrator users cannot partition the view
of deployed virtual machines when logging into the Virtual Image Library UI.
v For VMware images, Virtual Image Library is not able to specify if an image is
associated to a VMware cluster.
v If you are using a non-IBM OpenStack, because the virtual images are not
indexed, the following limitations apply in the Virtual Images tab of the
repository view:
The indexing state is listed as Not Indexed.
The virtual image architecture is listed as Unknown.
The OS version is empty.
Chapter 5. Managing virtual images 333
Cannot check in a deployed virtual machine:
A deployed virtual machine cannot be checked into the reference repository.
Symptoms
The following error is displayed:
COPIML830E Check in operation is not supported for the image image_name because
the image status is running. Only available images can be checked in.
Causes
The problem occurs because the virtual machine that you want to check in is still
running.
Resolving the problem
Power off the virtual machine before checking it into the reference repository.
Cannot connect to the HBase database:
Virtual Image Library cannot retrieve information from the HBase database.
Symptoms
If you open a Virtual Image Library user interface, the user interface hangs after
you log in.
The following errors are displayed in the SystemOut.log log file:
COPIML604E An error occurred while trying to load the object with type <object_type>
and universally unique identifier <object_UUID>.
...
Caused by: org.apache.hadoop.hbase.client.RetriesExhaustedException:
Trying to contact region server <server_name> for region <object_type>...
...
but failed after 10 attempts.
Exceptions:
java.net.ConnectException: Connection refused
...
COPIML605E An error occurred while trying to load all objects with type <object_type>.
Causes
The problem might occur because HBase is not working or HBase was stopped
and restarted.
Resolving the problem
Restart Virtual Image Library by running the following commands:
/home/library/il.sh stop
/home/library/il.sh start
NoClassDefFoundError exception:
After installing Virtual Image Library, the user interface cannot start and the
NoClassDefFoundError exception is displayed.
Symptoms
The following errors are displayed in the SystemOut.log log file:
SRVE0283E: Exception caught while initializing context: {0}
java.lang.ExceptionInInitializerError
...
Caused by: org.apache.hadoop.hbase.TableNotFoundException: domain
334 IBM SmartCloud Orchestrator 2.3: User's Guide
Causes
The problem might occur because the HBase tables were not created during the
Virtual Image Library installation procedure. To verify that tables were created:
/opt/hbase/bin/hbase shell and in the HBase shell type list.
Resolving the problem
Create the HBase tables by performing the following steps:
1. Check that the HBase service is running by running the following command:
ps -ef | grep hbase
If it is not running, start the HBase service by running the following command:
service hbase start
2. From the directory where you unpacked the Virtual Image Library installation
package, run the following command:
./create_il_tables.sh
3. Restart Virtual Image Library by running the following commands:
/home/library/il.sh stop
/home/library/il.sh start
rbagent component does not start:
When starting Virtual Image Library, the rbagent component does not start
successfully.
Symptoms
The following error is displayed in the /home/library/rbagent.log file:
A <INF> Packages not found at path local://root/home/library/rbagent.pak
Detecting network interfaces
Error raised by init in repository.rbc, line 182 [:0]
No such file or directory (Error during Local Repository initialization)
Causes
The problem may occur because the /tmp/tpmfiTemporaryRepository directory
does not exist.
Resolving the problem
Create the tpmfiTemporaryRepository subdirectory in the /tmp directory and try to
stop and restart the Virtual Image Library-related processes by running the
following commands:
/home/library/il.sh stop
/home/library/il.sh start
Error 404 - Too many open files:
Error 404 (Too many open files) is displayed in your browser.
Symptoms
The following error is displayed in your browser:
Error 404: javax.servlet.ServletException: java.io.FileNotFoundException:
/opt/IBM/Websphere/AppServer/profiles/ImageLibraryProfile/installed-Apps/
image-libraryNode01Cell/ImageManager.ear/ImageLibraryUIWeb.war/login.html
(Too many open files)
The following error is displayed in the SystemOut.log log file:
Chapter 5. Managing virtual images 335
00000031 webapp E com.ibm.ws.webcontainer.webapp.WebApp logServletError
SRVE0293E: [Servlet Error]-[Static File wrapper]:
com.ibm.wsspi.webcontainer.ClosedConnectionException:
OutputStream encountered error during write
If you try to run the il.sh command, the following error is displayed:
/home/library/il.sh: line 198: echo: write error: No space left on device
Stopping WebSphere Application Server server: imageLibraryServer
tee: /home/library/il_stop.log: No space left on device
Causes
The problem occurs because there is no enough space available on the file system
in the machine where Virtual Image Library is running.
Resolving the problem
Free some space on the file system and restart Virtual Image Library by running
the following commands:
/home/library/il.sh stop
/home/library/il.sh start
Cannot create HBase tables:
The creation of HBase table of Virtual Image Library does not complete.
Symptoms
The creation of HBase table does not complete.
Resolving the problem
The workaround is:
1. Log in to the PXE Server.
2. Do:
cd /tmp
service hbase start
3. Check that there is a class called HBaseTableCreator in /tmp
./create_il_tables.sh.
4. To verify that tables are created:
/opt/hbase/bin/hbase shell
and in the HBase shell type list.
Disk space lower than the safe threshold value:
The threshold value of 250M of available space on the filesystem for the HBASE
database has been reached. Cannot work with Virtual Image Library anymore.
Symptoms
The HBASE service is stopped. Each request fails with the message: COPIML010E
Disk space is lower than the safe threshold value. Check your file system
and add disk space before proceeding.
Resolving the problem
Run the "df -m /opt/hbase" command. Add enough space to the related file
system and restart the Virtual Image Library service.
336 IBM SmartCloud Orchestrator 2.3: User's Guide
Configuring WebSphere Application Server:
If you want to import OVA files into the Virtual Image Library reference repository,
configure the WebSphere Application Server class loader policy.
About this task
If the image import from an OVA file fails immediately, check the configuration of
the WebSphere Application Server class loader policy. To configure the WebSphere
Application Server class loader policy, complete the following steps:
Procedure
1. Log on to the WebSphere Integrated Solutions Console with a web browser by
entering https://vil_hostname:9043/ibm/console, where vil_hostname is the
fully qualified domain name of the Virtual Image Library server. To log on,
specify the credentials of the Virtual Image Library administrator you specified
during the installation procedure (wasadmin/passw0rd by default in the
SmartCloud Orchestrator installation).
2. In the left pane, click Applications > Application Types > WebSphere
enterprise applications.
3. In the Enterprise Applications pane, click ImageManager.
4. In the Modules section, click Manage Modules.
5. In the module table, click ImageLibrary.
6. In the Class loader order list, select Classes loaded with local class loader first
(parent last).
7. Click OK to confirm your changes.
8. Click Save to save the changes to the master configuration.
9. Restart Virtual Image Library by issuing the following commands:
/home/library/il.sh stop
/home/library/il.sh start
Results
You can now import OVA files into the reference repository. For more information
about importing images, see Importing an image on page 321.
Modifying the default check out settings:
You can modify the default check out settings of Virtual Image Library.
About this task
The default check out time in Virtual Image Library is two minutes. You might
want to modify this time to extend it, for example if you want to install a tool that
takes longer than two minutes. To modify the default check out time, perform the
following steps:
Procedure
1. Edit the /etc/imageLibrary/library.properties on the Virtual Image Library
server.
2. Add the following line, for example if you want to increase the default time of
two minutes to five minutes:
Seconds.between.start.and.stop.vmware.image=300
Chapter 5. Managing virtual images 337
where 300 is the amount of seconds you want the check out time to be.
3. Restart Virtual Image Library.
Image checkout fails:
Image check out fails in Virtual Image Library.
Symptoms
Image check out fails with an error similar to: COPIML842E The check-out
operation failed while trying to create a virtual image. ERROR:
com.vmware.vim25.FileAlreadyExists. Cannot complete the operation because
the file or folder [Shared_ESXi] OVA for vApp/disk1.vmdk already exists
Causes
VMware initially creates a folder on the datastore, to host the image files, and then
returns an ID to the caller, identifying the created VM. If something goes wrong
with this step, for example missing disk space, the folder has already been created,
but the VM creation fails and no ID is assigned to that resource because it does not
exist yet.
Resolving the problem
On the vSphere client, browse the datastore and remove the existing empty folder,
so that the next time a VM with the same name is created, the operation does not
fail. The error message returned by Virtual Image Library contains the path in the
datastore to identify which existing folder must be removed.
Domain status is out of sync:
Domain status appears as out of sync.
Symptoms
In the Summary tab of the domain view in the Virtual Image Library user
interface, the domain status appears as out of sync and is not updated the next
time the domain updater runs.
Causes
An error occurs when the domain updater runs.
Resolving the problem
Determine what is wrong with the domain being discovered and why the update
fails to detect changes, for example, there might be a problem with one of the
images, the user credentials, or network connectivity. You must correct the problem
so that this problem does not occur again.
After you have determined the problem, manually run a resynchronization by
clicking Synchronize Repositories in the Virtual Image Library user interface.
338 IBM SmartCloud Orchestrator 2.3: User's Guide
New region, new repository, or new image does not appear:
New region, new repository, or new image does not appear and you receive an
error in systemout.log.
Symptoms
A new region does not appear, or, in an update, a new repository or new image
does not appear. In the systemout.log file, you see the following error:
[10/5/13 12:02:15:127 EDT] 00000035 HConnectionMa I
org.apache.hadoop.hbase.client.HConnectionManager$HConnectionImplementation abort
This client just lost its session with ZooKeeper, trying to reconnect.
Causes
There is an issue with HBase and Virtual Image Library cannot store new data.
Resolving the problem
To solve this issue, ensure that HBase is running by entering the following
commands. The - list command returns the list of available HBase tables.
v - hbase shell
v - list
v - quit
If you receive no errors or warning messages, you can run a manual
synchronization from the Virtual Image Library UI. Select the operational
repository that was not updated and click Action > Synchronize Repository.
Virtual Image Library fails with message java.lang.NoClassDefFoundError:
Virtual Image Library fails with message java.lang.NoClassDefFoundError.
Symptoms
Virtual Image Library fails with message java.lang.NoClassDefFoundError.
Causes
This error might occur if the HBase service is not available when Virtual Image
Library starts.
Resolving the problem
You can attempt to fix the problem by running the following command:
"/home/library/recover_hbase.sh fix"
After HBase is active, Virtual Image Library recovers the connection automatically.
After moving a Linux image, you have problems starting the image:
If you move a Linux image from KVM to VMware or vice versa, the final image
might have problems starting.
Symptoms
Moving a Linux image from KVM to VMware or vice versa, the final image has
problems starting if, in /etc/fstab, it is using:
v /dev/sda1 for VMware
v /dev/vda1 for KVM
Chapter 5. Managing virtual images 339
Causes
This problem is related to any Linux images that are internally using a disk name
in /etc/fstab. Moving these images from KVM to VMware or vice versa, the disk
name changes from /dev/vda1 to /dev/sda1 and vice versa.
Resolving the problem
Modify the images before migrating them or modify the fstab file after migration.
REST API reference
Get information about using the Representational State Transfer (REST) application
programming interface (API) for Virtual Image Library.
The REST API provides you with the ability to access the image library services
from external applications.
REST is an architecture used to create stateless web services that are typically
accessed using the HTTP protocol. Software developed using this architecture is
considered to be RESTful. There are only four HTTP methods that you use to
interact with the API: GET, POST, PUT, and DELETE. Any client program that can
transmit network messages using HTTP can use the API, regardless of
programming language. Image Library REST APIs are accessed using the HTTPS
protocol.
A concept central to RESTful web services is resources. A RESTful resource is any
object or action that can be addressable using a Uniform Resource Identifier (URI).
URLs, as used on the Web, are a type of URI, where the page or web service
identified by the URL is the resource.
The table below describes the basic function of the HTTP methods used in the
REST API:
HTTP Method Description
GET Return information about the resource in the
body of the HTTP response.
PUT Update the resource if it already exists based
on information passed in the body of the
HTTP request. An HTTP response code of
404 is returned if the resource does not exist.
POST Create a new instance of a resource based on
information passed in the body of the HTTP
request.
DELETE Remove the resource.
340 IBM SmartCloud Orchestrator 2.3: User's Guide
ImageManager API reference
Get information about using the ImageManager application programming interface
(API) for Virtual Image Library.
Administration REST API:
Return the number of available resources
GET /admin/resourceCount
Example URL
https://localhost:9443/ImageLibrary/ImageLibrary/admin/resourceCount
Response content-type
application/json
Response example
{
"numberOfDeployedVirtualMachines":37,
"numberOfOperationalVirtualImages":19,
"numberOfOperationalRepositories":1,
"numberOfReferenceAndOperationalVirtualImages":3
}
Return the supported virtualization types
Returns all the supported virtualization types defined in the /etc/imageLibrary/
library.properties file
GET /admin/VirtualizationTypes
Example URL
https://localhost:9443/ImageLibrary/ImageLibrary/admin/
VirtualizationTypes
Response content-type
application/json
Response example
[{"type":"OpenStack","name":"OpenStack"},
{"type":"VMware","name":"VMware Virtual Center"}]
Return information about the environment
GET /admin/environment
Example URL
https://localhost:9443/ImageLibrary/ImageLibrary/admin/environment
Response content-type
application/json
Response example
{"image.library.release":"1",
"image.library.version":"2",
"os.name":"Linux",
"image.library.build":"327",
"os.architecture":"x86",
"user.name":"wasadmin",
"os.version":"2.6.32-131.0.15.el6.x86_64"}
Chapter 5. Managing virtual images 341
Return the list of virtual disk images in the import directory
Returns only the virtual disk images of the supported types. See Importing an
image on page 321 for more information about supported types of image file.
GET /admin/VirtualDiskNames
Example URL
https://localhost:9443/ImageLibrary/ImageLibrary/admin/
VirtualDiskNames
Response content-type
application/json
Response example
{"import.directory":"/home/library/imlib/import",
"virtual.disk.names":
["RHEL_ICON_Build275_Rev4023.ova",
"test2.vmdk",
"fedora14-32bit-1g.raw",
"deb-1g.raw"]}
Set configuration properties
PUT /admin/ConfigurationProperty
Example URL
https://localhost:9443/ImageLibrary/ImageLibrary/admin/
ConfigurationProperty
Request content-type
application/json
Request parameters
A JSON object in the HTTP body:
{
"name" : "propertyName",
"value" : "propertyValue"
}
Success code
204
Disconnect emulated disks
Disconnects the emulated disks in the /tmp directory and removes the
emulated-.tpm directories.
POST /admin/VMware/DisconnectEmulatedDisks
Example URL
https://localhost:9443/ImageLibrary/ImageLibrary/admin/VMware/
DisconnectEmulatedDisks
Request content-type
application/json
Success code
204
342 IBM SmartCloud Orchestrator 2.3: User's Guide
Analytics REST API:
Compare the files contained in two images
GET /analytics?function=compareImageFiles&imageA=<imageA_UUID>&imageB=<imageB_UUID>
Example URL
https://localhost:9443/ImageLibrary/ImageLibrary/
analytics?function=compareImageFiles&imageA=<imageA_UUID>
&imageB=<imageB_UUID>
Request parameters
imageA that is the UUID of the first image to compare
imageB that is the UUID of the second image to compare
Response content-type
application/json
Response example
{
"removed":
[{"file":"\/.dbus\/"},...,{"file":"\/var\/yp\/nicknames"}],
"added":
[{"file":"\/"},...,{"file":"\/var\/yp"}],
"modified":
[{"file":"\/bin\/arch"},...,{"file":"\/var\/run\/utmp"}]
}
Compare the products installed in two images
GET /analytics?function=compareImageProducts&imageA=<imageA_UUID>
&imageB=<imageB_UUID>
Example URL
https://localhost:9443/ImageLibrary/ImageLibrary/
analytics?function=compareImageProducts&imageA=<imageA_UUID>
&imageB=<imageB_UUID>
Request parameters
imageA The UUID of the first image to compare
imageB The UUID of the second image to compare
Response content-type
application/json
Response example
{
"removed":
[{"architecture":"x86_64","product":"busybox"},
...,
{"architecture":"x86_64","product":"pulseaudio-gdm-hooks"}],
"added":
[{"architecture":"","product":"activate-ntp-client"},
...,
{"architecture":"","product":"activation-engine-libxml2-python"}],
"modified":
[{"architecture":"noarch","product":"kbd-misc"},
...,
{"architecture":"x86_64","product":"newt-python"}}]
}
Chapter 5. Managing virtual images 343
Compare the properties for two images
GET /analytics?function=compareImageProperties&imageA=<imageA_UUID>
&imageB=<imageB_UUID>
Example URL
https://localhost:9443/ImageLibrary/ImageLibrary/
analytics?function=compareImageProperties&imageA=29bfd583-b014-43f9-
9300-a4c4018f32b9&imageB=92541f8e-4752-4ca3-ba42-6af3c7cbde94
Request parameters
imageA that is the UUID of the first image to compare
imageB that is the UUID of the second image to compare
Response content-type
application/json
Response example
{"modified":
[{"newValue":"1906257920","item":"totaldiskspace","oldValue":"7739864"},
{"newValue":"713150464","item":"useddiskspace","oldValue":"2987620"},
{"newValue":"1193107456","item":"availablediskspace","oldValue":"4752244"}]}
Return the properties of an image
GET /analytics?function=describeImageProperties&imageUUID=<image_UUID>
Example URL
https://localhost:9443/ImageLibrary/ImageLibrary/
analytics?function=describeImageProperties&imageUUID=29bfd583-b014-
43f9-9300-a4c4018f32b9
Request parameters
imageUUID
Response content-type
application/json
Response example
{"analyticsimageuuid":"https:\/\/2.zoppoz.workers.dev:443\/http\/origami.research.ibm.com\/images\
/86e238fc-d1d7-4e53-b759-0de06738737a",
"availablediskspace":"4752244",
"architecture":"x86_64",
"osversion":"6.1",
"totaldiskspace":"7739864",
"imageuuid":"29bfd583-b014-43f9-9300-a4c4018f32b9",
"osdistribution":"rhel",
"useddiskspace":"2987620",
"ostype":"linux"}
Find images
GET /analytics?function=findImages[&name=<image_name>][&description=<description>]
[&imageType=template|instance][virtualizationType=VMware|HSLT]
[lastModifiedStart=<start_time>][lastModifiedEnd=<end_time>]
[&analytics-query=<analytics_query>]
Example URL
https://localhost:9443/ImageLibrary/ImageLibrary/
analytics?function=findImages&imageType=template&name=redhat
&analytics-query=(ostype:linux)AND((software:abrt)AND(software:bash))
Request parameters
name
344 IBM SmartCloud Orchestrator 2.3: User's Guide
description
imageType that is template or instance
virtualizationType that is VMware or HSLT
lastModifiedStart
lastModifiedEnd
analytics-query that is a query related to the following attributes:
software
Specifies the software installed on the image. You can specify more
than one software attribute by using the AND operator.
ostype Specify the image OS type.
Response content-type
application/json
Response example
A JSON array containing a UUID for each image that matches the search criteria:
["c4a727c1-9fcc-4188-8f0a-9d168983a85c",
"15cb1e8c-26c3-471c-9401-4ec9a638c75f",
"50fb2a7a-2ab9-4c92-b04f-46f47c2ccd17"]
Find images with detailed information
GET /analytics?function=findImagesVerbose[&name=<image_name>]
[&description=<description>][&imageType=template|instance]
[virtualizationType=VMware|HSLT]
[lastModifiedStart=<start_time>][lastModifiedEnd=<end_time>]
[&analytics-query=<analytics_query>]
Example URL
https://localhost:9443/ImageLibrary/ImageLibrary/
analytics?function=findImagesVerbose&imageType=template&name=redhat
&analytics-query=(ostype:linux)AND((software:abrt)AND(software:bash))
Request parameters
name
description
imageType that is template or instance
virtualizationType that is VMware or HSLT
lastModifiedStart
lastModifiedEnd
analytics-query that is a query related to the following attributes:
software
Specifies the software installed on the image. You can specify more
than one software attribute by using the AND operator.
ostype Specify the image OS type.
Response content-type
application/json
Response example
Chapter 5. Managing virtual images 345
A JSON array containing the following object for each image that matches the
search criteria:
{
locationName: "Test Environment v41"
usage: "persistentInstance"
indexingState: "notIndexed"
indexedOn: 12345567
os: "LINUX"
hardware: {
virtualSystemType: "vmx-07"
devices: [
{
mappingBehavior: 0
caption: "CPU"
elementName: "CPU"
consumerVisibility: 0
resourceType: 3
automaticAllocation: true
automaticDeallocation: true
reservation: 0
allocationUnits: "hertz"
instanceID: 1
virtualQuantity: 2
weight: 2000
limit: -1
description: "2"
}
{
mappingBehavior: 0
caption: "Memory"
elementName: "Memory"
consumerVisibility: 0
resourceType: 4
automaticAllocation: true
automaticDeallocation: true
reservation: 0
allocationUnits: "bytes"
instanceID: 2
virtualQuantity: 4294967296
weight: 40960
limit: -1
description: "4096.0 MB"
}
{
mappingBehavior: 0
caption: "Hard disk 1"
elementName: "Hard disk 1"
consumerVisibility: 0
resourceType: 17
parent: 1000
automaticAllocation: true
automaticDeallocation: true
repositoryIDs: [
"datastore-189"
]
allocationUnits: "bytes"
instanceID: 2000
virtualQuantity: 85899345920
hostResource: [
"[test4] att-redhat-itds.torolab.ibm.com/att-redhat-itds.torolab.ibm.com.vmdk"
]
description: "80.0 GB"
addressOnParent: 0
}
{
mappingBehavior: 0
346 IBM SmartCloud Orchestrator 2.3: User's Guide
caption: "Network adapter 1"
elementName: "Network adapter 1"
consumerVisibility: 0
resourceType: 10
parent: 100
automaticAllocation: true
resourceSubType: "E1000"
automaticDeallocation: true
instanceID: 4000
address: "00:50:56:98:00:10"
description: "VM Network"
addressOnParent: 7
connection: [
"VM Network"
]
}
]
}
name: "att-redhat-itds.torolab.ibm.com"
domainName: "tiv-vsphere41"
locationUUID: "d4b02df3-d34f-4b0b-9853-4cd38e035e7e"
state: "available"
virtualizationType: "VMware"
architecture: "INTEL_X86_64"
osVersion: "Red Hat Enterprise Linux 5 (64-bit)"
imageID: "vm-323"
updated: 1315477636803
uuid: "560c826c-c059-4d55-8743-a8f89e592fc8"
"ownerList":[{"name":"Everyone","uuid":"ed881bac-6397-3de3-bc0a-285c9f50bb83"},
"groupUUIDList":[],"isUser":false}],
"accessList":[{"name":"Everyone","uuid":"ed881bac-6397-3de3-bc0a-285c9f50bb83"},
"groupUUIDList":[],"isUser":false}],
description: null
domainUUID: "dc4c3466-3b8c-40a7-8097-45bbc7139c7f"
imagePortabilityStatus:"partial"
"imagePortabilityChecker":
[{"checkerName":"DHCP","checkerStatus":"notPassed"},
{"checkerName":"HostnameFileLinux",
"checkerStatus":"notPassed"}]
}
List all the image properties
GET /analytics?function=listAllImageProperties
Example URL
https://localhost:9443/ImageLibrary/ImageLibrary/
analytics?function=listAllImageProperties
Response content-type
application/json
Response example
[analyticsimageuuid, imageuuid, ostype, osdistribution, osversion, architecture,
totaldiskspace, useddiskspace, availablediskspace]
List the products installed on an image
GET /analytics?function=listImageProducts&imageUUID=<image_UUID>
Example URL
https://localhost:9443/ImageLibrary/ImageLibrary/
analytics?function=listImageProducts&imageUUID=92541f8e-4752-4ca3-
ba42-6af3c7cbde94
Chapter 5. Managing virtual images 347
Request parameters
imageUUID
Response content-type
application/json
Response example
A JSON array containing the following object for each product installed on the
specified image:
{"architecture":"x86_64",
"howDiscovered":"s7\/RpmPackagesScanner",
"vendor":"Red Hat, Inc.",
"version":"1.1.16",
"product":"abrt"}
List the products in the Virtual Image Library knowledge base
GET /analytics?function=listKnownProducts
Example URL
https://localhost:9443/ImageLibrary/ImageLibrary/
analytics?function=listKnownProducts
Response content-type
application/json
Response example
A JSON array containing the following object for each product in the Virtual Image
Library knowledge base:
{"architecture":"x86_64",
"howDiscovered":"s7\/RpmPackagesScanner",
"vendor":"Red Hat, Inc.",
"version":"1.1.16",
"product":"abrt"}
List the files contained in an image
GET /analytics?function=listImageFiles&imageUUID=<image_UUID>
Example URL
https://localhost:9443/ImageLibrary/ImageLibrary/
analytics?function=listImageFiles&imageUUID=92541f8e-4752-4ca3-ba42-
6af3c7cbde94
Request parameters
imageUUID
Response content-type
application/json
Response example
A JSON array containing the following object for each file installed on the specified
image:
{"statInfo":"stat1","fileName":"path","digestValue":"stat2"}
348 IBM SmartCloud Orchestrator 2.3: User's Guide
Find similar images
Returns the images similar to the specified image with the similarity percentage
returned in the similarityMetric parameter.
GET /analytics?function=listSimilarImages&imageUUID=<image_UUID>
&comparisonType=[files|products]
Example URL
https://localhost:9443/ImageLibrary/ImageLibrary//
analytics?function=listImageProducts&imageUUID=92541f8e-4752-4ca3-
ba42-6af3c7cbde94&comparisonType=products
Request parameters
imageUUID
comparisonType that is files or products
Response content-type
application/json
Response example
A JSON array containing the following object for each image similar to the
specified image:
{"imagePortabilityStatus":"partial",
"provenanceVersionChainUUID":"36274f5e-71f4-46ed-a3cb-242d9a8e7236",
"repositoryUUID":"b18a149b-71d8-4b59-878e-1550dfa21cc5",
"name":"RHEL61-Test","state":"available",
"virtualizationType":"VMware",
"architecture":"INTEL_X86_64",
"osVersion":"Red Hat Enterprise Linux 6 (64-bit)",
"version":null,
"locationName":"CCS",
"usage":"image",
"indexingState":"partiallyIndexed",
"accessList":
[{"numberOfGroups":0,
"isUser":false,
"groupUUIDList":[],
"uuid":"ed881bac-6397-3de3-bc0a-285c9f50bb83",
"name":"Everyone",
"roles":[]},
{"numberOfGroups":0,
"isUser":true,
"groupUUIDList":[],
"uuid":"353dc07c-87fc-458e-bc03-44f097bf3a93",
"name":"wasadmin",
"roles":[]}],
"userVersionChainUUIDs":[],
"os":"LINUX",
"imagePortabilityChecker":
[{"checkerName":"NetworksFileLinux","checkerStatus":"passed"},
{"checkerName":"FstabFileEntryLinux","checkerStatus":"notPassed"}
,{"checkerName":"Disk_Device","checkerStatus":"passed"},
{"checkerName":"LVM_Disk","checkerStatus":"passed"},
{"checkerName":"SShServerConfigured","checkerStatus":"passed"},
{"checkerName":"Ifcfgeth0FileLinux","checkerStatus":"notPassed"},
{"checkerName":"RCLocalLinux","checkerStatus":"notPassed"},
{"checkerName":"Multiple_Disk","checkerStatus":"passed"},
{"checkerName":"HostsFileLinux","checkerStatus":"notPassed"},
{"checkerName":"SShServerInstalled","checkerStatus":"passed"},
{"checkerName":"WriteNetRulesFileLinux","checkerStatus":"notPassed"}],
"hardware":
{"virtualSystemType":"vmx-07",
Chapter 5. Managing virtual images 349
"devices":
[{"mappingBehavior":0,"caption":"CPU","elementName":"CPU","consumerVisibility":0,
"resourceType":3,"automaticAllocation":true,"automaticDeallocation":true,
"reservation":0,"allocationUnits":"hertz","instanceID":1,"virtualQuantity":1,
"weight":1000,"limit":-1,"description":"1"},
{"mappingBehavior":0,"caption":"Memory","elementName":"Memory",
"consumerVisibility":0,"resourceType":4,"automaticAllocation":true,
"automaticDeallocation":true,"reservation":0,"allocationUnits":"bytes",
"instanceID":2,"virtualQuantity":2147483648,"weight":20480,"limit":-1,
"description":"2048.0 MB"},
{"mappingBehavior":0,"caption":"Hard disk 1","elementName":"Hard disk 1",
"consumerVisibility":0,"resourceType":17,"parent":200,"automaticAllocation":true,
"automaticDeallocation":true,"repositoryIDs":["datastore-11"],
"allocationUnits":"bytes","instanceID":3000,"virtualQuantity":2147483648,
"hostResource":["[dsrtl-VMwareCCS-01-001] RHEL61-Test\/RHEL61-Test.vmdk"],
"description":"2.0 GB","addressOnParent":0},
{"mappingBehavior":0,"caption":"Network adapter 1",
"elementName":"Network adapter 1","consumerVisibility":0,"resourceType":10,
"parent":100,"automaticAllocation":true,"resourceSubType":"Vmxnet",
"automaticDeallocation":true,"instanceID":4000,"address":"00:50:56:9c:0e:6c",
"description":"Internal10GBVLAN10","addressOnParent":7,
"connection":["Internal10GBVLAN10"]}]},
"domainName":"nc058108",
"locationUUID":"83ab1a70-793d-47c8-8927-239468db7dca",
"indexedOn":1337875521267,
"ownerList":
[{"numberOfGroups":0,"isUser":false,
"groupUUIDList":[],"uuid":"ed881bac-6397-3de3-bc0a-285c9f50bb83",
"name":"Everyone","roles":[]}],
"similarityMetric":0.4,
"folderPath":"\/Datacenters\/CCS\/vm\/Administration\/Development-VLAN10",
"repositoryName":"dsrtl-VMwareCCS-01-001",
"imageID":"vm-419","updated":1337875521259,
"uuid":"92541f8e-4752-4ca3-ba42-6af3c7cbde94",
"description":null,
"domainUUID":"337a8c39-6bbf-40b9-9d0c-2fad52080740"}
Connector REST API:
Virtual Image Library uses a connector to communicate with an operational
repository. There is a connector for each of the following types of supported
operational repository:
v VMware
v HSLT
The base URL of the connector REST API is:
https://<vil_hostname>:9443/ImageLibraryConnector/<operational_repository_type>/
Note: This is the base URL. You must add the additional parameters shown in this
topic to the URL.
The following examples are related to the VMware connector.
List locations
GET /connector/json?function=listLocations&hostName=<HostName>
&userName=<UserName>&password=<Password>
Example URL
https://localhost:9443/ImageLibraryConnector/VMware/connector/
json?function=listLocations&hostName=rm-vm1&userName=administrator
&password=passw0rd
Request parameters
350 IBM SmartCloud Orchestrator 2.3: User's Guide
hostName
The host name of the hypervisor manager that you registered to
Virtual Image Library.
userName
The user name to access the hypervisor manager.
password
The password to access the hypervisor manager.
Response content-type
application/json
Response example
A JSON array containing the location native IDs:
["datacenter-2"]
List repositories
GET /connector/json?function=listRepositories&hostName=<HostName>
&userName=<UserName>&password=<Password>
Example URL
https://localhost:9443/ImageLibraryConnector/VMware/connector/
json?function=listRepositories&hostName=rm-vm1
&userName=administrator&password=passw0rd
Request parameters
hostName
The host name of the hypervisor manager that you registered to
Virtual Image Library.
userName
The user name to access the hypervisor manager.
password
The password to access the hypervisor manager.
Response content-type
application/json
Response example
A JSON array containing the repository IDs:
["datastore-10"]
List images
GET /connector/json?function=listImages&hostName=<HostName>
&userName=<UserName>&password=<Password>
Example URL
https://localhost:9443/ImageLibraryConnector/VMware/connector/
json?function=listImages&hostName=rm-vm1&userName=administrator
&password=passw0rd
Request parameters
hostName
The host name of the hypervisor manager that you registered to
Virtual Image Library.
Chapter 5. Managing virtual images 351
userName
The user name to access the hypervisor manager.
password
The password to access the hypervisor manager.
Response content-type
application/json
Response example
A JSON object containing the image IDs and the hypervisor manager time to mark
the timestamp of the last synchronization:
{
"imageIDs":["vm-12","vm-14","vm-22","vm-23","vm-24","vm-25","vm-41","vm-51"],
"serverTime":1310075108778
}
List image changes
GET /connector/json?function=listImageChanges&hostName=<HostName>
&userName=<UserName>&password=<Password>&serverTime=<ServerTime>
Example URL
https://localhost:9443/ImageLibraryConnector/VMware/connector/
json?function=listImageChanges&hostName=rm-vm1
&userName=administrator&password=passw0rd
&serverTime=1310075108778
Request parameters
hostName
The host name of the hypervisor manager that you registered to
Virtual Image Library.
userName
The user name to access the hypervisor manager.
password
The password to access the hypervisor manager.
serverTime
The time from which the image changes are returned.
Response content-type
application/json
Response example
A JSON object containing the image changes and the hypervisor manager time to
mark the timestamp of the last synchronization:
{
"added":["vm-12","vm-14","vm-24","vm-25","vm-46","vm-47","vm-48","vm-49","vm-53",
"vm-51","vm-52","vm-21","vm-22","vm-23","vm-41","vm-50"],
"removed":["vm-46","vm-47","vm-48","vm-49","vm-53","vm-52","vm-21","vm-50"],
"modified":["vm-24","vm-12","vm-21","vm-22","vm-41","vm-23"],
"serverTime":1310075981763
}
Describe a location
GET /location/<locationID>/json?function=describeLocation&hostName=<HostName>
&userName=<UserName>&password=<Password>
352 IBM SmartCloud Orchestrator 2.3: User's Guide
Example URL
https://localhost:9443/ImageLibraryConnector/VMware/location/
datacenter-2/json?function=describeLocation&hostName=rm-vm1
&userName=administrator&password=passw0rd
Request parameters
locationID
The location ID on the hypervisor manager.
hostName
The host name of the hypervisor manager that you registered to
Virtual Image Library.
userName
The user name to access the hypervisor manager.
password
The password to access the hypervisor manager.
Response content-type
application/json
Response example
A JSON object containing the location information:
{
"id":"datacenter-2",
"created":1306346556553,
"name":"ImageLibrary",
"creator":"Administrator"
"version":"2.1"
}
Describe a repository
GET /repository/<repositoryID>/json?function=describeRepository
&hostName=<HostName>&userName=<UserName>&password=<Password>
Example URL
https://localhost:9443/ImageLibraryConnector/VMware/repository/
datastore-10/json?function=describeRepository&hostName=rm-vm1
&userName=administrator&password=passw0rd
Request parameters
repositoryID
The repository ID on the hypervisor manager.
hostName
The host name of the hypervisor manager that you registered to
Virtual Image Library.
userName
The user name to access the hypervisor manager.
password
The password to access the hypervisor manager.
Response content-type
application/json
Response example
Chapter 5. Managing virtual images 353
A JSON object containing the repository information:
{
"id":"datastore-10",
"freeSpace":39819673600,
"name":"datastore1",
"capacity":158645354496,
"locationID":"datacenter-2",
"type":"VMware - VMFS"
}
Describe an image
GET /image/<imageID>/json?function=describeImage
&hostName=<HostName>&userName=<UserName>&password=<Password>
Example URL
https://localhost:9443/ImageLibraryConnector/VMware/image/vm-25/
json?function=describeImage&hostName=rm-vm1
&userName=administrator&password=passw0rd
Request parameters
imageID
The image ID on the hypervisor manager.
hostName
The host name of the hypervisor manager that you registered to
Virtual Image Library.
userName
The user name to access the hypervisor manager.
password
The password to access the hypervisor manager.
Response content-type
application/json
Response example
A JSON object containing the image information:
{
"os":"LINUX",
"osVersion":"Other 2.6x Linux (32-bit)",
"methodOfCreation":"cloned",
"state":"available",
"locationID":"datacenter-2",
"architecture":"INTEL_X86_32",
"parentInstanceID":"vm-24",
"creator":"Administrator",
"imageID":"vm-25",
"created":1307052201557,
"repositoryIDs":["datastore-10"],
"description":null,
"name":"bonzai-v2",
"usage":"persistentInstance",
"configurationPath":"[datastore1] bonzai-v2\/bonzai-v2.vmx"
"hardware":
{
"virtualSystemType":"vmx-07",
"devices":[
{
"limit":-1,
"elementName":"CPU",
"weight":1000,
354 IBM SmartCloud Orchestrator 2.3: User's Guide
"mappingBehavior":0,
"consumerVisibility":0,
"instanceID":1,
"automaticAllocation":true,
"caption":"CPU",
"virtualQuantity":1,
"resourceType":3,
"automaticDeallocation":true,
"description":"1",
"reservation":0,
"allocationUnits":"hertz"
},
{
"limit":-1,
"elementName":"Memory",
"weight":10240,
"mappingBehavior":0,
"consumerVisibility":0,
"instanceID":2,
"automaticAllocation":true,
"caption":"Memory",
"virtualQuantity":1073741824,
"resourceType":4,
"automaticDeallocation":true,
"description":"1024.0 MB",
"reservation":0,
"allocationUnits":"bytes"
},
{
"elementName":"Hard disk 1",
"mappingBehavior":0,
"consumerVisibility":0,
"instanceID":3000,
"automaticAllocation":true,
"parent":200,
"caption":"Hard disk 1",
"format":"VMDK",
"addressOnParent":0,
"virtualQuantity":268435456,
"resourceType":17,
"automaticDeallocation":true,
"repositoryIDs":["datastore-10"],
"description":"0.25 GB",
"hostResource":["[datastore1] bonzai-v2\/bonzai-v2.vmdk"],
"allocationUnits":"bytes"
},
{
"resourceSubType":"PCNet32",
"elementName":"Network adapter 1",
"connection":["VM Network"],
"mappingBehavior":0,
"consumerVisibility":0,
"instanceID":4000,
"automaticAllocation":true,
"parent":100,
"caption":"Network adapter 1",
"addressOnParent":7,
"resourceType":10,
"automaticDeallocation":true,
"address":"00:50:56:98:00:05",
"description":"VM Network",
"networkIDs":["network-11"]
},
{
"elementName":"Video card",
"mappingBehavior":0,
"consumerVisibility":0,
Chapter 5. Managing virtual images 355
"instanceID":500,
"automaticAllocation":true,
"parent":100,
"caption":"Video card",
"addressOnParent":0,
"virtualQuantity":4194304,
"resourceType":24,
"automaticDeallocation":true,
"description":"4.0 MB",
"allocationUnits":"bytes"
},
{
"elementName":"CD\/DVD Drive 1",
"mappingBehavior":0,
"consumerVisibility":0,
"instanceID":3002,
"automaticAllocation":true,
"parent":201,
"caption":"CD\/DVD Drive 1",
"addressOnParent":0,
"resourceType":15,
"automaticDeallocation":true,
"description":"ISO [datastore1] ISO\/bonzai_3_2.iso",
"repositoryIDs":["datastore-10"],
"hostResource":["[datastore1] ISO\/bonzai_3_2.iso"]
},
{
"automaticDeallocation":true,
"elementName":"Floppy drive 1",
"mappingBehavior":0,
"consumerVisibility":0,
"description":"Remote",
"instanceID":8000,
"parent":400,
"automaticAllocation":false,
"caption":"Floppy drive 1",
"addressOnParent":0,
"resourceType":14
},
{
"automaticDeallocation":true,
"elementName":"IDE 0",
"mappingBehavior":0,
"consumerVisibility":0,
"description":"IDE 0",
"instanceID":200,
"automaticAllocation":true,
"caption":"IDE 0",
"resourceType":5
},
{
"automaticDeallocation":true,
"elementName":"IDE 1",
"mappingBehavior":0,
"consumerVisibility":0,
"description":"IDE 1",
"instanceID":201,
"automaticAllocation":true,
"caption":"IDE 1",
"resourceType":5
},
{
"automaticDeallocation":true,
"elementName":"PS2 controller 0",
"mappingBehavior":0,
"consumerVisibility":0,
"otherResourceType":"PS2 Controller",
356 IBM SmartCloud Orchestrator 2.3: User's Guide
"description":"PS2 controller 0",
"instanceID":300,
"automaticAllocation":true,
"caption":"PS2 controller 0",
"resourceType":1
},
{
"automaticDeallocation":true,
"elementName":"PCI controller 0",
"mappingBehavior":0,
"consumerVisibility":0,
"otherResourceType":"PCI Controller",
"description":"PCI controller 0",
"instanceID":100,
"automaticAllocation":true,
"caption":"PCI controller 0",
"resourceType":1
},
{
"automaticDeallocation":true,
"elementName":"SIO controller 0",
"mappingBehavior":0,
"consumerVisibility":0,
"otherResourceType":"SIO Controller",
"description":"SIO controller 0",
"instanceID":400,
"automaticAllocation":true,
"caption":"SIO controller 0",
"resourceType":1
},
{
"automaticDeallocation":true,
"resourceSubType":"Keyboard",
"elementName":"Keyboard",
"mappingBehavior":0,
"consumerVisibility":0,
"description":"Keyboard",
"instanceID":600,
"parent":300,
"automaticAllocation":true,
"caption":"Keyboard",
"addressOnParent":0,
"resourceType":13
},
{
"automaticDeallocation":true,
"elementName":"Pointing device",
"mappingBehavior":0,
"consumerVisibility":0,
"description":"Pointing device; Device",
"instanceID":700,
"parent":300,
"automaticAllocation":true,
"caption":"Pointing device",
"addressOnParent":1,
"resourceType":13
},
{
"automaticDeallocation":true,
"elementName":"VMCI device",
"mappingBehavior":0,
"consumerVisibility":0,
"otherResourceType":"VMCI",
"description":"Device on the virtual machine PCI bus that provides
support for the virtual machine communication interface",
"instanceID":12000,
"parent":100,
Chapter 5. Managing virtual images 357
"automaticAllocation":true,
"caption":"VMCI device",
"addressOnParent":17,
"resourceType":1
}]
},
}
Domain REST API:
Return details of a domain
GET /domain?function=describeDomain&domainUUID=<domain_uuid>
Example URL
https://localhost:9443/ImageLibrary/ImageLibrary/
domain?function=describeDomain&domainUUID=3bed15d1-ead9-4a46-
ad02-7c815bbf51e0
Request parameters
domainUUID
Response content-type
application/json
Response example
{
"numberOfDeployedVirtualMachines":37,
"state":"available",
"numberOfVirtualImages":16,
"lastUpdated":1320880238893,
"username":"administrator",
"numberOfRepositories":1,
"type":"VMware",
"uuid":"3bed15d1-ead9-4a46-ad02-7c815bbf51e0",
"name":"rm-vm1",
"exploiter":"IWD",
"ownerList":[{"name":"Everyone","uuid":"ed881bac-6397-3de3-bc0a-285c9f50bb83"},
"groupUUIDList":[],"isUser":false}],
"accessList":[{"name":"Everyone","uuid":"ed881bac-6397-3de3-bc0a-285c9f50bb83"},
"groupUUIDList":[],"isUser":false}],
"description":"some description",
"url":"https:\/\/2.zoppoz.workers.dev:443\/https\/localhost:9443\/ImageLibraryConnector\/VMware\/"
}
List all the domains in Virtual Image Library
GET /domain?function=listDomains
Example URL
https://localhost:9443/ImageLibrary/ImageLibrary/
domain?function=listDomains
Response content-type
application/json
Response example
A JSON array containing a domain uuid for each domain:
["3bed15d1-ead9-4a46-ad02-7c815bbf51e0"]
List all the domains in Virtual Image Library with detailed information
GET /domain?function=listDomainsVerbose
358 IBM SmartCloud Orchestrator 2.3: User's Guide
Example URL
https://localhost:9443/ImageLibrary/ImageLibrary/
domain?function=listDomainsVerbose
Response content-type
application/json
Response example
A JSON array containing the following object for each domain:
{
"numberOfDeployedVirtualMachines":37,
"state":"available",
"numberOfVirtualImages":16,
"lastUpdated":1320880238893,
"username":"administrator",
"numberOfRepositories":1,
"type":"VMware",
"uuid":"3bed15d1-ead9-4a46-ad02-7c815bbf51e0",
"name":"rm-vm1",
"exploiter":"IWD",
"ownerList":[{"name":"Everyone","uuid":"ed881bac-6397-3de3-bc0a-285c9f50bb83"},
"groupUUIDList":[],"isUser":false}],
"accessList":[{"name":"Everyone","uuid":"ed881bac-6397-3de3-bc0a-285c9f50bb83"},
"groupUUIDList":[],"isUser":false}],
"description":"some description",
"url":"https:\/\/2.zoppoz.workers.dev:443\/https\/localhost:9443\/ImageLibraryConnector\/VMware\/"
}
Register a domain in Virtual Image Library
The operation is asynchronous and it returns the uuid of the domain registration
task.
POST /domain/registerDomain
Example URL
https://localhost:9443/ImageLibrary/ImageLibrary/registerDomain
Request parameters
A JSON object in the HTTP body:
{
"type" : "VMware or HSLT",
"description" : "some description",
"hostName" : "host name for the hypervisor manager",
"userName" : "user name to log in to the hypervisor manager",
"password" : "password to log in to the hypervisor manager",
"exploiter" : "exploiter name (optional)"
}
Response content-type
application/json
Response example
{"task_uuid" : "d760fb14-4c48-4470-a579-51b93b6b58c7"}
Remove a domain
Removes a domain and all the related objects. If a domain was registered by an
exploiter, the exploiter name must be specified to remove the domain. It returns
the uuid of the domain deletion task.
DELETE /domain?domainUUID=<domain_uuid>[&exploiter=<exploiter_name>]
Chapter 5. Managing virtual images 359
Example URL
https://localhost:9443/ImageLibrary/ImageLibrary/
domain?domainUUID=<domain_uuid>
Request parameters
domainUUID
Response content-type
application/json
Response example
{"task_uuid" : "d760fb14-4c48-4470-a579-51b93b6b49b6"}
Change the credentials to access the hypervisor manager
POST /domain/changeCredentials
Example URL
https://localhost:9443/ImageLibrary/ImageLibrary/domain/
changeCredentials
Request parameters
A JSON object in the HTTP body:
{
"domainUUID" : "domain uuid",
"newUserName" : "new user name for the hypervisor manager (optional)",
"newPassword" : "new password for the hypervisor manager"
}
Success code
204
Resynchronize a domain
Triggers resynchronization of Virtual Image Library domain with physical domain.
PUT /domain?function=resynchDomain&domainUUID=<domain_uuid>
Example URL
https://localhost:9443/ImageLibrary/ImageLibrary/
domain?function=resynchDomain&domainUUID=3bed15d1-ead9-4a46-
ad02-7c815bbf51e0
Request parameters
domainUUID
Response content-type
application/json
Response example
{"task_uuid" : "d760fb14-4c48-4470-a579-51b93b6b58c7"}
360 IBM SmartCloud Orchestrator 2.3: User's Guide
Image log REST API:
List all the image logs
GET /imageLog?function=listImageLogs[&domainUUID=<domain_uuid>]
[&locationUUID=<location_uuid>][&action=add|remove|modify]
[&eventTime=<event_time>]
Example URL
https://localhost:9443/ImageLibrary/ImageLibrary/
imageLog?function=listImageLogs
Request parameters
domainUUID
locationUUID
action that is the event related to the image
eventTime
Response content-type
application/json
Response example
A JSON array containing a UUID for each image log:
["d348d475-83de-4c61-a8ad-c7ee92e620e8","c0aaa327-0495-4e47-97de-c51bb121dccf",
"1f2275b3-fc51-4a4a-a926-0a03fe04bb08","440ad139-965f-4444-989c-eeb0e3863eea"]
List all the image logs with detailed information
GET /imageLog?function=listImageLogsVerbose[&domainUUID=<domain_uuid>]
[&locationUUID=<location_uuid>][&action=add|remove|modify]
[&eventTime=<event_time>]
Example URL
https://localhost:9443/ImageLibrary/ImageLibrary/
imageLog?function=listImageLogsVerbose
Request parameters
domainUUID
locationUUID
action that is the event related to the image
eventTime
Response content-type
application/json
Response example
A JSON array containing the following object for each image log:
{
"locationUUID":"579d9190-afb4-47cc-a54d-ec02c82489bb",
"ownerList":[],
"accessList":[],
"action":"REMOVE",
"imageID":"vm-446",
"imageUUID":"2d6dd813-8dcb-4f22-8d0b-d0d48b031695",
"eventTime":1330786071442,
"user":"wasadmin",
"uuid":"d348d475-83de-4c61-a8ad-c7ee92e620e8",
Chapter 5. Managing virtual images 361
"domainName":"nc058108.romelab.it.ibm.com",
"domainUUID":"038d8819-d6ae-46fe-ab6a-649598a14bf7",
"imageTypeChecks":[]
}
Delete image logs
It deletes the specified image log or all the image logs older than the specified
time.
DELETE /imageLog?imageLogUUID=<imagelog_uuid>
DELETE /imageLog?eventTime=<event_time>
Example URL
https://localhost:9443/ImageLibrary/ImageLibrary/
imageLog?imageLogUUID=<imagelog_uuid>
https://localhost:9443/ImageLibrary/ImageLibrary/
imageLog?eventTime=<event_time>
Request parameters
imageLogUUID
eventTime
Success code
204
Location REST API:
Return details of a location
GET /location?function=describeLocation&locationUUID=<location_uuid>
Example URL
https://localhost:9443/ImageLibrary/ImageLibrary/
location?function=describeLocation&locationUUID=3de593a5-92d5-4ed3-
94de-9a4abe7b14b6
Request parameters
locationUUID
Response content-type
application/json
Response example
{
"numberOfDeployedVirtualMachines":37,
"numberOfVirtualImages":16,
"numberOfRepositories":1,
"created":1306346556553,
"uuid":"3de593a5-92d5-4ed3-94de-9a4abe7b14b6",
"name":"ImageLibrary",
"creator":"Administrator",
"ownerList":[{"name":"Everyone","uuid":"ed881bac-6397-3de3-bc0a-285c9f50bb83"},
"groupUUIDList":[],"isUser":false}],
"accessList":[{"name":"Everyone","uuid":"ed881bac-6397-3de3-bc0a-285c9f50bb83"},
"groupUUIDList":[],"isUser":false}],
"domainName":"rm-vm1",
"domainUUID":"3bed15d1-ead9-4a46-ad02-7c815bbf51e0"
}
362 IBM SmartCloud Orchestrator 2.3: User's Guide
List all the locations in Virtual Image Library
If you specify the domainUUID parameter, all the locations related to that domain
are returned.
GET /location?function=listLocations[&domainUUID=<domain_uuid>]
Example URL
https://localhost:9443/ImageLibrary/ImageLibrary/
location?function=listLocations
Request parameters
domainUUID
Response content-type
application/json
Response example
A JSON array containing a location UUID for each location:
["4dd0921c-ba65-4f42-9ab2-4ba70d50ba32","ee9f1c3e-a66c-4100-ae83-41778bf91e67"]
List all the locations in Virtual Image Library with detailed information
If you specify the domainUUID parameter, all the locations related to that domain
are returned.
GET /location?function=listLocationsVerbose[&domainUUID=<domain_uuid>]
Example URL
https://localhost:9443/ImageLibrary/ImageLibrary/
location?function=listLocationsVerbose
Response content-type
application/json
Response example
A JSON array containing the following object for each location:
{
"numberOfDeployedVirtualMachines":37,
"numberOfVirtualImages":16,
"numberOfRepositories":1,
"created":1306346556553,
"uuid":"3de593a5-92d5-4ed3-94de-9a4abe7b14b6",
"name":"ImageLibrary",
"creator":"Administrator",
"ownerList":[{"name":"Everyone","uuid":"ed881bac-6397-3de3-bc0a-285c9f50bb83"},
"groupUUIDList":[],"isUser":false}],
"accessList":[{"name":"Everyone","uuid":"ed881bac-6397-3de3-bc0a-285c9f50bb83"},
"groupUUIDList":[],"isUser":false}],
"domainName":"rm-vm1",
"domainUUID":"3bed15d1-ead9-4a46-ad02-7c815bbf51e0"
}
Chapter 5. Managing virtual images 363
Operational repository REST API:
Return details of an operational repository
GET /instanceRepository?function=describeRepository&repositoryUUID=<repository_uuid>
Example URL
https://localhost:9443/ImageLibrary/ImageLibrary/
instanceRepository?function=describeRepository
&repositoryUUID=c9eadef4-6b35-484e-9e5b-0b26a3517f7b
Request parameters
repositoryUUID
Response content-type
application/json
Response example
{
"locationName":"ImageLibrary"
"numberOfVirtualImages":16
"name":"datastore1"
"domainName":"rm-vm1"
"url":"https:\/\/2.zoppoz.workers.dev:443\/https\/localhost:9443\/ImageLibraryConnector\/VMware\/"
"locationUUID":"3de593a5-92d5-4ed3-94de-9a4abe7b14b6"
"numberOfDeployedVirtualMachines":35
"referenceRepository":"false"
"type":"VMware - VMFS"
"uuid":"c9eadef4-6b35-484e-9e5b-0b26a3517f7b"
"ownerList":
[{"name":"Everyone","uuid":"ed881bac-6397-3de3-bc0a-285c9f50bb83"},
"groupUUIDList":[],"isUser":false}],
"accessList":
[{"name":"Everyone","uuid":"ed881bac-6397-3de3-bc0a-285c9f50bb83"},
"groupUUIDList":[],"isUser":false}],
"description":"datastore1"
"comment":null
"domainUUID":"3bed15d1-ead9-4a46-ad02-7c815bbf51e0"
}
List all the repositories in Virtual Image Library
If you specify the domainUUID or the locationUUID parameter, all the repositories
related to the specified object are returned.
GET /instanceRepository?function=listRepositories[&domainUUID=<domain_uuid>]
[&locationUUID=<location_uuid>]
Example URL
https://localhost:9443/ImageLibrary/ImageLibrary/
instanceRepository?function=listRepositories
Request parameters
domainUUID
locationUUID
Response content-type
application/json
Response example
A JSON array containing a UUID for each operational repository:
["c9eadef4-6b35-484e-9e5b-0b26a3517f7b"]
364 IBM SmartCloud Orchestrator 2.3: User's Guide
List all the repositories in Virtual Image Library with detailed information
If you specify the domainUUID or the locationUUID parameter, all the repositories
related to the specified object are returned.
GET /instanceRepository?function=listRepositoriesVerbose[&domainUUID=<domain_uuid>
][&locationUUID=<location_uuid>]
Example URL
https://localhost:9443/ImageLibrary/ImageLibrary/
instanceRepository?function=listRepositoriesVerbose
Response content-type
application/json
Optional parameters
domainUUID
locationUUID
Response example
A JSON array containing the following object for each location:
{
"locationName":"ImageLibrary"
"numberOfVirtualImages":16
"name":"datastore1"
"domainName":"rm-vm1"
"url":"https:\/\/2.zoppoz.workers.dev:443\/https\/localhost:9443\/ImageLibraryConnector\/VMware\/"
"locationUUID":"3de593a5-92d5-4ed3-94de-9a4abe7b14b6"
"numberOfDeployedVirtualMachines":35
"referenceRepository":"false"
"type":"VMware - VMFS"
"uuid":"c9eadef4-6b35-484e-9e5b-0b26a3517f7b"
"ownerList":
[{"name":"Everyone","uuid":"ed881bac-6397-3de3-bc0a-285c9f50bb83"},
"groupUUIDList":[],"isUser":false}],
"accessList":
[{"name":"Everyone","uuid":"ed881bac-6397-3de3-bc0a-285c9f50bb83"},
"groupUUIDList":[],"isUser":false}],
"description":"datastore1"
"comment":null
"domainUUID":"3bed15d1-ead9-4a46-ad02-7c815bbf51e0"
}
Operational images REST API:
Check in an image from an operational repository to the reference repository
Returns the UUID of the related check-in task.
POST /repositoryImage/checkin
Example URL
https://localhost:9443/ImageLibrary/ImageLibrary/repositoryImage/
checkin
Request content-type
application/json
Request parameters
A JSON object in the HTTP body:
{
"name" : "an image name",
"description" : "an optional description",
Chapter 5. Managing virtual images 365
"comment" : "optional comments",
"versionChainUUID" : "UUID of a version chain, none to join an existing
version chain, or a name to create a new version chain
with the specified name",
"sourceImageUUID" : "UUID of the image to be checked in"
}
Response content-type
application/json
Response example
{"task_uuid" : "d760fb14-4c48-4470-a579-51b93b64976b"}
Return details of an image in the operational repository
GET /repositoryImage?function=describeImage&imageUUID=<image_uuid>
Example URL
https://localhost:9443/ImageLibrary/ImageLibrary/
repositoryImage?function=describeImage&imageUUID=560c826c-c059-4d55-
8743-a8f89e592fc8
Request parameters
imageUUID
Response content-type
application/json
Response example
{
usage: "persistentInstance"
indexingState: "notIndexed"
indexedOn: 12345678
os: "LINUX"
created: 1315477636803
hardware: {
virtualSystemType: "vmx-07"
devices: [
{
mappingBehavior: 0
caption: "CPU"
elementName: "CPU"
consumerVisibility: 0
resourceType: 3
automaticAllocation: true
automaticDeallocation: true
reservation: 0
allocationUnits: "hertz"
instanceID: 1
virtualQuantity: 2
weight: 2000
limit: -1
description: "2"
}
{
mappingBehavior: 0
caption: "Memory"
elementName: "Memory"
consumerVisibility: 0
resourceType: 4
automaticAllocation: true
automaticDeallocation: true
reservation: 0
allocationUnits: "bytes"
instanceID: 2
366 IBM SmartCloud Orchestrator 2.3: User's Guide
virtualQuantity: 4294967296
weight: 40960
limit: -1
description: "4096.0 MB"
}
{
mappingBehavior: 0
caption: "Hard disk 1"
elementName: "Hard disk 1"
consumerVisibility: 0
resourceType: 17
parent: 1000
automaticAllocation: true
automaticDeallocation: true
repositoryIDs: [
"datastore-189"
]
allocationUnits: "bytes"
instanceID: 2000
virtualQuantity: 85899345920
hostResource: [
"[test4] redhat-itds.torolab.ibm.com/redhat-itds.torolab.ibm.com.vmdk"
]
description: "80.0 GB"
addressOnParent: 0
}
{
mappingBehavior: 0
caption: "Network adapter 1"
elementName: "Network adapter 1"
consumerVisibility: 0
resourceType: 10
parent: 100
automaticAllocation: true
resourceSubType: "E1000"
automaticDeallocation: true
instanceID: 4000
address: "00:50:56:98:00:10"
description: "VM Network"
addressOnParent: 7
connection: [
"VM Network"
]
}
{
mappingBehavior: 0
instanceID: 1000
caption: "SCSI controller 0"
elementName: "SCSI controller 0"
resourceType: 6
consumerVisibility: 0
parent: 100
automaticAllocation: true
resourceSubType: "lsilogic"
description: "LSI Logic Parallel"
automaticDeallocation: true
addressOnParent: 3
}
{
mappingBehavior: 0
caption: "Video card"
elementName: "Video card"
consumerVisibility: 0
resourceType: 24
parent: 100
automaticAllocation: true
automaticDeallocation: true
Chapter 5. Managing virtual images 367
allocationUnits: "bytes"
instanceID: 500
virtualQuantity: 4194304
description: "4.0 MB"
addressOnParent: 0
}
{
mappingBehavior: 0
instanceID: 3000
caption: "CD/DVD Drive 1"
elementName: "CD/DVD Drive 1"
resourceType: 15
consumerVisibility: 0
parent: 200
automaticAllocation: false
description: "Remote device"
automaticDeallocation: true
addressOnParent: 0
}
{
mappingBehavior: 0
instanceID: 200
caption: "IDE 0"
elementName: "IDE 0"
resourceType: 5
consumerVisibility: 0
automaticAllocation: true
description: "IDE 0"
automaticDeallocation: true
}
{
mappingBehavior: 0
instanceID: 201
caption: "IDE 1"
elementName: "IDE 1"
resourceType: 5
consumerVisibility: 0
automaticAllocation: true
description: "IDE 1"
automaticDeallocation: true
}
{
mappingBehavior: 0
instanceID: 300
caption: "PS2 controller 1"
elementName: "PS2 controller 1"
otherResourceType: "PS2 Controller"
resourceType: 1
consumerVisibility: 0
automaticAllocation: true
description: "PS2 controller 1"
automaticDeallocation: true
}
{
mappingBehavior: 0
instanceID: 100
caption: "PCI controller 1"
elementName: "PCI controller 1"
otherResourceType: "PCI Controller"
resourceType: 1
consumerVisibility: 0
automaticAllocation: true
description: "PCI controller 1"
automaticDeallocation: true
}
{
mappingBehavior: 0
368 IBM SmartCloud Orchestrator 2.3: User's Guide
instanceID: 400
caption: "SIO controller 1"
elementName: "SIO controller 1"
otherResourceType: "SIO Controller"
resourceType: 1
consumerVisibility: 0
automaticAllocation: true
description: "SIO controller 1"
automaticDeallocation: true
}
{
mappingBehavior: 0
instanceID: 600
caption: "Keyboard"
elementName: "Keyboard"
resourceType: 13
consumerVisibility: 0
parent: 300
automaticAllocation: true
resourceSubType: "Keyboard"
description: "Keyboard"
automaticDeallocation: true
addressOnParent: 0
}
{
mappingBehavior: 0
instanceID: 700
caption: "Pointing device"
elementName: "Pointing device"
resourceType: 13
consumerVisibility: 0
parent: 300
automaticAllocation: true
description: "Pointing device; Device"
automaticDeallocation: true
addressOnParent: 1
}
{
mappingBehavior: 0
instanceID: 12000
caption: "VMCI device"
elementName: "VMCI device"
otherResourceType: "VMCI"
resourceType: 1
consumerVisibility: 0
parent: 100
automaticAllocation: true
description: "Device on the virtual machine PCI bus that provides support
for the virtual machine communication interface"
automaticDeallocation: true
addressOnParent: 17
}
]
}
name: "redhat-itds.torolab.ibm.com"
creator: null
domainName: "tiv-vsphere41"
locationUUID: "d4b02df3-d34f-4b0b-9853-4cd38e035e7e"
state: "available"
architecture: "INTEL_X86_64"
osVersion: "Red Hat Enterprise Linux 5 (64-bit)"
imageID: "vm-323"
disks: [
{
size: 0
path: "[test4] redhat-itds.torolab.ibm.com/redhat-itds.torolab.ibm.com.vmdk"
format: "VMDK"
Chapter 5. Managing virtual images 369
instanceRepository: "3f445808-d3b8-4d16-822a-54705ff9e13d"
}
]
methodOfCreation: "unknown"
uuid: "560c826c-c059-4d55-8743-a8f89e592fc8"
updated: 1315477636803
description: null
diskFreeSpace: "1000"
comment: null
domainUUID: "dc4c3466-3b8c-40a7-8097-45bbc7139c7f"
version: "1.1"
"ownerList":
[{"name":"Everyone","uuid":"ed881bac-6397-3de3-bc0a-285c9f50bb83"},
"groupUUIDList":[],"isUser":false}],
"accessList":
[{"name":"Everyone","uuid":"ed881bac-6397-3de3-bc0a-285c9f50bb83"},
"groupUUIDList":[],"isUser":false}],
provenanceVersionChainUUID: "ab4c3466-3b8c-40a7-8097-45bbc12384737"
userVersionChainUUIDs: [ "ab4c3466-3b8c-40a7-8097-45bbc12384737" ]
imagePortabilityStatus:"partial"
"imagePortabilityChecker":
[{"checkerName":"DHCP","checkerStatus":"notPassed"},
{"checkerName":"HostnameFileLinux","checkerStatus":"notPassed"}]
}
Index an image
POST /repositoryImage/index
Example URL
https://localhost:9443/ImageLibrary/ImageLibrary/repositoryImage/
index
Request content-type
application/json
Request parameters
A JSON object in the HTTP body:
{
"imageUUID" : "UUID of image",
"indexType" : "partial or full"
}
Response content-type
application/json
Response example
{"task_uuid":"e4ac3fcf-f3b4-4cc0-8414-a3096595230a"}
List all the operational images in Virtual Image Library
If you specify the optional request parameters, only the operational images related
to the specified objects are returned.
GET /repositoryImage?function=listImages[&domainUUID=<domain_uuid>]
[&locationUUID=<location_uuid>][&repositoryUUID=<repository_uuid>]
[&parentUUID=<parent_uuid>][&imageType=template|instance]
Example URL
https://localhost:9443/ImageLibrary/ImageLibrary/
repositoryImage?function=listImages
Request parameters
domainUUID
locationUUID
370 IBM SmartCloud Orchestrator 2.3: User's Guide
repositoryUUID
parentUUID
imageType that is template or instance
Response content-type
application/json
Response example
A JSON array containing a UUID for each image in the operational repository:
["c4a727c1-9fcc-4188-8f0a-9d168983a85c",
"15cb1e8c-26c3-471c-9401-4ec9a638c75f"
,"50fb2a7a-2ab9-4c92-b04f-46f47c2ccd17"]
List all the operational images in Virtual Image Library with detailed
information
If you specify the optional request parameters, only the operational images related
to the specified objects are returned.
GET /repositoryImage?function=listImagesVerbose[&domainUUID=<domain_uuid>]
[&locationUUID=<location_uuid>][&repositoryUUID=<repository_uuid>]
[&parentUUID=<parent_uuid>][&imageType=template|instance]
Example URL
https://localhost:9443/ImageLibrary/ImageLibrary/
repositoryImages?function=listImagesVerbose
Request parameters
domainUUID
locationUUID
repositoryUUID
parentUUID
imageType that is template or instance
Response content-type
application/json
Response example
A JSON array containing the following object for each image in the operational
repository:
{
locationName: "Test Environment v41"
usage: "persistentInstance"
indexingState: "notIndexed"
indexedOn: 12345567
os: "LINUX"
hardware: {
virtualSystemType: "vmx-07"
devices: [
{
mappingBehavior: 0
caption: "CPU"
elementName: "CPU"
consumerVisibility: 0
resourceType: 3
automaticAllocation: true
automaticDeallocation: true
Chapter 5. Managing virtual images 371
reservation: 0
allocationUnits: "hertz"
instanceID: 1
virtualQuantity: 2
weight: 2000
limit: -1
description: "2"
}
{
mappingBehavior: 0
caption: "Memory"
elementName: "Memory"
consumerVisibility: 0
resourceType: 4
automaticAllocation: true
automaticDeallocation: true
reservation: 0
allocationUnits: "bytes"
instanceID: 2
virtualQuantity: 4294967296
weight: 40960
limit: -1
description: "4096.0 MB"
}
{
mappingBehavior: 0
caption: "Hard disk 1"
elementName: "Hard disk 1"
consumerVisibility: 0
resourceType: 17
parent: 1000
automaticAllocation: true
automaticDeallocation: true
repositoryIDs: [
"datastore-189"
]
allocationUnits: "bytes"
instanceID: 2000
virtualQuantity: 85899345920
hostResource: [
"[test4] redhat-itds.torolab.ibm.com/redhat-itds.torolab.ibm.com.vmdk"
]
description: "80.0 GB"
addressOnParent: 0
}
{
mappingBehavior: 0
caption: "Network adapter 1"
elementName: "Network adapter 1"
consumerVisibility: 0
resourceType: 10
parent: 100
automaticAllocation: true
resourceSubType: "E1000"
automaticDeallocation: true
instanceID: 4000
address: "00:50:56:98:00:10"
description: "VM Network"
addressOnParent: 7
connection: [
"VM Network"
]
}
]
}
name: "redhat-itds.torolab.ibm.com"
domainName: "tiv-vsphere41"
372 IBM SmartCloud Orchestrator 2.3: User's Guide
locationUUID: "d4b02df3-d34f-4b0b-9853-4cd38e035e7e"
state: "available"
virtualizationType: "VMware"
architecture: "INTEL_X86_64"
osVersion: "Red Hat Enterprise Linux 5 (64-bit)"
imageID: "vm-323"
updated: 1315477636803
uuid: "560c826c-c059-4d55-8743-a8f89e592fc8"
"ownerList":
[{"name":"Everyone","uuid":"ed881bac-6397-3de3-bc0a-285c9f50bb83"},
"groupUUIDList":[],"isUser":false}],
"accessList":
[{"name":"Everyone","uuid":"ed881bac-6397-3de3-bc0a-285c9f50bb83"},
"groupUUIDList":[],"isUser":false}],
description: null
domainUUID: "dc4c3466-3b8c-40a7-8097-45bbc7139c7f"
imagePortabilityStatus:"partial"
"imagePortabilityChecker":
[{"checkerName":"DHCP","checkerStatus":"notPassed"},
{"checkerName":"HostnameFileLinux","checkerStatus":"notPassed"}]
}
Reference repository REST API:
Return details about the reference repository
GET /referenceRepository?function=describeRepository
Example URL
https://localhost:9443/ImageLibrary/ImageLibrary/
referenceRepository?function=describeRepository
Response content-type
application/json
Response example
{
"locationName":null,
"accessList":[],
"numberOfVirtualImages":1,
"name":"reference",
"domainName":null,
"url":"https:\/\/2.zoppoz.workers.dev:443\/http\/9.168.58.110:8081",
"locationUUID":null,
"ownerList":
[
{"numberOfGroups":0,
"isUser":false,
"groupUUIDList":[],
"uuid":"ed881bac-6397-3de3-bc0a-285c9f50bb83",
"name":"Everyone",
"roles":[]
}
],
"referenceRepository":"true",
"type":"TPMFI",
"uuid":"f12055cf-d3ec-4328-a0e9-ae97d3ac9463",
"description":"",
"comment":"",
"domainUUID":null
}
Chapter 5. Managing virtual images 373
Import an image into the reference repository
Returns the UUID of the related import task.
POST /referenceRepository/importImage
Example URL
https://localhost:9443/ImageLibrary/ImageLibrary/referenceRepository/
importImage
Request content-type
application/json
Request parameters
A JSON object in the HTTP body:
{
"name" : "an image name",
"description" : "an optional description",
"comment" : "optional comments",
"versionChainUUID" : "UUID of a version chain, none to join an existing
version chain, or a name to create a new version chain
with the specified name",
"disk" : "the full path to the image file"
}
Response content-type
application/json
Response example
{"task_uuid" : "d760fb14-4c48-4470-a579-51b87b253b61"}
Check out an image from the reference repository to an operational repository
Returns the UUID of the related check-out task.
POST /referenceImage/checkout
Example URL
https://localhost:9443/ImageLibrary/ImageLibrary/referenceImage/
checkout
Request content-type
application/json
Request parameters
A JSON object in the HTTP body:
{
"referenceImageUUID" : "UUID of the image",
"name" : "an image name",
"description" : "an optional description",
"comment" : "optional comments",
"instanceRepositoryUUID" : "UUID of the repository"
}
Response content-type
application/json
Response example
{"task_uuid" : "d760fb14-4c48-4470-a579-51b87a2c3b62"}
Delete an image from the reference repository
DELETE /referenceImage?referenceImageUUID=<image_uuid>
374 IBM SmartCloud Orchestrator 2.3: User's Guide
Example URL
https://localhost:9443/ImageLibrary/ImageLibrary/
referenceImage?referenceImageUUID=15cb1e8c-26c3-471c-9401-4ec9a638c75f
Request content-type
application/json
Request parameters
referenceImageUUID
Success code
204
Return details of an image in the reference repository
GET /referenceImage?function=describeImage&referenceImageUUID=<image_uuid>
Example URL
https://localhost:9443/ImageLibrary/ImageLibrary/
referenceImage?function=describeImage&referenceImageUUID=15cb1e8c-
26c3-471c-9401-4ec9a638c75f
Request parameters
referenceImageUUID
Response content-type
application/json
Response example
{
"imagePortabilityStatus":"partial",
"provenanceVersionChainUUID":"b7d97d63-6f53-4b7b-ba43-6b2ff2bfd320",
"name":"Rhel61-IDE-PARTIAL",
"state":"available",
"virtualizationType":"VMware",
"architecture":"INTEL_X86_64",
"osVersion":"Red Hat Enterprise Linux 6 (64-bit)",
"methodOfCreation":"created",
"version":"1.1",
"isReferenceImage":true,
"diskFreeSpace":"1000",
"comment":"",
"locationName":null,
"usage":"image",
"indexingState":"fullyIndexed",
"accessList":
[{"numberOfGroups":0,"isUser":false,"groupUUIDList":[],
"uuid":"ed881bac-6397-3de3-bc0a-285c9f50bb83","name":"Everyone","roles":[]}],
"userVersionChainUUIDs":["63609155-72f6-4f8c-9e46-15c19de876cb"],
"os":"LINUX",
"imagePortabilityChecker":
[{"checkerName":"NetworksFileLinux","checkerStatus":"notPassed"},
{"checkerName":"FstabFileEntryLinux","checkerStatus":"notPassed"},
{"checkerName":"Disk_Device","checkerStatus":"passed"},
{"checkerName":"SShServerConfigured","checkerStatus":"notPassed"},
{"checkerName":"LVM_Disk","checkerStatus":"passed"},
{"checkerName":"RCLocalLinux","checkerStatus":"notPassed"},
{"checkerName":"Ifcfgeth0FileLinux","checkerStatus":"notPassed"},
{"checkerName":"Multiple_Disk","checkerStatus":"passed"},
{"checkerName":"HostsFileLinux","checkerStatus":"notPassed"},
{"checkerName":"WriteNetRulesFileLinux","checkerStatus":"notPassed"},
{"checkerName":"SShServerInstalled","checkerStatus":"passed"}],
"created":1336756108114,
"hardware":
{
"virtualSystemType":"vmx-08",
Chapter 5. Managing virtual images 375
"devices":
[
{"mappingBehavior":0,"caption":"CPU","elementName":"CPU","consumerVisibility":0,
"resourceType":3,"automaticAllocation":true,"automaticDeallocation":true,
"reservation":0,"allocationUnits":"hertz","instanceID":1,"virtualQuantity":1,
"weight":1000,"limit":-1,"description":"1"},
{"mappingBehavior":0,"caption":"Memory","elementName":"Memory",
"consumerVisibility":0,"resourceType":4,"automaticAllocation":true,
"automaticDeallocation":true,"reservation":0,"allocationUnits":"bytes",
"instanceID":2,"virtualQuantity":2147483648,"weight":20480,"limit":-1,
"description":"2048.0 MB"},
{"mappingBehavior":0,"caption":"Hard disk 1","elementName":"Hard disk 1",
"consumerVisibility":0,"resourceType":17,"parent":200,"automaticAllocation":true,
"automaticDeallocation":true,"repositoryIDs":["datastore-11"],
"allocationUnits":"bytes","instanceID":3000,"virtualQuantity":8589934592,
"hostResource":
["[dsrtl-VMwareCCS-01-001] Rhel61-IDE-PARTIAL\/Rhel61-IDE-PARTIAL.vmdk"],
"description":"8.0 GB","addressOnParent":0},
{"mappingBehavior":0,"caption":"Network adapter 1",
"elementName":"Network adapter 1","consumerVisibility":0,"resourceType":10,
"parent":100,"automaticAllocation":true,"resourceSubType":"E1000",
"automaticDeallocation":true,"instanceID":4000,"address":"00:50:56:9c:44:92",
"description":"Internal10GBVLAN10","addressOnParent":7,
"connection":["Internal10GBVLAN10"]},
{"mappingBehavior":0,"caption":"Video card","elementName":"Video card",
"consumerVisibility":0,"resourceType":24,"parent":100,"automaticAllocation":true,
"automaticDeallocation":true,"allocationUnits":"bytes","instanceID":500,
"virtualQuantity":8388608,"description":"8.0 MB","addressOnParent":0},
{"mappingBehavior":0,"caption":"CD\/DVD drive 1","elementName":"CD\/DVD drive 1",
"consumerVisibility":0,"resourceType":15,"parent":201,"automaticAllocation":true,
"automaticDeallocation":true,"repositoryIDs":["datastore-11"],"instanceID":3002,
"hostResource":
["[dsrtl-VMwareCCS-01-001] iso\/RHEL6.1-20110510.1-Server-x86_64-DVD1.iso"],
"description":
"ISO [dsrtl-VMwareCCS-01-001] iso\/RHEL6.1-20110510.1-Server-x86_64-DVD1.iso",
"addressOnParent":0},
{"mappingBehavior":0,"instanceID":8000,"caption":"Floppy drive 1",
"elementName":"Floppy drive 1","resourceType":14,"consumerVisibility":0,
"parent":400,"automaticAllocation":false,"description":"Remote",
"automaticDeallocation":true,"addressOnParent":0},
{"mappingBehavior":0,"instanceID":100,"caption":"PCI controller 0",
"elementName":"PCI controller 0","otherResourceType":"PCI Controller",
"resourceType":1,"consumerVisibility":0,"automaticAllocation":true,
"description":"PCI controller 0","automaticDeallocation":true},
{"mappingBehavior":0,"instanceID":200,"caption":"IDE 0","elementName":"IDE 0",
"resourceType":5,"consumerVisibility":0,"automaticAllocation":true,
"description":"IDE 0","automaticDeallocation":true},
{"mappingBehavior":0,"instanceID":201,"caption":"IDE 1","elementName":"IDE 1",
"resourceType":5,"consumerVisibility":0,"automaticAllocation":true,
"description":"IDE 1","automaticDeallocation":true},
{"mappingBehavior":0,"instanceID":300,"caption":"PS2 controller 0",
"elementName":"PS2 controller 0","otherResourceType":"PS2 Controller",
"resourceType":1,"consumerVisibility":0,"automaticAllocation":true,
"description":"PS2 controller 0","automaticDeallocation":true},
{"mappingBehavior":0,"instanceID":400,"caption":"SIO controller 0",
"elementName":"SIO controller 0","otherResourceType":"SIO Controller",
"resourceType":1,"consumerVisibility":0,"automaticAllocation":true,
"description":"SIO controller 0","automaticDeallocation":true},
{"mappingBehavior":0,"instanceID":600,"caption":"Keyboard",
"elementName":"Keyboard","resourceType":13,"consumerVisibility":0,
"parent":300,"automaticAllocation":true,"resourceSubType":"Keyboard",
"description":"Keyboard","automaticDeallocation":true,"addressOnParent":0},
{"mappingBehavior":0,"instanceID":700,"caption":"Pointing device",
"elementName":"Pointing device","resourceType":13,"consumerVisibility":0,
"parent":300,"automaticAllocation":true,
"description":"Pointing device; Device","automaticDeallocation":true,
"addressOnParent":1},
376 IBM SmartCloud Orchestrator 2.3: User's Guide
{"mappingBehavior":0,"instanceID":12000,"caption":"VMCI device",
"elementName":"VMCI device","otherResourceType":"VMCI","resourceType":1,
"consumerVisibility":0,"parent":100,"automaticAllocation":true,
"description":"Device on the virtual machine PCI bus that provides support for
the virtual machine communication interface","automaticDeallocation":true,
"addressOnParent":17}
]
},
"creator":"root",
"domainName":null,
"indexedOn":1337010983404,
"locationUUID":null,
"ownerList":
[{"numberOfGroups":0,"isUser":true,"groupUUIDList":[],
"uuid":"353dc07c-87fc-458e-bc03-44f097bf3a93","name":"wasadmin","roles":[]}],
"folderPath":null,
"imageID":"Rhel61-IDE-PARTIAL",
"disks":
[{"size":8589934592,"repositoryName":"reference",
"repositoryUUID":"f12055cf-d3ec-4328-a0e9-ae97d3ac9463",
"path":"21b7fb28-9879-434e-ab79-ee1a026031d3-Rhel61-IDE-PARTIAL.vmdk.sgd",
"format":null,"virtIO":false}],
"updated":1336756108114,
"uuid":"29bfd583-b014-43f9-9300-a4c4018f32b9","imageSize":8589934592,
"description":"",
"domainUUID":null
}
Index an image
POST /referenceImage/index
Example URL
https://localhost:9443/ImageLibrary/ImageLibrary/referenceImage/index
Request content-type
application/json
Request parameters
A JSON object in the HTTP body:
{
"referenceImageUUID" : "UUID of image",
"indexType" : "partial or full"
}
Response content-type
application/json
Response example
{"task_uuid":"e4ac3fcf-f3b4-4cc0-8414-a3096595230a"}
List all the images in the reference repository
GET /referenceImage?function=listImages
Example URL
https://localhost:9443/ImageLibrary/ImageLibrary/
referenceImage?function=listImages
Response content-type
application/json
Response example
A JSON array containing a UUID for each image in the reference repository:
Chapter 5. Managing virtual images 377
["c4a727c1-9fcc-4188-8f0a-9d168983a85c",
"15cb1e8c-26c3-471c-9401-4ec9a638c75f",
"50fb2a7a-2ab9-4c92-b04f-46f47c2ccd17"]
List all the images in the reference repository with detailed information
GET /referenceImage?function=listImagesVerbose
Example URL
https://localhost:9443/ImageLibrary/ImageLibrary/
referenceImage?function=listImagesVerbose
Response content-type
application/json
Response example
A JSON array containing the following object for each image in the reference
repository:
{
"imagePortabilityStatus":"partial",
"provenanceVersionChainUUID":"b7d97d63-6f53-4b7b-ba43-6b2ff2bfd320",
"repositoryUUID":"f12055cf-d3ec-4328-a0e9-ae97d3ac9463",
"name":"Rhel61-IDE-PARTIAL",
"state":"available",
"virtualizationType":"VMware",
"architecture":"INTEL_X86_64",
"osVersion":"Red Hat Enterprise Linux 6 (64-bit)",
"version":"1.1",
"isReferenceImage":true,
"locationName":null,
"usage":"image",
"indexingState":"fullyIndexed",
"accessList":
[{"numberOfGroups":0,"isUser":false,"groupUUIDList":[],
"uuid":"ed881bac-6397-3de3-bc0a-285c9f50bb83","name":"Everyone","roles":[]}],
"userVersionChainUUIDs":["63609155-72f6-4f8c-9e46-15c19de876cb"],
"os":"LINUX",
"imagePortabilityChecker":
[{"checkerName":"NetworksFileLinux","checkerStatus":"notPassed"},
{"checkerName":"FstabFileEntryLinux","checkerStatus":"notPassed"},
{"checkerName":"Disk_Device","checkerStatus":"passed"},
{"checkerName":"SShServerConfigured","checkerStatus":"notPassed"},
{"checkerName":"LVM_Disk","checkerStatus":"passed"},
{"checkerName":"RCLocalLinux","checkerStatus":"notPassed"},
{"checkerName":"Ifcfgeth0FileLinux","checkerStatus":"notPassed"},
{"checkerName":"Multiple_Disk","checkerStatus":"passed"},
{"checkerName":"HostsFileLinux","checkerStatus":"notPassed"},
{"checkerName":"WriteNetRulesFileLinux","checkerStatus":"notPassed"},
{"checkerName":"SShServerInstalled","checkerStatus":"passed"}],
"hardware":
{
"virtualSystemType":"vmx-08",
"devices":
[
{"mappingBehavior":0,"caption":"CPU","elementName":"CPU","consumerVisibility":0,
"resourceType":3,"automaticAllocation":true,"automaticDeallocation":true,
"reservation":0,"allocationUnits":"hertz","instanceID":1,"virtualQuantity":1,
"weight":1000,"limit":-1,"description":"1"},
{"mappingBehavior":0,"caption":"Memory","elementName":"Memory",
"consumerVisibility":0,"resourceType":4,"automaticAllocation":true,
"automaticDeallocation":true,"reservation":0,"allocationUnits":"bytes",
"instanceID":2,"virtualQuantity":2147483648,"weight":20480,"limit":-1,
"description":"2048.0 MB"},
{"mappingBehavior":0,"caption":"Hard disk 1","elementName":"Hard disk 1"
,"consumerVisibility":0,"resourceType":17,"parent":200,"automaticAllocation":true,
378 IBM SmartCloud Orchestrator 2.3: User's Guide
"automaticDeallocation":true,"repositoryIDs":["datastore-11"],
"allocationUnits":"bytes","instanceID":3000,"virtualQuantity":8589934592,
"hostResource":
["[dsrtl-VMwareCCS-01-001] Rhel61-IDE-PARTIAL\/Rhel61-IDE-PARTIAL.vmdk"],
"description":"8.0 GB","addressOnParent":0},
{"mappingBehavior":0,"caption":"Network adapter 1",
"elementName":"Network adapter 1","consumerVisibility":0,"resourceType":10,
"parent":100,"automaticAllocation":true,"resourceSubType":"E1000",
"automaticDeallocation":true,"instanceID":4000,"address":"00:50:56:9c:44:92",
"description":"Internal10GBVLAN10","addressOnParent":7,
"connection":["Internal10GBVLAN10"]}
]
},
"domainName":null,
"locationUUID":null,
"indexedOn":1337010983404,
"ownerList":
[{"numberOfGroups":0,"isUser":true,"groupUUIDList":[]
,"uuid":"353dc07c-87fc-458e-bc03-44f097bf3a93","name":"wasadmin","roles":[]}],
"folderPath":null,
"repositoryName":"reference",
"imageID":"Rhel61-IDE-PARTIAL",
"updated":1336756108114,
"uuid":"29bfd583-b014-43f9-9300-a4c4018f32b9",
"description":"",
"domainUUID":null
}
]
Task REST API:
List all the tasks
GET /task?function=listAllTasks
Example URL
https://localhost:9443/ImageLibrary/ImageLibrary/
task?function=listAllTasks
Response content-type
application/json
Response example
A JSON array containing the following object for each tasks:
{
"task_uuid" : "b60b7983-50cf-4c95-96ce-fb041c7109f3",
"name" : "taskName_index",
"details" : {"imageName":"test"},
"ownerList":
[{"name":"Everyone","uuid":"ed881bac-6397-3de3-bc0a-285c9f50bb83"},
"groupUUIDList":[],"isUser":false}],
"accessList":
[{"name":"Everyone","uuid":"ed881bac-6397-3de3-bc0a-285c9f50bb83"},
"groupUUIDList":[],"isUser":false}],
"status" : "InProgress",
"percentComplete" : "50",
"timeCreated" : "1312565894424",
"timeStarted" : "1312565904378",
"timeCompleted" : "1312565955128"
}
Remove a task
You cannot remove a task that is in progress.
DELETE /task?task_uuid=<task_uuid>
Chapter 5. Managing virtual images 379
Example URL
https://localhost:9443/ImageLibrary/ImageLibrary/
task?task_uuid=b60b7983-50cf-4c95-96ce-fb041c7109f3
Request parameters
task_uuid
Success code
204
Get the task status
GET /task?function=getTaskStatus&task_uuid=<task_uuid>
Example URL
https://localhost:9443/ImageLibrary/ImageLibrary/
task?function=getTaskStatus&task_uuid=b60b7983-50cf-4c95-96ce-
fb041c7109f3
Request parameters
task_uuid
Response content-type
application/json
Response example
A JSON object containing one of the following statuses:
v Queued
v Completed
v Failed
v InProgress
{ "status" : "InProgress"}
Get the percentage of a task completion
GET /task?function=getTaskPercentComplete&task_uuid=<task_uuid>
Example URL
https://localhost:9443/ImageLibrary/ImageLibrary/
task?function=getTaskPercentComplete&task_uuid=b60b7983-50cf-4c95-
96ce-fb041c7109f3
Request parameters
task_uuid
Response content-type
application/json
Response example
{ "percentComplete" : 50}
Get the error message of a failed task
GET /task?function=getTaskError&task_uuid=<task_uuid>
Example URL
https://localhost:9443/ImageLibrary/ImageLibrary/
task?function=getTaskError&task_uuid=b60b7983-50cf-4c95-96ce-
fb041c7109f3
380 IBM SmartCloud Orchestrator 2.3: User's Guide
Request parameters
task_uuid
Response content-type
application/json
Response example
{
"ERROR_CODE" : "COPIML108EcannotConnectToDomain",
"ERROR_MESSAGE":"Cannot connect to the domain host name 9.123.141.177
using user name admin."
"ERROR_CAUSE":"null"
}
Users REST API:
Triggers resynchronization of Virtual Image Library users and groups with
WebSphere users and groups.
POST /userAndGroup?function=synchronize
Example URL
https://localhost:9443/ImageLibrary/ImageLibrary/
userAndGroup?function=synchronize
Request parameters
None
Response content-type
application/json
Response example
{"task_uuid" : "d760fb14-4c48-4470-a579-51b93b6b58c7"}
Version chain REST API:
List all the version chains
GET /versionChain?function=listUserVersionChains
Example URL
https://localhost:9443/ImageLibrary/ImageLibrary/
versionChain?function=listUserVersionChains
Response content-type
application/json
Response example
A JSON array containing the following object for each version chain:
{
"name" : "vm-test-01",
"uuid" : "dc4c3466-3b8c-40a7-8097-45bbc7139c7f"
}
Return information about a version chain
GET /versionChain?function=describeVersionChain&versionChainUUID=<versionchain_uuid>
Example URL
https://localhost:9443/ImageLibrary/ImageLibrary/
versionChain?function=describeVersionChain
&versionChainUUID=dc4c3466-3b8c-40a7-8097-45bbc7139c7f
Chapter 5. Managing virtual images 381
Request parameters
versionChainUUID
Response content-type
application/json
Response example
A JSON object tree of all the objects that are in the version chain. The types of
output are:
v Provenance output
{
name: "string",
description: "string"
comment: "string",
firstLinkUUID: "string",
version chain:
{
imageName: "string",
imageUUID: "string",
imageParentUUID: "string",
imageVersion: "string",
imageType: "string",
imageDeleted: boolean,
imageRoot: boolean,
children:
[
{
imageName: "string",
imageUUID: "string",
imageParentUUID: "string",
imageVersion: "string",
imageType: "string",
imageDeleted: boolean,
imageRoot: boolean,
children: [{...}, ...]
},
..., ...
]
}
}
v Version chain output
{
name: "string",
description: "string"
comment: "string",
firstLinkUUID: "string",
version chain:
[{
imageName: "string",
imageUUID: "string",
imageParentUUID: "string",
imageVersion: "string",
imageType: "string",
imageDeleted: boolean,
imageRoot: boolean,
children:
[
{
imageName: "string",
imageUUID: "string",
imageParentUUID: "string",
imageVersion: "string",
imageType: "string",
382 IBM SmartCloud Orchestrator 2.3: User's Guide
imageDeleted: boolean,
imageRoot: boolean,
children: [{...}, ...]
},
..., ...
]
} , ..., ...]
}
Return all the descendants of an image in a version chain
GET /versionChain?function=describeDescendantLinks
&versionChainUUID=<versionchain_uuid>&linkUUID=<image_UUID>
Example URL
https://localhost:9443/ImageLibrary/ImageLibrary/
versionChain?function=describeDescendantLinks
&versionChainUUID=dc4c3466-3b8c-40a7-8097-45bbc7139c7f
&linkUUID=c4a727c1-9fcc-4188-8f0a-9d168983a85c
Request parameters
versionChainUUID
linkUUID
Response content-type
application/json
Response example
A JSON object tree of all the objects that are descendants of the specified image:
{
name: "string",
description: "string"
comment: "string",
version chain:
{
imageName: "string",
imageUUID: "string",
imageParentUUID: "string",
imageVersion: "string",
imageType: "string",
imageDeleted: boolean,
imageRoot: boolean,
children:
[
{
imageName: "string",
imageUUID: "string",
imageParentUUID: "string",
imageVersion: "string",
imageType: "string",
imageDeleted: boolean,
imageRoot: boolean,
children: [{...}, ...]
},
..., ...
]
}
}
Chapter 5. Managing virtual images 383
Return all the ancestors of an image in a version chain
GET /versionChain?function=describeAncestralLinks
&versionChainUUID=<versionchain_uuid>&linkUUID=<image_UUID>
Example URL
https://localhost:9443/ImageLibrary/ImageLibrary/
versionChain?function=describeAncestralLinks
&versionChainUUID=dc4c3466-3b8c-40a7-8097-45bbc7139c7f
&linkUUID=c4a727c1-9fcc-4188-8f0a-9d168983a85c
Request parameters
versionChainUUID
linkUUID
Response content-type
application/json
Response example
A JSON object tree of all the objects that are ancestors of the specified image.
Move an image to a different version chain
Moves an image and all the descendent images to the specified version chain.
POST /versionChain/moveLinksToVersionChain
Example URL
https://localhost:9443/ImageLibrary/ImageLibrary/versionChain/
moveLinksToVersionChain
Request content-type
application/json
Request parameters
A JSON object in the HTTP body:
{
"versionChainUUID" : "the version chain UUID",
"linkUUID" : "the image UUID"
}
Success code
204
Move an image to a new version chain
Creates a new version chain and moves the specified image and all the descendent
images to the new version chain.
POST /versionChain/createNewVersionChainAndMoveLinks
Example URL
https://localhost:9443/ImageLibrary/ImageLibrary/versionChain/
createNewVersionChainAndMoveLinks
Request content-type
application/json
Request parameters
A JSON object in the HTTP body:
384 IBM SmartCloud Orchestrator 2.3: User's Guide
{
"linkUUID" : "the image UUID",
"name" : "the name of the new version chain"
}
Response content-type
application/json
Response example
{
"versionChaindUUID" : "dc4c3466-3b8c-40a7-8097-45bbc7139c7f",
"name" : "My Version Chain"
}
Edit the properties of a version chain
PUT /versionChain/editVersionChain
Example URL
https://localhost:9443/ImageLibrary/ImageLibrary/versionChain/
editVersionChain
Request content-type
application/json
Request parameters
A JSON object in the HTTP body:
{
"versionChainUUID" : "the version chain UUID",
"name" : "a new name for the version chain",
"description" : "a new description for the version chain",
"comment" : "a new comment for the version chain"
}
Success code
204
IaaS API reference
Get information about using the Infrastructure as a Service (IaaS) application
programming interface (API) for Virtual Image Library.
Virtual Image Library is registered as a new service with the SmartCloud
Orchestrator GateWay (GW) with the following characteristics:
type vil
name vil-image-service
After you get the public URL for vil-image-service from the SmartCloud
Orchestrator GW, you can invoke the Glance APIs and the extensions.
Glance API:
The following versions of Glance API are supported:
Glance API version 1.x
Version 1 Glance APIs are available at http://docs.openstack.org/
developer/glance/glanceapi.html.
Glance API version 2.x
For version 2 Glance APIs, see the section Compute at
http://api.openstack.org/api-ref.html. Implemented APIs are the ones
listed that begin with v2/images.
Chapter 5. Managing virtual images 385
OVF metadata REST API:
In Virtual Image Library, you can add files to an image, providing customization.
Using Glance, you can already add metadata as key, value pairs, but Virtual Image
Library extends this capability so you can add files that contain more information.
You can associate any file to the image, typically adding license files, translation
bundles, and multi-part files to be used during deployment. These files are
provided and returned as a compressed file and stored in Glance as an ISO image.
These images are not available to the user for deployment.
Create an ISO image in OpenStack
This API creates an ISO image in OpenStack and connects it to the specified image
by custom property. Created ISO images are not visible as valid images by Virtual
Image Library after they are created. If you run the list of available images, new
images are not displayed.
POST <VIL Service URL>/<version>/image/{id}/postOvfMetadata
where:
<VIL Service URL> is the public URL registered in the Gateway for the Virtual
Image Library image service
<version> is the PAI version that can be, for example "v1", "v1.0", "v1.1", "v2",
"v2.0". This API performs in same way for any version
{id} is the image ID in OpenStack
POST body is the compressed file that contains the metadata to be attached to the
image
Example URL
http://9.115.77.65:9973/f9c63dd430ae4f7bb3be26bd1765730f/public/ImageLibrary/ImageService/
v1/images/7de6d6e2-ea03-4500-a854-1aa4e1b74a08/postOvfMetadata
Request content-type
application/octet-stream
Request parameters
Image ID in the URL and the compressed file that contains additional
metadata files as request body
Response example
{
"name": "IBM OS Image for Fedora_Fedora-16-ec2-20111101-i386-sda-2GB.qcow2",
"container_format": "bare",
"disk_format": "qcow2",
"checksum": "f55a04393d28980602f72f481e233cc0",
"id": "7de6d6e2-ea03-4500-a854-1aa4e1b74a08",
"size": 402259968
}
To retrieve attached information
GET <VIL Service URL>/<version>/image/{id}/ovfMetadata
where:
<VIL Service URL> is the public URL registered in the Gateway for the Virtual
Image Library image service
386 IBM SmartCloud Orchestrator 2.3: User's Guide
<version> is the PAI version that can be, for example "v1", "v1.0", "v1.1", "v2",
"v2.0". This API performs in same way for any version
{id} is the image ID in OpenStack
Example URL
http://9.115.77.65:9973/f9c63dd430ae4f7bb3be26bd1765730f/public/ImageLibrary/ImageService/
v1/images/7de6d6e2-ea03-4500-a854-1aa4e1b74a08/ovfMetadata
Request parameters
Image ID in the URL
Response example
Compressed file that contains the required metadata
Return the OVF contained by the metadata
GET <VIL Service URL>/<version>/image/{id}/ovf
where:
<VIL Service URL> is the public URL registered in the Gateway for the Virtual
Image Library image service
<version> is the PAI version that can be, for example "v1", "v1.0", "v1.1", "v2",
"v2.0". This API performs in same way for any version
{id} is the image ID in OpenStack
Example URL
http://9.115.77.65:9973/f9c63dd430ae4f7bb3be26bd1765730f/public/ImageLibrary/ImageService/
v1/images/7de6d6e2-ea03-4500-a854-1aa4e1b74a08/ovfMetadata
Request parameters
Image ID in the URL
Response example
XML file that contains the OVF envelope that describes the image, if
contained by compressed file that is provided with postOvfMetadata.
Working with IBM Image Construction and Composition Tool
Use the Image Construction and Composition Tool to build virtual images for
deployment into cloud environments. Experts build particular software bundles for
reuse by others. This simplifies the complexity of image creation and reduces
errors. You can reuse and manage images and software in a cloud environment
and build and share images that are self-descriptive, customizable, and
manageable.
Creating virtual images with the Image Construction and
Composition Tool versus traditional methods
Using traditional approaches, image creation is a long and error-prone procedure
that lacks standardization and does not promote a high degree of reuse. However,
many of the operations and software content should be standardized and reusable.
A successful approach to image creation needs to ensure that while providing the
capability for reuse and standardization, images also need to be customized. This
approach has an additional challenge, that of combining reuse and standardization
while allowing for a high degree of customization and deployment into specific
environments.
Chapter 5. Managing virtual images 387
The following table compares the image creation process using a traditional
approach versus using Image Construction and Composition Tool.
Table 29. Creating an image using Image Construction and Composition Tool
Image creation
approach Process
Traditional image
creation process
Creating an image using a traditional approach is complex and
requires specialized knowledge:
1. Create a virtual machine.
2. Install and configure software on the virtual machine. This
process requires significant specialized knowledge of the
particular software.
3. Test the virtual machine and software.
4. Develop configuration scripts and edit the image metadata as
required. Requires knowledge of virtualization technology.
5. Save the disk image.
6. Test the image configuration.
Image Construction
and Composition Tool
image creation
process
Creating an image using the Image Construction and Composition
Tool involves the following steps, none of which requires specialist
knowledge:
1. Choose a base image.
2. Add a predefined software bundle.
3. The software bundle is automatically installed and configured.
4. Test the image.
5. Save the image.
Model-driven image creation
Use the Image Construction and Composition Tool to build a model of an image
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 products installed, supported
operating system, prerequisites, and requirements. Each building block also
contains the installation and configuration operations and their parameters. This
metadata makes it possible to complete validation on the model. The validation
can check, for example, if all of the prerequisites are selected and installed, if the
base image is compatible with all of the software bundles, and if the installation
order is correct. Validation is completed before installing the software physically on
a virtual machine, where the process would take longer to complete.
Automated installation process
After you create the image model, the software installation and image building
process is fully automated. It does not require any user skills or input, no matter
what the cloud environment or operating system.
Image lifecycle management
The Image Construction and Composition Tool enhances the efficiency of image
lifecycle management. Images that you create are self-describing. At a glance, you
can see the contents of the image. The images are also customizable and
manageable. You can export images to another system and other users can import
images that you create. Images created with the Image Construction and
388 IBM SmartCloud Orchestrator 2.3: User's Guide
Composition Tool have a high degree of interoperability with other IBM products
and software.
Image creation and activation
You can create images of your operating system and software content. The tool
supports multiple individuals or organizations. Content is added based on
expertise and that expertise is captured in the tool, facilitating reuse and
propagation. Image builders can use the encapsulated content created by experts to
build images without requiring in-depth knowledge of the operating system or
software installation themselves. Specialists build particular software bundles and
these bundles are then available for images builders to access when they are
creating images.
The primary users of the Image Construction and Composition Tool are:
v Operating system specialists who use the tool to specify and create base
operating system images for organizational use
v Software specialists who use the tool to specify and create software bundles
encapsulating software content
v Image builders who use the tool to build images for deployment by selecting the
operating system and software
v Cloud administrators who want to provide users of their cloud with virtual
machines with preinstalled software
Installing, upgrading, and uninstalling Image Construction and
Composition Tool
Install, upgrade, or uninstall the Image Construction and Composition Tool.
You can install the Image Construction and Composition Tool on any computer
that can connect to the virtual machines created by IBM SmartCloud Orchestrator
and all of its nodes. In the installation and upgrade, the file permissions set is 640
general files and 750 executable files.
Make sure that the following ports are open on the machine on which the Image
Construction and Composition Tool is installed:
v 22
v 80
v 443
v 445, if you are building Windows images
Note: After you have installed the Image Construction and Composition Tool, the
default ID is admin and the password is Passw0rd.
For information about how to create new images, see Creating new images or
using existing images on page 488.
Chapter 5. Managing virtual images 389
Installing IBM Image Construction and Composition Tool on
Linux
Review the requirements and install Image Construction and Composition Tool
using either a normal or silent installation.
Prerequisites
To install Image Construction and Composition Tool, ensure that the following
system requirements are met:
Hardware requirements (physical or virtual)
v Minimum requirements: 1 CPU and 1 GB of memory
v Suggested requirements: 2 CPUs and 2 GB of memory
v 60 GB of disk space, depending on your cloud providers
Additional requirements
v Ensure that additional disk space is reserved for the growth of the /drouter
directory. This directory is used by Image Construction and Composition Tool.
100 GB is recommended. If the partition is full, you can extend it using the
capabilities provided by the operating system.
v Ports 80 (default HTTP) and 443 must not be in use or reserved by other
applications.
Operating system where the Image Construction and Composition Tool can be
installed:
v SLES 11 SP1 and SP2, 32-bit and 64-bit
v RHEL 6.0, 6.1, 6.2, and 6.3, 32-bit and 64-bit. Minimal installations of Red Hat
Enterprise Linux are not supported.
For information about guest operating systems, see Supported operating systems
on page 16.
Before you begin
Before installing, you must install the 32-bit versions of the system libraries for
RHEL 6.0/6.1/6.2/6.3 x86_64 (64-bit), which are available from the OS DVD. These
libraries are not installed by default.
To install the libraries proceed as follows:
1. Access the installation media.
2. Select open a terminal window as a root.
3. Run:
[root@localhost]# mkdir /mnt/cdrom
[root@localhost]# mount -o ro /dev/cdrom /mnt/cdrom
4. Create the text file server.repo in the /etc/yum.repos.d directory.
Note: To use gedit, run:
[root@localhost]# gedit /etc/yum.repos.d/server.repo
Add the following text to the file:
390 IBM SmartCloud Orchestrator 2.3: User's Guide
[server]
name=server
baseurl=file:///mnt/cdrom/Workstation
enabled=1
where baseurl depends on the mounting point and the RHEL distribution. In
the example, the mounting point is cdrom and the RHEL distribution is
Workstation but could be server.
It is recommended to use yum instead of, for example, an RPM tool, because
another tool does not satisfy the library dependencies.
5. Run:
[root@localhost]# yum clean all
6. To import the related public keys, run:
[root@localhost]# rpm --import /mnt/cdrom/*GPG*
7. To install the required libraries, run:
[root@localhost]# yum install gtk2.i686
[root@localhost]# yum install libXtst.i686
During the installation you might receive prompts similar to:
Total download size: 15 M
Installed size: 47 M
Is this ok [y/N]: y
Answer with y.
Note: The package name extension (.i686) might change in the command
depending on the hardware platform that you use. On the x86/x86_64
platform, the package name extension on 32-bit is i686, while on 64-bit is
x86_64.
Installation steps
Note: Do not install the Image Construction and Composition Tool on any IBM
SmartCloud Orchestrator version 2.1 Linux machine where the Workload Deployer
component is already installed.
To install Image Construction and Composition Tool on Linux:
1. Insert the DVD and extract the tar file or access the Image Construction and
Composition Tool from the IBM SmartCloud Orchestrator user interface.
2. Run sh ./install. IBM Installation Manager is installed if it is not already
installed. When IBM Installation Manager is installed, it installs IBM Image
Construction and Composition Tool.
3. On the Packages page, verify that IBM Image Construction and Composition
Tool is selected and the version is correct. Click Next.
4. Accept the license agreement, and click Next.
5. Select the Shared Resources directory and click Next.
6. Accept the default installation location, or provide a location where you want
to install Image Construction and Composition Tool and click Next. The
installation location can contain English characters only.
7. Accept the default values for the language panel. Click Next.
8. On the Feature panel, ensure that IBM Image Construction and Composition
Tool is selected. Click Next.
Chapter 5. Managing virtual images 391
9. Provide a user name and password for the Image Construction and
Composition Tool instance you are installing. The password must be 8-12
characters and contain at least one number, one lowercase letter, and one
uppercase letter. These restrictions are not automatically enforced during
installation. The default password is passw0rd. Click Next.
10. Click Install.
Image Construction and Composition Tool is installed and the user interface is
available from the following web address:
https://<IP_address>/icn/ui/
Use the credentials that you provided during installation to log in to Image
Construction and Composition Tool.
Silent installation steps
To install IBM Installation Manager and Image Construction and Composition Tool
silently on Linux:
1. Go to the directory where the compressed file .tar is saved and extract the
compressed file. From the .tar file, extract the compressed file
ICCT_Install_<version>.zip.
2. Open the file install.xml in a text editor and remove the following lines:
<repository location=icon/>
<offering id=com.ibm.cloud.icon/>
3. In the compressed file that contains the Image Construction and Composition
Tool binary files, open the response file named icon/
icon_silent_install_response_file.xml. Edit the file so that the repository
location points to the icon directory in the directory where the compressed file
is extracted. This directory must contain the file repository.config. For
example:
<repository location=/path/to/icon_im_repository/icon/>
If you want to change the installation directory from the default location,
update the parameter installLocation to point to the location that you want
by updating the following line in the file:
<profile id="Image Construction and Composition Tools"
installLocation="/opt/IBM/icon"/>
The installation location can contain English characters only.
4. Generate the encrypted password for the response file by running:
<UNCOMPRESSED_DIR>/tools/imcl encryptString <password>
where UNCOMPRESSED_DIR is the directory where theImage Construction
and Composition Tool package has been uncompressed.
The password must be 8-12 characters and contain at least one number, one
lowercase letter, and one uppercase letter. These restrictions are not
automatically enforced during installation. The default password is passw0rd.
For information about providing command-line arguments and encrypting
passwords, see the IBM Installation Manager information center.
5. Set the user name and password by updating the following line in the file:
<data key=user.username,com.ibm.cloud.icon value=admin/>
<data key=user.password,com.ibm.cloud.icon value=fufgZbY47EfxLYarBAIxeQ==/>
<data key=user.confirmPassword,com.ibm.cloud.icon value=fufgZbY47EfxLYarBAIxeQ==/>
392 IBM SmartCloud Orchestrator 2.3: User's Guide
6. If installing Image Construction and Composition Tool on a computer where
IBM Installation Manager is installed, run the following command to install
Image Construction and Composition Tool:
<IM_INSTALL_DIR>/eclipse/tools/imcl input <response_file>
-log <log_file> -acceptLicense
where <IM_INSTALL_DIR> is the Installation Manager home directory. The
default directory is /opt/IBM/InstallationManager.
7. If installing Image Construction and Composition Tool on a computer where
Installation Manager is not installed, run the following command to install both
Installation Manager and Image Construction and Composition Tool:
./install --launcher.ini silent-install.ini -input <response_file>
-log <log_file> -acceptLicense
The install command is in the directory where the Image Construction and
Composition Tool binary files were extracted.
Image Construction and Composition Tool is installed and is accessible from
https://<IP_address>/icn/ui/. You can log in to this instance by using the
credentials that were used in the response file.
Upgrading the Image Construction and Composition Tool
Upgrade the Image Construction and Composition Tool using the standard
upgrade procedure or using the silent upgrade procedure.
Upgrading from a previous version:
You can upgrade from a previous version of IBM Image Construction and
Composition Tool. You can also install a fix pack on top of an existing installation.
Before you begin
You can upgrade Image Construction and Composition Tool directly from the latest
version of the product that you are using it with, or you can get the compressed
upgrade file from IBM Fix Central.
Note: When you upgrade from Image Construction and Composition Tool, you
must change your existing password. The password must be 8-20 characters and
contain at least one number, one lowercase letter, and one uppercase letter. This is
necessary only if the existing password does not respect these requirements.
Procedure
1. Download and extract the compressed file to the computer where you want to
upgrade or install the Image Construction and Composition Tool fix pack. The
format of the compressed file is ICCT_Install_<version>.zip.
2. Start IBM Installation Manager by running <IM_INSTALL_DIR>/eclipse/IBMIM.
The default value for <IM_INSTALL_DIR> is /opt/IBM/InstallationManager.
3. Add the new repository by clicking File > Preferences in Installation Manager.
The location of the new repository is <extract_dir>/icon/, where
<extract_dir> is the directory where you extracted the compressed file. Ensure
that the <extract_dir> is not the same directory that you used in previous
installations. Ensure that the Search service repositories during installation
and updates option is unchecked
4. From the Installation Manager start page, select Update. Go through the panels
to upgrade or install the fix pack.
Chapter 5. Managing virtual images 393
Results
Image Construction and Composition Tool is upgraded to the latest version.
Upgrading silently from a previous version:
You can upgrade silently from a previous version of IBM Image Construction and
Composition Tool. You can also install a fix pack on top of an existing installation.
Before you begin
Note: When you upgrade from Image Construction and Composition Tool, you
must change your existing password. The password must be 8-20 characters and
contain at least one number, one lowercase letter, and one uppercase letter.
If you want to upgrade from IBM Image Construction and Composition Tool
V1.2.0.x, do not use the instructions in this topic to complete the upgrade process.
Instead, you must uninstall Image Construction and Composition Tool while
keeping their contents of the /drouter directory, and then install the latest release
of the Image Construction and Composition Tool by using the existing /drouter
directory. For more information, see:
v Installing IBM Image Construction and Composition Tool on Linux on page
390
v Uninstalling the product on page 395
You can upgrade Image Construction and Composition Tool directly from the latest
version of the product that you are using it with, or you can get the compressed
upgrade file from IBM Fix Central.
If Installation Manager is not installed on your system, complete the following
steps before attempting to upgrade:
1. Edit the file install.xml to remove the following two lines:
<repository location=icon/>
<offering id=com.ibm.cloud.icon/>
2. Install the Installation Manager agent, by running the following command:
./installc acceptLicense
Procedure
1. Download and extract the compressed file to the computer where you want to
upgrade or install the Image Construction and Composition Tool fix pack. The
format of the compressed file is ICCT_IM_Repository_<version>.zip.
2. Important: If you are upgrading from Image Construction and Composition
Tool V1.1, you must delete or move the files from the directory
<ICCT_INSTALL_DIR>/license. The default value for <ICCT_INSTALL_DIR> is
/opt/IBM/icon.
For any other upgrade paths, do not delete or move these files, or you will get
an error message.
3. Modify the following line in <extract_dir>/
icon_silent_install_response_file.xml to point to <extract_dir>:
<repository location=/path/to/icon_im_repository/icon/>
4. Run the following command:
<IM_INSTALL_DIR>/eclipse/IBMIM --launcher.ini <IBM_INSTALL_DIR>/eclipse/silent-install.ini
-input <extract_dir>/icon_silent_install_response_file.xml -acceptLicense
394 IBM SmartCloud Orchestrator 2.3: User's Guide
Results
Image Construction and Composition Tool is upgraded to the latest version.
Uninstalling the product
You can uninstall a fix pack or uninstall the IBM Image Construction and
Composition Tool completely.
Uninstalling a fix pack:
About this task
You can uninstall a fix pack to roll back to a previous maintenance level. To
uninstall a fix pack:
Procedure
1. Start Installation Manager.
2. Click Roll back.
3. Select the maintenance level to be rolled back.
4. Go through the rollback panels to uninstall the fix pack.
Results
The fix pack is rolled back to the maintenance level that you selected.
Uninstalling the Image Construction and Composition Tool:
About this task
To uninstall the Image Construction and Composition Tool:
Procedure
1. Export any bundles or images created with the current Image Construction and
Composition Tool version. For information about exporting, see your cloud
provider documentation.
2. Stop the Image Construction and Composition Tool by running the following
command from the directory that you specified during the installation:
stop.sh
3. Start the uninstallation wizard by running the following command:
/opt/IBM/InstallationManager/eclipse/IBMIM
Note: If you installed silently, the /opt/IBM/InstallationManager/eclipse/
IBMIM directory does not exist. In this case, to uninstall, use the command:
<install_images>/tools/imcl uninstall com.ibm.cloud.icon
4. After completing the wizard, remove image and bundle repositories by running
the following command:
rm -rf /drouter/*
Chapter 5. Managing virtual images 395
Uninstalling the Image Construction and Composition Tool silently:
About this task
To uninstall the Image Construction and Composition Tool silently:
Procedure
1. Export any bundles or images created with the current Image Construction and
Composition Tool version.
2. Stop the Image Construction and Composition Tool by running the following
command from the directory that you specified during the installation:
stop.sh
3. Uninstall the Image Construction and Composition Tool by running the
following command:
/opt/IBM/InstallationManager/eclipse/tools/imcl uninstall com.ibm.cloud.icon
Note: If you installed silently, the /opt/IBM/InstallationManager/eclipse/
IBMIM directory does not exist. In this case, to uninstall, use the command:
<install_images>/tools/imcl uninstall com.ibm.cloud.icon
4. Uninstall IBM Installation Manager by running the following command:
/var/ibm/InstallationManager/uninstall/uninstallc
5. Remove image and bundle repositories by running the following command:
rm -rf /drouter/*
Getting started
Understand system requirements, how to configure and start the Image
Construction and Composition Tool, and how to configure the tool to begin
building virtual images.
The basics
To get started, you can familiarize yourself with the basics of Image Construction
and Composition Tool.
When you access the Image Construction and Composition Tool for the first time,
you are prompted to create a cloud provider definition. All actions performed are
based on a cloud provider.
The Welcome page contains links to each of the main Image Construction and
Composition Tool pages that provide access to the key functions of the tool. The
main pages are briefly described in the following table.
396 IBM SmartCloud Orchestrator 2.3: User's Guide
Table 30. Main Image Construction and Composition Tool pages
Page You can:
Images
v Import virtual images from your cloud provider
v Create virtual images
v Extend virtual images
v Capture virtual images
v Delete virtual images
v Search for virtual images
v Share software bundles by either importing them from or
exporting them to a remote system
v Create software bundles
v Extend software bundles
v Publish software bundles
v Delete software bundles
v Search for software bundles
Administer
v Configure cloud provider
v Change password
v Download log files
Universal identifiers
When you create virtual images, bundles, and other assets, you enter a unique
universal identifier (ID) for the asset.
The Image Construction and Composition Tool creates a universal identifier for
you. The universal ID identifies an Image Construction and Composition Tool asset
across different repositories.
The universal ID uses an Open Service Gateway Interface (OSGI) notation, with a
reverse domain name and a version in the format major.minor.macro and an
optional qualifier, for example, com.ibm.images.was_1.0.0 for a WebSphere
Application Server base virtual image. In this example, the version is not the
WebSphere Application Server version, it represents the virtual image version. In
general, you can use any dotted notation to create a universal ID, for example
icct.image.base.rhel56_1.0.0.
Based on universal ID, bundles can be looked up independently from the
repository in which they are stored. If there are different bundle repositories, the
virtual image builder or Image Construction and Composition Tool can assume
that if two assets have the same universal ID, they are identical and the tool can
use either. The universal ID is required and provides a unique way of referencing
an Image Construction and Composition Tool asset across several repositories.
Universal IDs combined with version
If you enter a universal ID with a version, you can enter the same universal ID
value for multiple assets if you enter a different value in the version field.
These values provide uniqueness to assets across repositories, allowing resources to
be identified. For the universal ID value, you can use alphanumeric characters, an
underscore, a dash, or a period. A period is not allowed as the first character. For
version, the format is: <major>.<minor>.<micro>.<qualifier> where major, minor, and
Chapter 5. Managing virtual images 397
micro are all numeric and required, while qualifier is optional and can contain the
same type of characters as the universal ID.
Related tasks:
Creating software bundles on page 412
You can create software bundles for software installations on your virtual image.
To create software bundles, you must have expert knowledge of the software to
include. The software bundle can be accessed by other users who can then add it
to the virtual images that they create.
Extending software bundles on page 417
You can extend a software bundle to create a new software bundle.
System requirements
Ensure that your system meets the virtualization and browser requirements for
using IBM Image Construction and Composition Tool.
Windows targets
For Windows targets supported by the Image Construction and Composition Tool,
see Prerequisites for KVM or VMware images on page 494.
Operating system targets
For target operating systems supported by the Image Construction and
Composition Tool, see Supported operating systems on page 16.
Browser requirements
The following browsers are supported:
v Mozilla Firefox V10 or V11
v Microsoft Internet Explorer V7, V8, or V9 (in V8 compatibility mode)
Ensure that the following requirements are met:
v JavaScript is enabled in the browser.
v The minimum recommended screen resolution is 1024 by 768.
Changing your user password
You can change your Image Construction and Composition Tool user password
using these steps.
Before you begin
Note: When you upgrade from Image Construction and Composition Tool V1.2.0.0
to V1.2.0.1 or later, you must change your existing password.
Procedure
1. Click Administer > Change password.
2. Enter your new password in the New password field and verify it. Password
requirements are:
v Alphanumeric characters only.
v Minimum of 8 and maximum of 20 characters.
v At least one uppercase character.
v At least one lowercase character.
v At least one number.
398 IBM SmartCloud Orchestrator 2.3: User's Guide
3. Click OK.
Managing the Image Construction and Composition Tool server
You might need to start or stop the Image Construction and Composition Tool
server.
To start or stop the Image Construction and Composition Tool server, run the
following commands from the directory that you specified during the installation.
Start the server
start.sh
Stop the server
stop.sh
Managing the firewall
When extending an image, if you enable the firewall on the virtual machine after
synchronize and before capture, ensure that the ports that are required for SSH
communication are open for inbound and outbound traffic. Access is required for
the Image Construction and Composition Tool to complete the image building
process.
For information about opening ports, see your operating system documentation.
Redhat Linux
cat /etc/sysconfig/iptables | grep 22
cat /etc/sysconfig/ip6tables | grep 22
SUSE Linux
cat /etc/sysconfig/SuSEfirewall2 | grep 22
AIX
lsfilt v 4
Lists all of the ipv4 ports. Check if port 22 is in the list.
lsfilt -v 6
Lists all of the ipv6 ports. Check if port 22 is in the list.
Configuring cloud providers
You can configure a cloud provider for Image Construction and Composition Tool.
The first time you open Image Construction and Composition Tool, you see the
Create a new cloud provider wizard. If the wizard does not open automatically, to
configure the cloud provider, click Administer > Manage cloud providers and
then .
Important: You cannot edit your cloud provider configuration after it is created.
Chapter 5. Managing virtual images 399
Configuring the OpenStack cloud provider:
Configure OpenStack as your cloud provider.
Procedure
1. On the Create a new cloud provider Welcome page, click Next.
2. On the General page, enter the name, description, and enter OpenStack as the
cloud provider type. Click Next.
3. On the Credentials page, enter the following information:
v User name: Enter a Keystone user name. Make sure that the user has an
administrative role.
v Password: Enter a password for the Keystone user.
v Connection type: Select Indirect through the IBM IaaS Gateway.
Note: If you select Direct to OpenStack, the image created does not have
the associated metadata and the image created cannot be correctly managed
by IBM SmartCloud Orchestrator.
v IBM IaaS Gateway server: The server can be either the host name or IP
address.
Click Next.
4. In the Cloud details page, select the tenant and region. The tenant list includes
only tenants that your user can access and manage. The region list include any
region for the selected tenant. Click Next.
5. Click Done.
Working with virtual images
You can build virtual images.
The virtual images created by the Image Construction and Composition Tool
contain all the information required for specific deployment platforms to create
specific deployed VM instances.
The virtual images that you create will include the Open Virtualization Format
(OVF) file and other metadata to support Workload Deployer patterns, including
being able to provide configuration parameters during the pattern deployment
process. The tool creates Open Virtualization Archive (OVA) formatted virtual
images, ready for import and use in Workload Deployer. The OVA includes OVF
extensions to be used in the Workload Deployer pattern editor.
In many organizations, virtual image creation is logically divided into two roles,
although one person can perform both roles if they have the knowledge:
Operating system specialist
Creates the base operating system virtual images following company and
cloud specifications.
Virtual image builders
Uses these base virtual images and adds software content, such as
middleware and applications. Virtual image builders can reuse resources
such as software bundles that were created by other experts. Some
software bundles, for example DB2
or WebSphere Application Server
software bundles can be specialized and complex, and the virtual image
builder does not need to be involved in their creation. Instead, the virtual
image builder reuses the software bundles created by the DB2 or
400 IBM SmartCloud Orchestrator 2.3: User's Guide
WebSphere Application Server specialists and needs only to work with the
parameters and configuration made available by the specialists.
To work with virtual images, click Build and Manage Images on the Welcome
page.
Importing base images from OpenStack
You can import base images from OpenStack.
About this task
Before you can import base images from OpenStack, you must configure
OpenStack as a cloud provider.
Procedure
1. Select the OpenStack provider in the upper right corner drop-down list.
2. Click Images > Build Images from the Image Construction and Composition
Tool main menu.
3. Click .
4. Select the image that you want to import from the list of images that are
displayed in the left pane of the Images page. You can search for images by
name or keyword.
5. Select the images that you want to add, and click Add. The actual image
content does not transfer to Image Construction and Composition Tool, only a
copy of the metadata is saved to Image Construction and Composition Tool.
6. Click Import.
What to do next
Note: If you move a Linux image from KVM to VMware or vice versa, the final
image might have problems starting, if, in /etc/fstab, it is using:
v /dev/sda1 for VMware
v /dev/vda1 for KVM
For Linux images that are internally using a disk name in /etc/fstab, moving
these images from KVM to VMware or vice versa, the disk name changes from
/dev/vda1 to /dev/sda1 and vice versa. To avoid complications, before
synchronizing, modify the images before migrating them or modify the fstab file
after migration.
Building virtual images
You can build a virtual image by selecting a base image, adding one or more
software bundles, and specifying the installation and configuration requirements.
To work with virtual images, click Build and manage images from the Welcome
page.
About this task
This task describes the high level tasks involved in creating a virtual image. Each
of these tasks is described in detail in subsequent topics.
Chapter 5. Managing virtual images 401
Install(automatic)
Chooseabaseimage
Addsoftwarebundle
Savediskimage
Test
Procedure
1. Choose a base image: Select the base operating system virtual image and use
the Extend option to copy the information about the base virtual image into
Image Construction and Composition Tool. The tool does not copy or modify
the base OS virtual image during this step.
2. Add software bundle: Select the software bundles to add to the new virtual
image and specify the installation and deployment parameters for the software
bundle. This step creates a list of software to install on the virtual image. The
tool does not install the actual software during this step.
3. Install (automatically): Save the new virtual image definition and synchronize
it. The synchronization process starts your base virtual image in the build
environment, installs the software bundle, and then performs any additional
configuration specified in the software bundles. The Image Construction and
Composition Tool starts a deployed VM from the base operating system virtual
image, and during this step, files are copied and installation tasks run.
4. Optional: Test: Manually log on to the deployed VM and test the correct
installation of the software bundles.
5. Save disk image: After testing, save the virtual image.
402 IBM SmartCloud Orchestrator 2.3: User's Guide
Extending virtual images:
You can extend a virtual image to customize the parameters of a base image.
About this task
When you extend a virtual image, you clone it so you can reuse the original image
without having to rebuild it from the beginning every time.
Note: You can use wildcard searches to search for a virtual image.
Procedure
1. From the Welcome page, click Build and manage images.
2. Select the virtual image that you want to extend and click .
3. Enter the following details in the Extend an Image dialog box:
Name Enter a name for the new virtual image that you are creating. The name
you enter must not exceed 50 characters.
Universal ID
Enter a unique identifier for the new virtual image that you are
creating.
Version
Enter a unique version number for the new virtual image that you are
creating.
Description
Optional. Enter a description for the new virtual image that you are
creating.
4. Click Create to extend the virtual image.
Results
You are ready to start configuring the extended image.
Adding software bundles to virtual images:
You can use a software bundle to add software content to a virtual image.
About this task
If you add a bundle to an image, and the bundle is in planned state and you
change the bundle, the bundle already added to the image is a copy of the old
bundle. You must delete and add the bundle to the image to pick up the bundle
changes before synchronization.
Note: In a Linux operating system, during synchronization, the Image
Construction and Composition Tool copies the bundles files to the /tmp directory.
The Linux images must allow execution under /tmp for the activation engine to be
installed. For the enablement bundle, the space in the /tmp directory must be 15
MB. You can calculate the total space needed in the /tmp directory by adding the
bundles size that must be installed in the base image.
Chapter 5. Managing virtual images 403
Procedure
1. Click to start configuring the extended virtual image. You can change the
name and description for the new virtual image on the page that is displayed.
2. Click the Software Bundles section and click .
3. Select the software bundles that you want to include in the virtual image and
click Add. Use the icons to specify the order of installation for the
software bundles into the virtual image. The Up and Down arrow icons are
displayed only for planned software bundles, not for software bundles that are
already installed.
4. Click a software bundle to see its parameters. If the software bundle creator
provided configuration options for the software bundle, the first set of
parameters is displayed in the Install Parameters section. The second set of
parameters defines configuration options that are made available during the
deployment of the virtual image.
5. Review the values for Licenses and Products and identify if you want to
change any parameters or accept the default values. The Products values
cannot be changed.
6. Review the values for Install Parameters and identify if you want to change
any parameters or accept the default values. If needed, customize these
parameters for the specific virtual image that you are creating. Installation
parameters are used during virtual image synchronization to install the
products in the software bundle. For example, if you are installing a DB2
software bundle, you might need to specify parameters values for DB2 binary
files or the location of a DB2 response file. Ensure that all parameters have a
value assigned and that the parameter settings match your specific
requirements. Otherwise, you might encounter errors in the virtual image or
during run time.
7. Review the values for Deploy Parameters and identify if you want to change
any parameters or accept the default values. These parameters define the
default parameter values used during virtual image deployment when the
selected personality is deployed. The deployment parameters are used to
customize the product for the environment for which they are being created,
for example, an LDAP server host name and port numbers. You can make the
deployment parameters configurable or not at deployment time by clicking the
corresponding Lock icon.
8. When you are done with your changes, click .
Results
As you edit the virtual image, missing or invalid input is highlighted and any
validation messages are displayed in the validation status section. When you save,
semantic validation is performed to ensure that the virtual image definition is
consistent. For example, if the specified software bundle order satisfies any
dependency requirements. This validation is performed by the server and is done
only when you save your changes. The validation report entries have three
severities, info, warning, or error. If your virtual image has any error severity
validation entries, any synchronize or capture action for the virtual image is likely
to fail. Even if the synchronize or capture action succeeds, the resulting virtual
image might not be usable.
404 IBM SmartCloud Orchestrator 2.3: User's Guide
Adding licenses to virtual images:
You can add licenses in any language to a virtual image.
About this task
When you edit a new or extended virtual image, you can add or delete licenses.
You can add licenses for any supported language and multiple translations of the
same license.
Note: Licenses must be text files. Other formats are not supported.
Procedure
1. Click to start configuring the extended virtual image. If you want, you
can change the name and description for the new virtual image on the page
that is displayed.
2. Click the License section, and click .
3. Enter a license name and select the language for the license. Click Browse to
select the file for upload, then click Add.
4. Repeat steps 2 and 3 for additional licenses.
5. When you are done with your changes, click .
Adding personalities to virtual images:
A personality is a set of custom configuration settings for a subset of software
bundles in a virtual image. All the software bundles defined for the image are
always installed, even if they are not in the personality that is used. During
deployment, only the software bundles that are included in the personality are
configured, according to the deployment parameters specified in the personality.
Before you begin
Personalities are useful when you want to create an image that supports a common
set of software with multiple configuration options.
Using WebSphere Application Server as an example, you might have the need to
be able to deploy an entire WebSphere cluster, consisting of a deployment
manager, custom nodes, and an HTTP server. Each of these VMs in the cluster
consist of the same software; they all have WebSphere Application Server installed.
They differ only in the way they are configured.
Without personalities, you must create a separate image for each of these
configurations. This uses a lot of space and results in duplicated effort. But, using
personalities, you can create a single image with the required software installed,
and create different configuration settings for the image by creating multiple
personalities with different software selected or configuration values set in each.
About this task
The concept of personality in Image Construction and Composition Tool maps to
the concept of a virtual system image part in IBM SmartCloud Orchestrator.
Chapter 5. Managing virtual images 405
Procedure
1. To start configuring the extended virtual image, click . You can change
the name and description for the new virtual image.
2. To add a personality, click the Personalities section, and click
.
3. In the Add personality to image dialog box, review and complete the
information:
Name Enter a name for the personality that you are adding.
Note: The personality name is the part name in the captured image. If
you want the part name to be different from the part name in the base
image, change the personality name before you run the synch operation
in Image Construction and Composition Tool.
Description
Optional. Enter a description for the personality that you are creating.
Key Enter a unique identifier for the personality within the image.
Product GUID
This field cannot be changed.
Enter a unique identifier for the product GUID within the image.
Supports IPv6
Check this box if you want the personality to support both IPv4 and
IPv6. If cleared, the personality supports IPv4 only.
Enable instance count selection
Check this box if you want to indicate that multiple instances of the
personality can be included in a virtual system pattern. In the Pattern
Editor window, you can specify the number of instances to create for
the corresponding part.
Enable dynamic instance count
Check this box if the image supports dynamic resizing of the number
of instances at run time. By using this option, you can add or remove
instances from a deployed virtual system pattern.
4. Select the software bundles that you want to include in the personality. You can
select only software bundles that exist in the image. By default, all personalities
include the OS and Enablement software bundles. When you are done, click
Add.
5. Click a software bundle and review the values for Deploy Parameters and
identify if you want to change any parameters or accept the default values.
These parameters define the default parameter values used during virtual
image deployment when the selected personality is deployed. The deployment
parameters are used to customize the product for the environment for which
they are being created, for example, an LDAP server host name and port
numbers. You can make the deployment parameters configurable or not for this
personality, by clicking the corresponding Lock icon.
6. When you are done with your changes, click .
406 IBM SmartCloud Orchestrator 2.3: User's Guide
Results
As you edit the virtual image, any missing or invalid inputs are highlighted any
messages are displayed in the validation status section. When you save, your
changes are validated to ensure that the virtual image definition is consistent, for
example, if the specified software bundle order meets any dependency
requirements. The validation report contains the following entries: info, warning,
or error. If your virtual image has any error entries, any synchronize or capture
action for the virtual image is likely to fail. Even if the synchronize or capture
actions succeed, the resulting virtual image might not be usable.
Synchronizing virtual images:
Synchronization is the process where Image Construction and Composition Tool
creates a running deployed VM from the base operating system virtual image that
you specify. After that, it executes the selected software bundles into the
environment, by copying files and running scripts as defined in the software
bundle. The software bundles are executed according to the order specified in the
virtual image definition.
Before you begin
When you perform synchronization in Image Construction and Composition Tool,
use the Administrator user.
About this task
To synchronize a virtual image, the image must be extended and have software
bundles in a planned state. Any software bundles that were previously executed as
part of a synchronization process are not executed again if you synchronize the
virtual image. For more information, see Extending virtual images.
Procedure
1. Click Images and then Build images. Select the extended virtual image with
the planned software bundles that you want to synchronize.
2. Click Synchronize. The Cloud provider parameters wizard is displayed if the
image has any deployment configuration parameters. The wizard prompts you
to enter values for the deployment parameters. Select a cloud provider
availability zone where the image is present.
Note: If the image is a non-English Windows image, for example, a Chinese or
Japanese Windows image, before you click Synchronize, ensure that the
following parameters are correctly configured:
For a Chinese Windows image:
Default Locale zh
Default Country ZH
Default Encoding < leave this one blank
For a Japanese Windows image:
Default Locale ja
Default Country JP
Default Encoding < leave this one blank
Chapter 5. Managing virtual images 407
Note: If you do not see certain values for flavor, network, or cloud provider
availability zone, you can run a cloud provider refresh by performing the
following steps:
a. Go to Administer > Manage cloud provider.
b. Select your own cloud provider.
c. Click .
The new values are displayed in the cloud provider parameters wizard.
3. As the synchronization process proceeds, any license terms and conditions
contained as part of the virtual image are displayed, along with a list of
bundles already in the virtual image or to be included in the virtual image. You
must accept the terms and conditions for the synchronization to proceed.
4. Click to view the progress of the synchronization process. You can
perform the synchronize step multiple times. If you synchronize a virtual image
more than once, each synchronization executes any additional planned software
bundles. After executing a software bundle, the tool moves that software
bundle to the Installed section under the Software tab for the virtual image.
If the synchronization process fails, you can edit the list of planned software
bundles. Then resynchronize by clicking Synchronize again. When you
resynchronize, use the same password as the one from the previous
synchronization operation.
Note: After a failure, resynchronization of the virtual image deletes the
deployed virtual machine and starts the synchronization step from a new state.
That is, it deploys a new instance of the base image and it installs all planned
bundles no matter how many intermediate synchronization steps were
successfully completed.
If there are errors detected, you are prompted to confirm that you want to
proceed with the synchronization. Errors do not prevent synchronization from
completing. If errors are reported during a synchronization process, some of
these errors might cause a failure of the virtual image. If the synchronization
process is successful, the resulting virtual image might not be usable.
Investigate any errors reported and make sure that they are not significant.
Results
When the synchronization process starts, a deployed VM is created by using the
base virtual image. After the deployed VM is created, its IP address and host name
are visible in the Virtual System section on the virtual image details panel.
You can also download the log files for the installation scripts from the console, by
expanding Virtual System and clicking Download logs. For more information, see
Log files for virtual image synchronization on page 469. You can also connect to
the deployed VM using SSH to review other logs generated by the bundle.
408 IBM SmartCloud Orchestrator 2.3: User's Guide
Capturing virtual images:
You can capture a virtual image when the image is in the synchronized state.
About this task
The actions that occur during a capture depend on the cloud provider that you are
using.
For a synchronized cloud provider image, the capture process captures the
updated disks from the deployed VM and creates a new, updated, physical copy of
the virtual image disks. Image Construction and Composition Tool stores the new
virtual image in the local repository.
Procedure
1. Clean up your hard disks. Ensure that there is nothing on the hard disks that
you do not want to be captured. Whatever is on the hard disks when the
capture is performed is available to the user of the image. Depending on your
situation, perform the following steps:
a. Delete any files and directories that you do not need, including any
software binary files used during the installation and configuration of this
VM.
b. Unmount any disks used during the installation and configuration of the
VM that are not to be available to the VM after a capture is performed.
c. Disks that are copied during capture are compressed to save disk space. To
ensure efficient compression, all free disk space is automatically zero filled.
2. To start the capture process, click Capture.
Creating virtual images from a template:
You can use an existing virtual image as a template to create another virtual image.
About this task
To create an image by using an existing virtual image as a template, select the
virtual image that you want to use as the template. Before using an existing
template to create an image, verify that the contents of the template is correct and
that you can edit the image. Then select a base virtual image to extend with the
virtual image you used as a template. When applying a template, Image
Construction and Composition Tool focuses on the products mentioned by the
template, regardless of the bundles from which they come. You do not have to use
the same bundles as the bundles in the template.
When you are using a template to create a virtual image, Image Construction and
Composition Tool identifies the valid base virtual image options for your virtual
image rather than listing all of the base virtual image options available from your
cloud provider. You can use a virtual image template to create a virtual image even
if there are no bundles defined in the virtual image that you are using as a
template.
Procedure
1. From the Cloud Provider menu, select your cloud provider.
2. From the Welcome page, click Build and manage images.
Chapter 5. Managing virtual images 409
3. Click and then click Create image from a template image. Click Proceed.
4. From the General section on the Create Image wizard, enter a name, universal
ID, version, and description for your virtual image. Click Next.
5. From the Template section of the Create Image wizard, select a template to use
for the virtual image that you are creating. To choose a template, you select a
virtual image that has software products that you want to include in the virtual
image that you are creating. Click Next.
6. Optional: From the Base Image section of the Create Image wizard, select a
base virtual image from the completed virtual images of the target cloud
provider.
If you select a base virtual image, the base virtual image that you select is the
base for the new virtual image to be created.
If you do not select a base virtual image, Image Construction and Composition
Tool checks all base virtual images of the target cloud provider that are
compatible with the template virtual image. Click Next.
The Image Construction and Composition Tool searches for solutions that
match the template virtual image that you selected. A solution comprises a base
virtual image plus any software bundles. After the search is completed, you see
up to 10 closest matching solutions. Each solution comprises one base virtual
image and any software bundles. The top-ranking solution is selected by
default, but you can browse through all solutions and choose any one. A
solution with no software bundles corresponds to a virtual image that exists,
and therefore does not need to be created. A solution with at least one software
bundle corresponds to a virtual image that Image Construction and
Composition Tool creates for you using the name, universal ID, version, and
description that you provided.
7. From the Summary section of the Create Image wizard, select the virtual image
that you want and click Done.
Managing software bundles
A software bundle contains and describes the software available for use in a virtual
image. The software bundle includes information about how to install the software,
prerequisites of the software, and parameters available for customizing the
software.
You can use the existing sample bundles or you can define your own bundles.
Creating a software bundle requires specialized knowledge of how the software
works and is normally completed by a software specialist. Because the software
specialist creates the bundle, the virtual image builder using the software bundle
does not require understanding of the specifics of installation, activation, and reset
of the software.
Understanding the integration between Image Construction and Composition Tool
and the deployment tools helps in designing your bundles. The software bundle
specification uses a process where a set of installation tasks is performed once, by
the virtual image builder initially creating the virtual image. A set of configuration
tasks is then performed for each virtual image deployment. The recommendation is
to define common tasks for all instances or time-intensive tasks, such as, installing
large binary files, as part of the software bundle installation so the tasks run only
once. Along with the installation tasks, the software bundle provides for different
deployment-time configurations of the software. The use of deployment-time
configuration parameters reduces the number of virtual images that you require by
410 IBM SmartCloud Orchestrator 2.3: User's Guide
providing you with a means of customizing the software for each deployment.
Preparing to create software bundles:
Before you create a software bundle, prepare the necessary information.
The following list describes information that you can specify for each software
bundle that you create:
Requirements
You can list prerequisites, for example, operating system and version, in
the requirements section of a software bundle. A prerequisite check is
performed when you add a software bundle to a virtual image.
Installation tasks
You can define the files to copy and the command to run to install the
software. If the binary files are not included in the bundle, you must
provide the information to automate the transfer of files and execution of
your installation program. If the binary files are included in the bundle,
they are transferred by Image Construction and Composition Tool.
You can also define parameters to your installation scripts, such as the
mount points in your virtual image and the target location for the
application you are installing.
Activation tasks
Virtual images can capture the state of a system, including preinstalled and
preconfigured software. Along with preserving an installed software stack,
virtual images also preserve the configuration of that software. Some of the
software configuration, for example, IP addresses, host names, user names,
passwords, and other parameters, might vary for each deployment of the
virtual image.
Instead of manually updating this dynamic configuration information after
each activation process, you can define tasks that run during the virtual
image activation process and make the necessary configuration updates.
You can define activation scripts for configuration updates that run during
the virtual image deployment process. These scripts are used for
deployment time reconfiguration of settings based on data such as new IP
addresses, host names, and other deployment characteristics. You define
these activation scripts and any associated parameters, and they are copied
into the virtual image during the synchronize step.
The base operating system virtual images used with the OpenStack Cloud
Provider must contain the provided IBM Virtual System Activation Engine.
Any activation tasks you specify as configuration steps in the bundle are
automatically added. This means that your activation scripts are performed
automatically as part of the virtual image deployment process. Any
activation scripts that you provide run after the scripts included in the
Activation Engine. The activation process follows the Open Virtualization
Format (OVF) standard.
Firewall rules
The firewall information in the bundle can be used to open the native
operating system firewall ports on the virtual machine running the image.
Reset tasks
The virtual image build process starts the deployed VM and software
installed in the virtual image. You can include scripts to clean up and reset
Chapter 5. Managing virtual images 411
any files that you do not want in the final virtual image. For example, you
might want to reset passwords, or remove log files or temporary
passwords generated during the virtual image creation process before
using the virtual image for deployments. Reset scripts are run just before
the virtual image is captured to reset the virtual image state to ensure that
any unplanned content is not captured. When creating a software bundle,
if a software bundle installation added a state to the virtual image, the
software bundle creator can provide a reset script to clean up that state.
Creating software bundles:
You can create software bundles for software installations on your virtual image.
To create software bundles, you must have expert knowledge of the software to
include. The software bundle can be accessed by other users who can then add it
to the virtual images that they create.
Before you begin
About this task
The software bundles that you create are validated.
Procedure
1. On the Welcome page, click Build and manage software bundles and click
.
2. Enter a name, universal ID, version, and optionally, a description. From the
Storage Location menu, choose where you want to store the software bundle.
For information about the relationship between the universal ID and version,
see Universal identifiers on page 397.
If you want to enable software bundle creation by using IBM Installation
Manager, select Uses IBM Installation Manager. The Create a New IM
Bundle wizard is displayed. Complete the wizard and click Create.
Note: For each password-protected Installation Manager repository, you must
provide the repository URL, the repository user name, and the repository
password on the Install tab.
A script file is generated to complete the following tasks:
v Disables SELinux which is required by IBM Installation Manager.
v Optional. Creates product installation system user.
v Downloads and installs IBM Installation Manager from public repositories.
Note: The virtual machine that is created during synchronize must be able
to access the internet to access the Installation Manager binary files.
v Creates a credential file for password-protected repositories.
v Installs the product by using IBM Installation Manager.
3. Add any additional information to the General tab. You can enter details for
the publisher and the products in the software bundle.
4. To create prerequisites, complete the following steps:
a. Click the Requirements tab.
b. Click to add requirements for operating systems, software, or
bundles. If you are adding supported operating system requirements,
412 IBM SmartCloud Orchestrator 2.3: User's Guide
complete the Supported Operating Systems section for your software
bundle, describing the supported operating system, operating system
distribution, architecture, and version requirements.
c. Complete the Required Software section to specify the software
requirements for your software bundle. You can enter the name of the
software and the version.
d. Complete the Required Bundles section to specify the bundles that are
required for the installation. You can choose from bundles available in the
bundles repository. To add bundles, select the software bundle from the
list and click Add.
The supported operating systems are checked against the operating system in
the base virtual image selected by the virtual image builder. The software
prerequisite information is checked against other software bundles selected for
or installed in the virtual image. To use software prerequisites, ensure that the
name provided for the Name field matches the name of the software bundle
on which there is a dependency.
5. Specify how to install the software content on the Install tab, following the
steps that are described in the following table:
Chapter 5. Managing virtual images 413
Table 31. Specify the software to install on your instances
Task Description
1. Specify files to copy
to the targets
Specify the software installation packages that you want to install
on the targets from the Install tab. You must also include any
installation scripts that are required for the installation:
1. In the Files to copy section, click .
2. Select the files that you want to copy to the target. All of the
files that you select are included in the same directory before
the Run Command runs. You can upload files from your local
system or from a remote system. Select the Upload and
package with bundle option if you want the file to be copied
into the software bundle. If you do not select the Upload and
package with bundle option, the file is copied to the virtual
image from which the software bundle is installed.
3. Select Make executable if the file that you are uploading is an
executable file.
4. Click Upload. The files that you include are displayed as a
hyperlink that you can click and download after you created
the software bundle.
Important: Ensure that the scripts that you are using to install the
software return a zero value to indicate successful installation. The
installation script must check for error conditions relevant to the
installation of the software bundle. For errors that you think
compromise the software bundle installation, ensure that an exit
code value greater than zero is returned, indicating failure. If a
script returns no exit code explicitly, the exit code of the last
command of the script is implicitly returned. Make sure that the
software bundle installation script can accept parameters in the
following format:
scriptname -parameter1 <parameter1 value> -parameter2
<parameter2 value>
You must save your installation script in the correct format for
your operating system. For a sample installation script, see Virtual
image synchronization fails because of return code value on page
485.
Note: If you upload scripts from a Windows system to Image
Construction and Composition Tool installed on an AIX or UNIX
system, you must remove the ^M characters from the script files
before you upload them onto Image Construction and Composition
Tool. If cygwin is installed on your Windows system, you can use
the dos2unix command to clean up the script files.
2. Specify the
command to install
the software
From the Run Command menu, select a command to install the
software. The command is run from the directory to which it was
copied. It can reference entries that are selected for Files To Copy
by using only the file name, because all files are in the same
directory. One directory is created per software bundle being
added to the virtual image Conflicting file name are not allowed.
414 IBM SmartCloud Orchestrator 2.3: User's Guide
Table 31. Specify the software to install on your instances (continued)
Task Description
3. Specify the user
that installs the
software
In the Run as field, specify one of the following users:
v For Windows operating systems, the Administrator user. When
this user is specified, the internal user NT Authority\System is
used.
v For UNIX and Linux operating systems, the root user. You must
run the script as the root user.
Note: The user is not created or validated on the deployed VM.
Ensure that you specify a valid user.
4. Define the
parameters that the
installation scripts can
access
In the Arguments section, define parameters that your installation
scripts can access. To define an installation parameter, define a
name, label, and value. The Name column defines the name by
which your scripts access the parameter, for example, the
environment variable name. Use the Label column to specify the
display name in Image Construction and Composition Tool. The
Value column represents the default value for the parameter. You
can override the default values before the installation process. If
you want the value to be hidden from view, check Hide Value.
If you are using IBM Installation Manager for software bundle
creation, values such as repoURL, repoUserName, and repoPassword
values are displayed in the Arguments list.
6. To define activation scripts and other artifacts necessary for deployment-time
configuration, click the Configuration tab to configure the software in a new
instance of a deployed VM. Complete the following steps:
a. In the File To Copy section, define the location of the files that you want
to copy or upload them from your local machine and the target location in
the virtual image. The files that you include are displayed as a link. Users
can click and download the files after you created the software bundle.
b. After you define the necessary files to copy, define the different
configuration steps that are required for successful activation. First, define
an operation name. A service name is created based on the operation
name. The service name is the name of the operating system service that is
automatically created during the synchronization process. The service is
placed in the /etc/init.d directory on the virtual image. The operation
name becomes the name of the configuration step in the activation engine.
c. From the Run Command menu, select an option for the command to run
during the configuration step. You can define parameters to be available to
your activation scripts in the Arguments section. You can click an existing
parameter or create a parameter for the activation script.
When you include the software bundle, a number of events occur during the
synchronization process:
a. The ConfigSample.sh script is copied to the Activation Engine directory. It
is copied to either /opt/IBM/AE/AS or /opt/ibm/ae/AS for Activation Engine
2.1.
b. A new operating system service is added in the /etc/init.d directory
named ConfigSample.
c. A new configuration step named ConfigSample is added to the list of steps
that are saved in the activation engine metadata. The data for this step
includes information about what command to run during the completion
Chapter 5. Managing virtual images 415
of the step. This information comes directly from the command you enter
in the Run Command field for the software bundle in Image Construction
and Composition Tool.
The result of adding the configuration step is that during the virtual image
deployment process, the new ConfigSample operating system service starts.
This service invokes the core components of the IBM Virtual System
Activation Engine, and submits the name of the configuration step to start, in
this example, ConfigSample. The activation engine searches the information for
the ConfigSample step, and starts the /opt/IBM/AE/AS/ConfigSample.sh script
that you provided and that was previously copied into the virtual image. The
activation engine passes all of the parameters and their values that are listed
in the Arguments section as arguments to the script.
The tool ensures that the OVA produced includes any parameters as part of
the product section of the OVF file. The deployment products pass the
parameters and their values in an OVF environment document. If some of
your activation scripts access parameters that are not defined as part of the
configuration step they belong to, they can do so by reading from the
/opt/IBM/AE/AP/ovf-env.xml file.
Note: This file might be in a slightly different directory such as
/opt/ibm/ae/AP/ovf-env.xml
Because the tool automatically integrates your activation scripts into the
activation engine, the activations scripts do not need to understand the
specifics of the activation engine or OVF standard.
7. On the Firewall tab, specify the port numbers that must be open. Specify
either fixed single ports or port ranges, each with the TCP/UDP protocol.
Note: This step does not apply for Windows images.
8. When you create a software bundle, the software bundle author can provide a
reset script. The purpose of the reset script is to clean up any state that the
corresponding software bundle installation might have added to the virtual
image. On the Reset tab, define reset tasks:
a. Upload the reset script and related files in the Files to Copy section.
Although you can specify the location of the uploaded files in the Files to
Copy destination folder, they are always put in the directory of the
activation framework. The files that you include are displayed as a link
and users can click and download them after you created the software
bundle.
b. From the Run Command menu, select an option for the name of the script
that you want Image Construction and Composition Tool to use to reset
the software bundle.
c. Use the Run As field to specify the root user. You must run the script as
the root user.
d. The arguments section is ignored for the reset scripts. Parameters from the
first Configuration Operation defined on the Configuration tab are
passed to the reset command.
9. To save your software bundle, click . Validation is completed to ensure
that your software bundle is consistent. Review any errors, warnings, or
information messages and take corrective action, if necessary.
416 IBM SmartCloud Orchestrator 2.3: User's Guide
10. If you want to publish the software bundle, click . If you publish the
software bundle, you can no longer edit the software bundle or change it, but
you can still extend it.
Results
You can view the new software bundle in the asset catalog of your Exploiter Name
account, by completing the following steps:
1. Log in to your Exploiter Name account.
2. Click Control Panel.
3. Click View asset catalog.
4. Click the Developer Cloud filter.
5. Search for the software bundle that you created. You can also check for the
most recently modified software bundle.
Related concepts:
Universal identifiers on page 397
When you create virtual images, bundles, and other assets, you enter a unique
universal identifier (ID) for the asset.
Searching for bundles:
You can search for existing bundles.
When you enter your search criteria, only the following fields are searched in the
bundle:
v Name
v Description
v Product name and version
v Universal ID
v Version
Extending software bundles:
You can extend a software bundle to create a new software bundle.
About this task
When you extend a software bundle, all the data that you provided in the
requirements, installation, configuration, and reset sections of the source software
bundle is copied to the new software bundle in a draft state. You can then make
revisions and changes.
Tip: You can use wildcard searches to search for a software bundle.
Procedure
1. Select the software bundle and click .
2. Accept the default values or specify a name, unique version number, universal
ID, and optionally, a description for your new software bundle. For information
about the relationship between the universal ID and version, see Universal
identifiers on page 397.
Chapter 5. Managing virtual images 417
Related concepts:
Universal identifiers on page 397
When you create virtual images, bundles, and other assets, you enter a unique
universal identifier (ID) for the asset.
Uploading large files when creating software bundles:
When you create software bundles that use large files for product installation, such
as large RPM files or large executable files, do not try to upload these files into the
software bundle.
Instead, access the large files at installation time using the software bundle
installation scripts. You must write the software bundle installation scripts so that
they are provided with the location of the binary files at run time, and can be
copied to the new deployed VM on which the software bundle is to be installed.
You can do this in either of the following ways:
v Hardcode the location of the external large files in the installation script.
v In the installation script, use parameters for the location of the external large
files.
This option allows other users of the software bundle to put the large files in
locations that are suitable for their network and environment. In this case, the
software bundle script must specify parameters such as LOCATION, the values
for which are provided when a user is synchronizing a new virtual image with
the software bundle in planned state. The LOCATION value is then used by the
software bundle installation script at run time to find the external large files.
Sharing software bundles:
You can share a software bundle with other systems and users.
About this task
Sharing a software bundle involves either importing a software bundle from
another system or exporting a software bundle to another system. You can also
import a software bundle from a local system or export a software bundle to a
local system. By sharing software bundles you can access and reuse software
bundles that already exist and that contain encapsulated expertise of software
experts who created the software bundles.
To import the software bundle, you must know the name of the remote system and
have access to that system.
The procedure for exporting a software bundle is similar. If you want to export a
software bundle to another system, select the software bundle and click .
Then enter the required values for the export, which are similar to the values for
importing a software bundle. If you are exporting a software bundle to another
system, you can authenticate using a private key file and passphrase or using a
password.
Procedure
1. On the Welcome page, click Build and manage software bundles.
2. To begin importing a software bundle, click .
418 IBM SmartCloud Orchestrator 2.3: User's Guide
3. Enter the following information:
File location
The complete path of the file that you want to import from the remote
system.
User name
The name of the user to connect to the remote system. The user name
is optional and is needed only if the remote system requires it.
Password
The password of the remote system. The password is optional and is
needed only if the remote system requires it.
Storage Location
The location where the software bundle is stored.
4. Click OK.
5. In the Importing <filename> screen, enter the details for the software bundle
that you are importing. If the universal ID or version of the software bundle
that you are importing is not unique on the system on which you are importing
the software bundle, you must enter a unique ID or version. For information
about the fields that display on the screen, see Creating software bundles on
page 412.
Results
The software bundle is imported into the system. You can use it to create virtual
images or you can modify it to suit your requirements.
Using the command-line interface
To perform administrative functions for Image Construction and Composition Tool,
you can download and run the command-line interface on a local machine.
The command-line interface communicates with Image Construction and
Composition Tool so you can manage the system in a scripted, non-graphical
environment. Minimal functions are available without a network connection to the
system.
Note: If you are migrating to Image Construction and Composition Tool from a
previous version, you must download the command-line interface code from the
Welcome page of Image Construction and Composition Tool.
Ensure that you have Java Runtime Environment (JRE) V6, installed on the
machine on which the command-line interface is to run. JRE exists on the virtual
machine that is running You can download this JRE for Linux from the following
web address: http://www.ibm.com/developerworks/java/jdk/linux/
download.html. Because the command-line interface is a scripting language based
on Python 2.5.1, using the command-line interface requires some familiarity with
version 2.5.1 of the Python language. For information about using Python, see
http://www.python.org/doc/2.5.1/index.html.
If you are running the command-line interface on the same VM that Image
Construction and Composition Tool is already using, the JRE exists in
/opt/IBM/icct/jre.
Chapter 5. Managing virtual images 419
Command-line interface high-level procedure
This section provides the high-level steps for using the command-line interface
with links to more detailed information about each section.
Before you begin
In the command-line interface examples, >>> denotes the Python command
prompt, meaning the three greater than symbols together in these examples, >>>,
precede code that you enter.
Procedure
1. Download the command-line interface using the instructions provided in
Downloading and configuring the command-line interface on page 422.
2. Start the command-line interface using the options provided in Invoking the
command-line interface on page 423.
3. You can get help for command syntax, available commands, and using
interactive mode. For more information, see Getting help on the command-line
interface on page 465.
4. For a listing of the resource objects and links to information about using the
command-line interface with them, see Command-line interface resource object
reference on page 428.
Results
After you download and initialize the command-line interface, you are ready to
use it to work with the Image Construction and Composition Tool resources.
Related concepts:
Bundles reference on page 428
You can manage bundles using the command-line interface. Bundles provide the
definition of software and the scripts and parameters needed for installation,
configuration, and deployment of software on a virtual machine.
Cloud providers reference
You can manage cloud providers by using the command-line interface. Cloud
providers provide the definition of hypervisors capable of building and capturing
images.
Images reference
You can manage images by using the command-line interface. Images provide the
definition of virtual machine images that can be used to import, extend, capture,
and export images.
Problem determination reference for the command-line interface on page 463
You can work with problem determination using the command-line interface.
Users reference on page 461
You can administer the user of Image Construction and Composition Tool using
the command-line interface.
Command-line interface resource object reference on page 428
Anything that can be managed in the Image Construction and Composition Tool is
a resource object on the command-line interface.
Related reference:
Invoking in batch mode on page 426
To invoke the command-line interface in batch mode, use these optional
parameters in addition to those parameters used to start the command-line
interface in interactive mode.
420 IBM SmartCloud Orchestrator 2.3: User's Guide
Invoking in interactive mode on page 425
To invoke the command-line interface in interactive mode, use these parameters.
Invoking the samples
You can invoke the samples by invoking as in batch mode.
Related information:
Python documentation
Linux download information
Command-line interface overview
Image Construction and Composition Tool command-line interface provides a
scripting environment based on Jython. Jython is the Java-based implementation of
Python. In addition to issuing commands specific to Image Construction and
Composition Tool, you can also issue Python commands at the command prompt.
To manage Image Construction and Composition Tool with the command-line
interface, you can download the command-line interface to any machine and then
point to where tool is running. You can use the command-line interface on
Windows and Linux operating systems.
Using the command-line interface, you can manage Image Construction and
Composition Tool remotely. The command-line interface communicates with Image
Construction and Composition Tool over a hypertext transfer protocol secure
(HTTPS) session. The command-line interface does not cache updates and has only
minimal caching for reads. If the machine on which the command-line interface is
running loses connectivity to port 443 of the tool, you can perform only
rudimentary operations.
The Jython interpreter included with the command-line interface implements some
of the Python 2.5.1 language. The command-line interface uses the Jython
interpreter to help you manage Image Construction and Composition Tool. In
addition to the standard Jython libraries, the command-line interface provides
functions and classes.
The 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 423.
Note: Each of these methods of passing commands to the command-line interface
supports the same Jython scripting language.
For more information about how to invoke the command-line interface, specify the
--help parameter to the icct or icct.bat command. For more information about
getting help on the command line, see Getting help on the command-line
interface on page 465.
Chapter 5. Managing virtual images 421
Downloading and configuring the command-line interface
To perform administrative functions for Image Construction and Composition Tool,
you can download and run the command-line interface on a local machine.
Before you begin
Ensure that you have Java Runtime Environment (JRE) V6 installed on the machine
on which the command-line interface is to run. To download this JRE for Linux, go
to http://www.ibm.com/developerworks/java/jdk/linux/download.html.
About this task
The command-line interface is currently supported on Windows and Linux
systems.
Procedure
1. To download the command-line interface, click Download command line tool
on the Welcome page of Image Construction and Composition Tool.
2. Save the compressed file to a local drive.
3. Open the compressed file and expand the contents to a local directory. A
subdirectory named icct.cli is created in the local directory.
4. Change directory to the icct.cli directory.
5. Ensure that either the JAVA_HOME or the PATH environment variable is set to
the location of your JRE. To verify, enter java -version at the command line.
6. For Windows Server 2003 and Windows Server 2008 operating systems only: In
the icct.cli directory, find the directory lib\<version>, and create a registry
file in it with the following line:
python.os=nt
This change allows Jython to bypass the normal operating system detection
logic and treat the system as a Windows computer.
By default, the only thing in the lib directory is a <version> subdirectory that
matches the firmware level of the tool from which the command-line interface
was downloaded. If you use this command-line interface installation to
communicate with tools at different firmware levels, there is one subdirectory
under the /lib directory for each of these firmware levels. You must copy the
registry file into each of these subdirectories. For example,
\lib\1.2.0.0-20120131-0830-11\registry
Results
Verify that the command line is installed correctly by running the icct command.
For example:
v On Windows:
bin\icct -h myicct.mycompany.com -P 443 -u username -p password -c icct.version
v On Linux:
bin/icct -h myicct.mycompany.com -P 443 -u username -p password -c icct.version
If the environment is set up correctly, a message is displayed with information
about the command-line interface.
422 IBM SmartCloud Orchestrator 2.3: User's Guide
What to do next
You can now invoke the command-line interface. For more information, see
Invoking the command-line interface.
Related concepts:
Bundles reference on page 428
You can manage bundles using the command-line interface. Bundles provide the
definition of software and the scripts and parameters needed for installation,
configuration, and deployment of software on a virtual machine.
Cloud providers reference
You can manage cloud providers by using the command-line interface. Cloud
providers provide the definition of hypervisors capable of building and capturing
images.
Images reference
You can manage images by using the command-line interface. Images provide the
definition of virtual machine images that can be used to import, extend, capture,
and export images.
Problem determination reference for the command-line interface on page 463
You can work with problem determination using the command-line interface.
Users reference on page 461
You can administer the user of Image Construction and Composition Tool using
the command-line interface.
Command-line interface resource object reference on page 428
Anything that can be managed in the Image Construction and Composition Tool is
a resource object on the command-line interface.
Related reference:
Invoking in batch mode on page 426
To invoke the command-line interface in batch mode, use these optional
parameters in addition to those parameters used to start the command-line
interface in interactive mode.
Invoking in interactive mode on page 425
To invoke the command-line interface in interactive mode, use these parameters.
Invoking the samples
You can invoke the samples by invoking as in batch mode.
Related information:
Python documentation
Linux download information
Invoking the command-line interface
To perform administrative functions for Image Construction and Composition Tool,
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
Download and extract the command-line interface. If you recently upgraded your
system, download the new version of the command-line interface.
About this task
The 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
Chapter 5. Managing virtual images 423
interface session uses the timeout value specified in Image Construction and
Composition Tool. When a user session expires, you are prompted to reenter your
user ID and password. If the ICCT_REAUTHENTICATE environment variable is
set, a new session is automatically started for the user when an existing session
expires.
A set of sample scripts that demonstrate some of the command-line interface
function are located in the cli_install_dir\sample directory.
Related concepts:
Bundles reference on page 428
You can manage bundles using the command-line interface. Bundles provide the
definition of software and the scripts and parameters needed for installation,
configuration, and deployment of software on a virtual machine.
Cloud providers reference
You can manage cloud providers by using the command-line interface. Cloud
providers provide the definition of hypervisors capable of building and capturing
images.
Images reference
You can manage images by using the command-line interface. Images provide the
definition of virtual machine images that can be used to import, extend, capture,
and export images.
Problem determination reference for the command-line interface on page 463
You can work with problem determination using the command-line interface.
Users reference on page 461
You can administer the user of Image Construction and Composition Tool using
the command-line interface.
Command-line interface resource object reference on page 428
Anything that can be managed in the Image Construction and Composition Tool is
a resource object on the command-line interface.
Related reference:
Invoking in batch mode on page 426
To invoke the command-line interface in batch mode, use these optional
parameters in addition to those parameters used to start the command-line
interface in interactive mode.
Invoking in interactive mode on page 425
To invoke the command-line interface in interactive mode, use these parameters.
Invoking the samples
You can invoke the samples by invoking as in batch mode.
Related information:
Python documentation
Linux download information
424 IBM SmartCloud Orchestrator 2.3: User's Guide
Invoking in interactive mode:
To invoke the command-line interface in interactive mode, use these parameters.
-u <userid> or --userid
Optional. Specifies the user ID to authenticate to the Image Construction
and Composition Tool. Use the same user ID and password that you use to
log on to the tool. If the userid parameter is not specified, the value of the
ICCT_USERID environment variable determines the user ID. When the
user ID is not included on the command-line interface and the
environment variable is not set, you are prompted to enter a user ID.
-p <password> or --password
Optional. The parameter -p is case sensitive. Specifies the password used
to authenticate to the Image Construction and Composition Tool. Use the
same user ID and password that you use to log on to the tool. If the
password parameter is not specified, the value of the ICCT_PASSWORD
environment variable determines the password. When the password is not
included on the command-line interface and the environment variable is
not set, you are prompted to enter a password.
-P <port> or --port
Optional. The parameter -P is case sensitive. Specifies the TCP/IP port
used to communicate with the Image Construction and Composition Tool.
Use the same port that you use to log on to the tool. If the port parameter
is not specified, the value of the ICCT_PORT environment variable
determines the port. When the port is not included on the command-line
interface and the environment variable is not set, the default value of 443
is used.
-h <host> or --host
Required. Specifies the host name or IP address of the Image Construction
and Composition Tool. If you specify this option, do not use the URL to
access the web interface. If this parameter is not specified, the value of the
ICCT_HOST environment variable determines the host name.
-d or --debug
Optional. Enable the logging of communication between the Image
Construction and Composition Tool server and the command-line interface.
File cli.log in the logs directory is not used.
Note: Because this log contains unencrypted HTTP data, delete the cli.log
file when you are finished with it.
$ icct -h myicct.mycompany.com -P 443 -u username -p password
Related concepts:
Bundles reference on page 428
You can manage bundles using the command-line interface. Bundles provide the
definition of software and the scripts and parameters needed for installation,
configuration, and deployment of software on a virtual machine.
Cloud providers reference
You can manage cloud providers by using the command-line interface. Cloud
providers provide the definition of hypervisors capable of building and capturing
images.
Images reference
You can manage images by using the command-line interface. Images provide the
definition of virtual machine images that can be used to import, extend, capture,
Chapter 5. Managing virtual images 425
and export images.
Problem determination reference for the command-line interface on page 463
You can work with problem determination using the command-line interface.
Users reference on page 461
You can administer the user of Image Construction and Composition Tool using
the command-line interface.
Command-line interface resource object reference on page 428
Anything that can be managed in the Image Construction and Composition Tool is
a resource object on the command-line interface.
Related tasks:
Command-line interface high-level procedure on page 420
This section provides the high-level steps for using the command-line interface
with links to more detailed information about each section.
Invoking the command-line interface on page 423
To perform administrative functions for Image Construction and Composition Tool,
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.
Getting help on the command-line interface on page 465
As you perform administrative functions using the command-line interface, you
can get help for all resources.
Downloading and configuring the command-line interface on page 422
To perform administrative functions for Image Construction and Composition Tool,
you can download and run the command-line interface on a local machine.
Related information:
Python documentation
Linux download information
Invoking in batch mode:
To invoke the command-line interface in batch mode, use these optional
parameters in addition to those parameters used to start the command-line
interface in interactive mode.
-c <command>
Optional. Passes 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 not a Jython statement, it is
run but no output is generated unless the statement itself causes output to
be generated. Do not specify this parameter if you want to run the
command-line interface in interactive mode.
Example: $ icct -h myicct.mycompany.com -P 443 -u joeadmin -p
password -c "icct.version"
-f <script_file><arg>*
Optional. Causes 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.
Example: $ icct -h myicct.mycompany.com -P 443 -u joeadmin -p
password -f sampleScript.py arg1 arg2 arg3
426 IBM SmartCloud Orchestrator 2.3: User's Guide
-d Optional. This parameter is used for debugging. The log files are stored in
icct.cli\logs\cli.log".
Example: $ icct -h myicct.mycompany.com -P 443 -u joeadmin -p
password -d
On Linux, you can make the shell automatically use the Image Construction and
Composition Tool command to execute your Jython scripts. If the Image
Construction and Composition Tool 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:
#!/usr/bin/env icct
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.
Related concepts:
Bundles reference on page 428
You can manage bundles using the command-line interface. Bundles provide the
definition of software and the scripts and parameters needed for installation,
configuration, and deployment of software on a virtual machine.
Cloud providers reference
You can manage cloud providers by using the command-line interface. Cloud
providers provide the definition of hypervisors capable of building and capturing
images.
Images reference
You can manage images by using the command-line interface. Images provide the
definition of virtual machine images that can be used to import, extend, capture,
and export images.
Problem determination reference for the command-line interface on page 463
You can work with problem determination using the command-line interface.
Users reference on page 461
You can administer the user of Image Construction and Composition Tool using
the command-line interface.
Command-line interface resource object reference on page 428
Anything that can be managed in the Image Construction and Composition Tool is
a resource object on the command-line interface.
Related tasks:
Command-line interface high-level procedure on page 420
This section provides the high-level steps for using the command-line interface
with links to more detailed information about each section.
Invoking the command-line interface on page 423
To perform administrative functions for Image Construction and Composition Tool,
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.
Getting help on the command-line interface on page 465
As you perform administrative functions using the command-line interface, you
can get help for all resources.
Downloading and configuring the command-line interface on page 422
To perform administrative functions for Image Construction and Composition Tool,
you can download and run the command-line interface on a local machine.
Related information:
Chapter 5. Managing virtual images 427
Python documentation
Linux download information
Command-line interface resource object reference
Anything that can be managed in the Image Construction and Composition Tool is
a resource object on the command-line interface.
The Image Construction and Composition Tool command-line interface manages
different types of resources, for example bundles, cloud providers and images
instances. The following objects are available:
Related tasks:
Command-line interface high-level procedure on page 420
This section provides the high-level steps for using the command-line interface
with links to more detailed information about each section.
Invoking the command-line interface on page 423
To perform administrative functions for Image Construction and Composition Tool,
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.
Getting help on the command-line interface on page 465
As you perform administrative functions using the command-line interface, you
can get help for all resources.
Downloading and configuring the command-line interface on page 422
To perform administrative functions for Image Construction and Composition Tool,
you can download and run the command-line interface on a local machine.
Related reference:
Invoking in batch mode on page 426
To invoke the command-line interface in batch mode, use these optional
parameters in addition to those parameters used to start the command-line
interface in interactive mode.
Invoking in interactive mode on page 425
To invoke the command-line interface in interactive mode, use these parameters.
Invoking the samples
You can invoke the samples by invoking as in batch mode.
Related information:
Python documentation
Linux download information
Bundles reference:
You can manage bundles using the command-line interface. Bundles provide the
definition of software and the scripts and parameters needed for installation,
configuration, and deployment of software on a virtual machine.
Bundles object
A bundles object represents the collection of bundles defined in Image
Construction and Composition Tool. Objects of this type are used to create, delete,
iterate over, list, and search bundles.
428 IBM SmartCloud Orchestrator 2.3: User's Guide
Bundles methods
The bundles object has the methods described for a typical resource collection. The
following methods are unique to bundles as their parameters and return values
differ from what is expected:
getBundles()
This method returns a Python list of bundle objects representing all
bundles. You can optionally filter the list using regular expressions. The
method accepts the following parameters:
nameRegEx
String for a regular expression to match against the bundle name.
Default is none.
universalIdRegEx
String for a regular expression to match against the bundle
universalId (symbolicName). Default is none.
versionRegEx
String for a regular expression to match against the bundle version.
Default is none.
descriptionRegEx
String for a regular expression to match against the bundle
description. Default is none.
import()
Imports a bundle to the Image Construction and Composition Tool. The
attributes to import the new bundle can be specified in any of the
following ways:
v As a string specifying a non-authenticated URL from which the bundle
can be downloaded:
>>> icct.bundles.import(http://localhost/myBundle.ras)
v As a string specifying a file local to the Image Construction and
Composition Tool machine:
>>> icct.bundles.import(/tmp/myBundle.ras)
v As a string specifying an authenticated URL, username, and password
>>> icct.bundles.import(http://localhost/myBundle.ras,
username, password)
This method returns a bundle object for the newly imported bundle. This
method queues the operation in the Image Construction and Composition
Tool and returns immediately. The returned bundle object can be used to
track the status of the import process. The waitFor() method can also be
used to pause until the import completes.
Bundles examples
To get a list of all the bundles, without filtering out any bundle, use the following
method:
>>> icct.bundles.getBundles()
To get a list of all the bundles, with a specific bundle listed first, use the following
method. Only an exact match for the entire bundle name results in the bundle
being listed first.
>>>bundles = icct.bundles[bundle abc]
Chapter 5. Managing virtual images 429
To get a list of all the bundles that have Linux in the name, use the following
method:
>>> icct.bundles.getBundles(Linux)
To get a list of all the bundles that have suse in the universalId and 1.0.0 in the
version, use the following method:
>>> icct.bundles.getBundles(None, suse, 1.0.0)
To import a bundle and wait for the import to complete, use the following code:
>>> importingBundle = icct.bundles.import(http://localhost/myBundle.ras)
>>> importingBundle.waitFor()
>>> if importingBundle.currentState == import_failed:
>>> print Bundle import failed!
Bundle object
A bundle object represents a particular bundle defined in the Image Construction
and Composition Tool. Use the object to query and manipulate the bundle.
Attributes of the bundle resource are represented as Jython attributes on the
bundle object. Manipulate these Jython attributes using standard Jython
mechanisms to change to the corresponding data in the Image Construction and
Composition Tool.
Bundle attributes
The bundle object has the following attributes which are read-only unless
otherwise noted:
currentState
The state of a bundle: importing, import_failed, draft, published.
currentState_text
Specifies the textual representation of currentState. This field is a string
representation of currentState in the preferred language of the requester
and is automatically generated by the tool.
description
The description of the bundle. Read/write.
id The universal identifier of the bundle.
name The name of the bundle. Read/write.
uri The URI used to access the bundle.
version
The version of the bundle.
Bundle methods
The bundle object has the methods described for a typical resource collection. The
following methods are unique to bundle objects as their parameters and return
values differ from what is expected:
clone()
This method returns a copy of the bundle object. The method accepts the
following parameters:
dict A Jython dict object where the valid keys are:
430 IBM SmartCloud Orchestrator 2.3: User's Guide
name The name of the cloned bundle. If this value is not
supplied, it defaults to the current bundle name + -
Clone.
description
The description of the cloned bundle. If this value is not
supplied, it defaults to the current bundle description.
symbolicName
The universal ID of the cloned bundle. If this value is not
supplied, it defaults to the current bundle universal ID.
version
The version of the cloned bundle. If this value is not
supplied, it defaults to the current Bundle version + 1.
For example:
>>> bundle = icct.bundles[0]
>>> dict = { name : My cloned bundle,
version : 1.2.3.4-20120131 }
>>> bundleClone = bundle.clone(dict)
delete()
This method deletes the bundle.
export()
This method starts the asynchronous process of exporting a bundle to a
remote location. This method accepts the following parameters:
export_host
The IP address of the computer where the image is to be copied.
export_path
The directory to copy the bundle to. By default, the universal id
and version are used to create the filename. To specify a different
filename, include the filename with a .ras extension.
export_userid
The user ID for UNIX Secure Copy.
export_password
The password for UNIX Secure Copy.
privateKeyFile
Optional: The private key file name. If specified, the
export_password parameter is used as the passphrase.
This file is copied to the given location, as shown in the following
example:
>>> bundle = icct.bundles[0]
>>> bundleExportId = bundle.export(localhost, /tmp,
userid, password)
>>> bundle.waitForExport(bundleExportId)
This method returns an identifier for the exporting bundle task and queues
the operation on the Image Construction and Composition Tool. It is
returned immediately. The returned identifier can be used to track the
status of the export process. The waitForExport() method can also be used
to pause until the export completes. The exportStatus() method can be
used to query the last known export status but you must call the refresh()
method prior to calling the exportStatus() method to be sure that you get
the latest status.
Chapter 5. Managing virtual images 431
exportStatus()
This method checks the status of the asynchronous process that is
exporting the bundle:
>>> bundle.export(localhost, /tmp, userid, password)
>>> bundle.refresh()
>>> bundle.exportStatus()
This method returns a string specifying the current export status of the
Bundle object. To ensure the latest status, call the refresh() method prior to
calling the exportStatus() method. Valid export status values are
Exporting, Complete, Failed.
getBundleRequirements()
This method returns a Python list of BundleBundleRequirement objects
representing all the bundle requirements in this bundle. The function
accepts no arguments. Get a list of bundle requirements in the bundle:
>>>bundle = icct.bundles[0]
>>>bundlereqs=bundle.getBundleRequirements()
getConfigurations()
This method returns a Python list of BundleConfiguration objects
representing all of the configuration and deployment definitions in this
bundle. The function accepts no arguments. Get a list of configuration
operations in the bundle:
>>>bundle = icct.bundles[0]
>>>configs=bundle.getConfigurations()
getDeployParameters()
This method returns a list of Python dict objects representing parameters
used for deployment of the bundle. Each dict object contains information
about a bundle deployment parameter.
>>> icct.bundles[0].getDeployParameters()
The keys in the dict are:
defaultVal
Default value that is used if a value is not provided.
direction
Value is always "input"
isPassword
Value is true, if the deployment parameter is a password.
label Text label for the user interface display
name Name identifier
type Value is always "string".
value Current parameter value.
getFirewallRules()
This method returns a Python list of BundleFirewallRule objects
representing all the firewall port opening definitions in this bundle. The
function accepts no arguments. Get a list of firewall ports in the bundle:
>>>bundle = icct.bundles[0]
>>>firewallports=bundle.getFirewallRules()
getInstallation()
This method returns a BundleInstallation object representing all the bundle
432 IBM SmartCloud Orchestrator 2.3: User's Guide
installation operation in this bundle. The function accepts no arguments.
Get the bundle installation in the bundle:
>>>bundle = icct.bundles[0]
>>>install=bundle.getInstallation()
getInstallParameters()
This method returns a list of Python dict objects representing parameters
used for installation of the bundle. Each dict object contains information
about a bundle installation parameter.
>>> icct.bundles[0].getInstallParameters()
The keys in the dict are:
defaultVal
Default value that is used if a value is not provided
direction
Value is always input.
isPassword
Value is true, if the deployment parameter is a password.
label Text label for the user interface display
name Name identifier
type Value is always "string".
value Current parameter value.
getOSRequirements()
This method returns a Python list of BundleOSRequirement objects
representing all the operating system requirements in this bundle. The
function accepts no arguments. Get a list of operating system requirements
in the bundle:
>>>bundle = icct.bundles[0]
>>>osreqs=bundle.getOSRequirements()
getProducts()
This method returns a Python list of BundleProduct objects representing all
the products defined to be in this bundle. The function accepts no
arguments. To get a list of products in the bundle:
>>>bundle = icct.bundles[0]
>>>products=bundle.getProducts()
getReset()
This method returns a BundleReset object representing all the bundle reset
operation in this bundle. The function accepts no arguments. Get the
bundle reset in the bundle:
>>>bundle = icct.bundles[0]
>>>reset=bundle.getReset()
getSoftwareRequirements()
This method returns a Python list of BundleSoftwareRequirement objects
representing all the software requirements in this bundle. The function
accepts no arguments. Get a list of software requirements in the bundle:
>>>bundle = icct.bundles[0]
>>>swreqs=bundle.getSoftwareRequirements()
Chapter 5. Managing virtual images 433
publish()
This method changes the bundle state from draft to published. The method
uses a Python object representing the bundle. The original object is also
refreshed to reflect the updated state.
setConfigurations
This method stores a Python list of BundleConfiguration objects
representing all the configuration and deployment definitions in this
bundle. This method must be called to save BundleConfiguration changes.
The function accepts the following argument:
configuration
This method stores a Python list of BundleConfiguration objects
representing all the configuration and deployment definitions in
this bundle. This method must be called to save
BundleConfiguration changes. The function accepts the following
argument:
configuration
A Python list of BundleConfiguration objects
Save a modified list of configuration definitions in the bundle:
>>>bundle.setConfigurations(configs)
setBundleRequirements()
This method stores a Python list of BundleBundleRequirement objects
representing all the bundle requirements defined in this bundle. This
method must be called to save BundleBundleRequirement changes. The
function accepts the following arguments:
bundleList
A Python list of BundleBundleRequirement objects.
Save a modified list of bundle requirements in the bundle:
>>>bundle.setBundleRequirements(bundlereqs)
setInstallation()
This method stores a BundleInstallation object representing the bundle
install operation defined in this bundle. This method must be called to
save BundleInstallation changes. The function accepts the following
argument:
installation
A BundleInstallation object
Save a modified bundle installation in the bundle:
>>>bundle.setInstallation(install)
setOSRequirements()
This method stores a Python list of BundleOSRequirement objects
representing all the operating system requirements defined in this bundle.
This method must be called to save BundleOSRequirement changes. The
function accepts the following argument:
osList APython list of BundleOSRequirement objects.
Save a modified list of operating system requirements in the bundle:
>>>bundle.setOSRequirements(osreqs)
434 IBM SmartCloud Orchestrator 2.3: User's Guide
setFirewallRules()
This method stores a Python list of BundleFirewallRule objects
representing all the firewall port opening definitions in this bundle. This
method must be called to save BundleFirwallRule changes. The function
accepts the following argument:
portList
APython list of BundleFirewallRule objects.
Save a modified list of firewall rules in the bundle:
>>>bundle.setFirewallRules(firewallports)
setProducts()
This method stores a Python list of BundleProduct objects representing all
the products defined to be in this bundle. This method must be called to
save BundleProduct changes. The function accepts the following argument:
products
A Python list of BundleProduct objects. Save a modified list of
products in the bundle:
>>>bundle.setProducts(products)
setReset()
This method stores a BundleReset object representing the bundle reset
operation defined in this bundle. This method must be called to save
BundleReset changes. The function accepts the following argument:
reset A BundleReset object
Save a modified bundle reset in the bundle:
>>>bundle.setReset(reset)
setSoftwareRequirements()
This method stores a Python list of BundleSoftwareRequirement objects
representing all the software requirements defined in this bundle. This
method must be called to save BundleSoftwareRequirement changes. The
function accepts the following argument:
swList APython list of BundleSoftwareRequirement objects.
Save a modified list of software requirements in the bundle:
>>>bundle.setSoftwareRequirements(swreqs)
waitForExport()
This method can be used to wait a specified period of time for the export
of the bundle to finish. The method can assist you in writing scripts that
must wait for theImage Construction and Composition Tool to complete a
particular action. The waitForExport() method periodically checks for the
export to finish or a timeout expires. The method accepts the following
parameters:
exportId
The ID returned by a call to the bundle.export() method.
maxWait
The maximum wait time in 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.
Chapter 5. Managing virtual images 435
interval
The interval at which bundle export status is evaluated in seconds.
Floating point values can be used to express fractions of a second.
The default value is 60 seconds.
>>> bundle = icct.bundles[0]
>>> bundleExportId = bundle.export(localhost, /tmp,
userid, password)
>>> bundle.waitForExport(bundleExportId)
Related tasks:
Command-line interface high-level procedure on page 420
This section provides the high-level steps for using the command-line interface
with links to more detailed information about each section.
Invoking the command-line interface on page 423
To perform administrative functions for Image Construction and Composition Tool,
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.
Getting help on the command-line interface on page 465
As you perform administrative functions using the command-line interface, you
can get help for all resources.
Downloading and configuring the command-line interface on page 422
To perform administrative functions for Image Construction and Composition Tool,
you can download and run the command-line interface on a local machine.
Related reference:
Invoking in batch mode on page 426
To invoke the command-line interface in batch mode, use these optional
parameters in addition to those parameters used to start the command-line
interface in interactive mode.
Invoking in interactive mode on page 425
To invoke the command-line interface in interactive mode, use these parameters.
Invoking the samples
You can invoke the samples by invoking as in batch mode.
Related information:
Python documentation
Linux download information
BundleBundleRequirements reference:
You can manage requirements a Bundle places on other Bundle objects using the
command-line interface. BundleBundleRequirement provides the definition of
required bundles needed for installation of software on a virtual machine
BundleBundleRequirements object
A BundleBundleRequirements object is used to create a BundleBundleRequirement
object.
BundleBundleRequirements methods
The BundleBundleRequirements object has no methods that are unique to
BundleBundleRequirements.
436 IBM SmartCloud Orchestrator 2.3: User's Guide
BundleBundleRequirements examples
Create a new BundleBundleRequirement object using the interactive wizard, add to
existing bundle requirements, and save:
>>>wizard = icct.wizard()
>>>bundleReq = icct.bundlebundlerequirements.create(wizard)
>>>wizard.toDict()
>>>bundle.getBundleRequirements().append(bundleReq)
>>>bundle.setBundleRequirements(bundleReq)
Create a new BundleBundleRequirement using a Python dict object:
>>>newbundlereqDict = {version: u1.0.1, symbolicName: uicon.default.helloworld,
name: uhelloWorld}
>>>bundleReq = icct.bundlebundlerequirements.create(newbundlereqDict)
BundleBundleRequirement object
A BundleBundleRequirement object represents a particular bundle requirement of a
bundle defined in the Image Construction and Composition Tool. Use the object to
query and manipulate the bundle requirement. Attributes of the
BundleBundleRequirement resource are represented as Jython attributes of the
object. Manipulate these Jython attributes using standard Jython mechanisms to
change the corresponding data. Any changes to this object require the use of the
Bundle.setBundleRequirements() method to save the change in the Image
Construction and Composition Tool.
BundleBundleRequirement attributes
The BundleBundleRequirement object has the following attributes, which are
read-only unless otherwise noted:
name The name of the bundle. Writeable.
uri The URI used to access the bundle.
symbolicName
The universal ID of the bundle. Writeable.
version
The version of the bundle. Writeable.
BundleBundleRequirement methods
None.
BundleCommands reference:
You can manage commands that a Bundle uses during installation, capture, and
deployment using the command-line interface. BundleCommand provides the
definition of operating system scripts or commands that must be run on a virtual
machine.
BundleCommands object
A BundleCommands object is used to create a BundleCommand object.
Chapter 5. Managing virtual images 437
BundleCommands methods
The BundleCommands object has no methods that are unique to
BundleCommands.
BundleCommands examples
Create a new BundleCommand object using the interactive wizard, replace the
installation command in the bundle, and save:
>>>wizard = icct.wizard()
>>>bundleCmd = icct.bundlecommands.create(wizard)
>>>wizard.toDict()
>>>install = bundle.getInstallation()
>>>install.command = bundleCmd
>>>bundle.setInstallation(install)
Create a new BundleCommand using a Python dict object:
>>>newCmdDict = {runas: uroot, parameterStyle: ushortSpaceStyle}
>>>newCmd = icct.bundlecommands.create(newCmdDict))
BundleCommand object
A BundleCommand object represents a particular bundle command of a bundle
defined in the Image Construction and Composition Tool. Use the object to query
and manipulate the bundle command. Attributes of the BundleCommand resource
are represented as Jython attributes of the object. Manipulate these Jython
attributes using standard Jython mechanisms to change the corresponding data.
Any changes to this object require the use of the corresponding
Bundle.setInstallation(), Bundle.setConfigurations() or Bundle.setResets() method to
save the change in theImage Construction and Composition Tool.
BundleCommand attributes
The BundleCommand object has the following attributes, which are read-only
unless otherwise noted:
runas The name of the bundle. Writeable.
runcmd
The command file to run. Writeable.
parameterStyle
The URI used to access the bundle. Writeable. Valid values are:
v 'environmentStyle'
v 'longSpaceStyle'
v 'shortSpaceStyle'
v 'windowsStyle'
arguments
The Python list of BundleCommandArgument objects. Writeable.
BundleCommand methods
None.
438 IBM SmartCloud Orchestrator 2.3: User's Guide
BundleCommandArguments reference:
You can manage command line arguments, also know as parameters, that a
BundleCommand uses during installation, capture, and deployment using the
command-line interface. BundleCommandArgument provides the definition of
command line arguments to pass to the operating system scripts or commands that
need to be run on a virtual machine.
BundleCommandArguments object
A BundleCommandArguments object is used to create a
BundleCommandArgument object.
BundleCommandArguments methods
The BundleCommandArguments object has no methods that are unique to
BundleCommandArguments.
BundleCommandArguments examples
Create a new BundleCommandArgument object using the interactive wizard,
replace the installation command in the bundle, and save:
>>>wizard = icct.wizard()
>>>newCmdArg = icct.bundlecommandarguments.create(wizard)
>>>wizard.toDict()
>>>install=bundle.getInstallation()
>>>arglist = install.command.arguments
>>>arglist.append(newCmdArg)
>>>install.command.arguments=arglist
>>>bundle.setInstallation(install)
Create a new BundleCommandArgument using a Python dict object:
>>>newCmdArgDict = {label: uarglabel1, isPassword: False, defaultVal: uargDefaultVal1,
name: uargname1}
>>>newCmdArg = icct.bundlecommandarguments.create(newCmdArgDict)
BundleCommandArgument object
A BundleCommandArgument object represents a particular bundle command
argument of a bundle defined in the Image Construction and Composition Tool.
Use the object to query and manipulate the bundle command argument. Attributes
of the BundleCommandArgument resource are represented as Jython attributes of
the object. Manipulate these Jython attributes using standard Jython mechanisms to
change the corresponding data. Any changes to this object require the use of the
corresponding Bundle.setInstallation(), Bundle.setConfigurations() or
Bundle.setResets() method to save the change in the Image Construction and
Composition Tool.
BundleCommandArgument attributes
The BundleCommandArgument object has the following attributes, which are
read-only unless otherwise noted:
name The name of the argument that is passed to the command. Writeable.
label The label displayed when this argument is requested from the user.
Writeable.
Chapter 5. Managing virtual images 439
isPassword
True if the value must be hidden, otherwise False.
defaultVal
Optional. Default value for this argument. Writeable.
BundleCommandArgument methods
None.
BundleConfigDependencies reference:
You can manage configuration service name dependencies using the command-line
interface. BundleConfigDependency provides the definition of configuration service
name dependencies to the operating system on a virtual machine.
BundleConfigDependencies object
A BundleConfigDependencies object is used to create a BundleConfigDependency
object.
BundleConfigDependencies methods
The BundleConfigDependencies object has no methods that are unique to
BundleConfigDependencies
BundleConfigDependencies examples
Create a new BundleConfigDependency object using the interactive wizard, replace
the installation command in the bundle, and save:
>>>wizard = icct.wizard()
>>>newCfgDep = icct.bundleconfigdependencies.create(wizard)
>>>wizard.toDict()
>>>config=bundle.getConfigurations()
>>>depList = config[0].dependencies
>>>depList.append(newCfgDep)
>>>bundle.setConfigurations(config)
Create a new BundleConfigDependency using a Python dict object:
>>>newCfgDepDict = {servicename: activation.CLITESTService}
>>>newCfgDep = icct.bundleconfigdependencies.create(newCfgDepDict)
BundleConfigDependency object
A BundleConfigDependency object represents a particular bundle configuration
service name dependency of a bundle defined in the Image Construction and
Composition Tool. Use the object to query and manipulate the bundle
configuration dependency. Attributes of the BundleConfigDependency resource are
represented as Jython attributes of the object. Manipulate these Jython attributes
using standard Jython mechanisms to change the corresponding data. Any changes
to this object require the use of the Bundle.setConfigurations() method to save the
change in the Image Construction and Composition Tool.
BundleConfigDependency attributes
The BundleConfigDependency object has the following read-write attribute:
440 IBM SmartCloud Orchestrator 2.3: User's Guide
servicename
The operating system service name.
BundleConfigDependency methods
None.
BundleConfigurations reference:
You can manage configurations using the command-line interface.
BundleConfiguration provides the definition of configuration operations for a
bundle on a virtual machine.
BundleConfigurations object
A BundleConfigurations object is used to create a BundleConfiguration object.
BundleConfigurations methods
The BundleConfigurations object has no methods that are unique to
BundleConfigurations.
BundleConfigurations examples
Create a new BundleConfiguration object using the interactive wizard:
>>>wizard = icct.wizard()
>>>newCfg = icct.bundleconfigurations.create(wizard)
>>>wizard.toDict()
Create a new BundleConfiguration using a Python dict object:
>>>newCfgDict = {operationname: activation.MyConfigTest}
>>>newCfg = icct.bundleConfigurations.create(newCfgDict)
BundleConfiguration object
A BundleConfiguration object represents a particular bundle configuration of a
bundle defined in the Image Construction and Composition Tool. Use the object to
query and manipulate the bundle configuration. Attributes of the
BundleConfiguration resource are represented as Jython attributes of the object.
Manipulate these Jython attributes using standard Jython mechanisms to change
the corresponding data. Any changes to this object require the use of the
Bundle.setConfigurations() method to save the change in theImage Construction
and Composition Tool.
BundleConfiguration attributes
The BundleConfiguration object has the following read-write attribute:
operationname
The operation name of the configuration.
BundleConfiguration methods
None.
Chapter 5. Managing virtual images 441
BundleFiles reference:
You can manage files of the BundleInstallation, BundleConfiguration and
BundleReset objects using the command-line interface. BundleFile provides the
definition of a file for the selected operation for a bundle on a virtual machine.
BundleFiles object
A BundleFiles object is used to create a BundleFile object.
BundleFiles methods
The BundleFiles object has no methods that are unique to BundleFiles.
BundleFiles examples
Create a new BundleFile object using the interactive wizard:
>>>wizard = icct.wizard()
>>>newFile = icct.bundlefiles.create(wizard)
>>>wizard.toDict()
Create a new BundleFile using a Python dict object:
>>>newFileDict = {source: C:\\testFile.sh, executable: True}
>>>newFile = icct.bundlefiles.create(newFileDict)
BundleFile object
A BundleFile object represents a file of a BundleInstallation, BundleConfiguration
or BundleReset object of a bundle defined in the Image Construction and
Composition Tool. Use the object to query and manipulate the file definition.
Attributes of the BundleFile resource are represented as Jython attributes of the
object. Manipulate these Jython attributes using standard Jython mechanisms to
change the corresponding data. Any changes to this object require the use of the
respective Bundle.setInstallation(), Bundle.setConfigurations() or Bundle.setReset()
method to save the change in theImage Construction and Composition Tool.
BundleFile attributes
The BundleFile object has the following attributes, which are read-only unless
otherwise noted:
source The file name. Writeable.
executable
True if the file must be executable, False otherwise.
BundleFile methods
None.
442 IBM SmartCloud Orchestrator 2.3: User's Guide
BundleFirewallRules reference:
You can manage firewall ports to open using the command-line interface.
BundleFirewallRule provides the definition of a port or range of ports to open for
a bundle on a virtual machine.
BundleFirewallRules object
A BundleFirewallRules object is used to create a BundleFirewallRule object.
BundleFirewallRules methods
The BundleFirewallRules object has no methods that are unique to
BundleFirewallRules.
BundleFirewallRules examples
Create a new BundleFirewallRule object using the interactive wizard:
>>>wizard = icct.wizard()
>>>newRule = icct.bundlefirewallrules.create(wizard)
>>>wizard.toDict()
Create a new BundleFirewallRule using a Python dict object:
>>>newRuleDict = {endingport: 7777, startingport: 6666, protocol: uUDP}
>>>newRule = icct.bundlefirewallrules.create(newRuleDict)
BundleFirewallRule object
A BundleFirewallRule object represents a firewall port or range of ports to open for
a bundle defined in the Image Construction and Composition Tool. Use the object
to query and manipulate the firewall port definitions. Attributes of the
BundleFirewallRule resource are represented as Jython attributes of the object.
Manipulate these Jython attributes using standard Jython mechanisms to change
the corresponding data. Any changes to this object require the use of the
Bundle.setFirewallRules() method to save the change in theImage Construction and
Composition Tool.
BundleFirewallRule attributes
The BundleFirewallRule object has the following attributes, which are read-only
unless otherwise noted:
startingport
The starting port number to open. Writeable.
endingport
The ending port number to open. Must be greater than or equal to
startingport. Writeable.
protocol
Optional. The protocol of the ports. Valid values are: TCP, UDP.
BundleFirewallRule methods
None.
Chapter 5. Managing virtual images 443
BundleInstallations reference:
You can manage installation of a bundle using the command-line interface.
BundleInstallation provides the definition how to install a bundle on a virtual
machine.
BundleInstallations object
A BundleInstallations object is used to create a BundleInstallation object.
BundleInstallations methods
The BundleInstallations object has no methods that are unique to
BundleInstallations.
BundleInstallations examples
Create a new BundleInstallation object using the interactive wizard:
>>>wizard = icct.wizard()
>>>newInstall = icct.bundleinstallations.create(wizard)
>>>wizard.toDict()
Create a new BundleInstallation using a Python dict object:
>>>newInstall = icct.bundleinstallations.create({})
BundleInstallation object
A BundleInstallation object represents installation operations for a bundle defined
in the Image Construction and Composition Tool. Use the object to query and
manipulate the installation definitions. Attributes of the BundleInstallation resource
are represented as Jython attributes of the object. Manipulate these Jython
attributes using standard Jython mechanisms to change the corresponding data.
Any changes to this object require the use of the Bundle.setInstallation() method to
save the change in theImage Construction and Composition Tool.
BundleInstallation attributes
The BundleInstallation object has the following attributes, which are read-only
unless otherwise noted:
commands
A BundleCommand object. Writeable.
files APython list of BundleFile objects. Writeable.
BundleInstallation methods
None.
444 IBM SmartCloud Orchestrator 2.3: User's Guide
BundleOSRequirements reference:
You can manage the operating system requirements of a bundle using the
command-line interface. BundleOSRequirement provides the definition of an
operating system requirement for a bundle on a virtual machine.
BundleOSRequirements object
A BundleOSRequirements object is used to create a BundleOSRequirement object.
BundleOSRequirements methods
The BundleOSRequirements object has no methods that are unique to
BundleOSRequirements.
BundleOSRequirements examples
Create a new BundleOSRequirement object using the interactive wizard:
>>>wizard = icct.wizard()
>>>newOSReq = icct.bundleosrequirements.create(wizard)
>>>wizard.toDict()
Create a new BundleOSRequirement using a Python dict object:
>>>osReqDict = {architecture: x86-32, distribution:
Red Hat Enterprise Linux (RHEL), type: Linux, minversion: u1.2.3}
>>>newosReq = icct.bundleosrequirements.create(osReqDict)
BundleOSRequirement object
A BundleOSRequirement object represents OSRequirement operations for a bundle
defined in the Image Construction and Composition Tool. Use the object to query
and manipulate the OSRequirement definitions. Attributes of the
BundleOSRequirement resource are represented as Jython attributes of the object.
Manipulate these Jython attributes using standard Jython mechanisms to change
the corresponding data. Any changes to this object require the use of the
Bundle.setOSRequirement() method to save the change in theImage Construction
and Composition Tool.
BundleOSRequirement attributes
The BundleOSRequirement object has the following attributes, which are read-only
unless otherwise noted:
BundleOSRequirement methods
architecture
Optional. Operating system architecture. Writeable. Valid values are:
v 'x86-32'
v 'x86-64'
v 'IA64'
v 'POWER System'
v 'System z'
distribution
Optional. Operating system distribution. Writeable. Valid values are:
v 'Red Hat Enterprise Linux (RHEL)'
Chapter 5. Managing virtual images 445
v 'SUSE Linux Enterprise Server (SLES)
v 'AIX Server'
v 'Windows 7'
v 'Windows Server 2008'
v 'IBM i Server'
type Optional. Operating system type. Writeable. Valid values are:
v 'Any'
v 'Linux'
v 'AIX'
v 'Windows
v 'IBM i'
minversion
Optional. Minimum operating system version number.
None.
BundleProducts reference:
You can manage products included in a bundle using the command-line interface.
BundleProduct provides the definition of a product contained in the bundle on a
virtual machine.
BundleProducts object
A BundleProducts object is used to create a BundleProduct object.
BundleProducts methods
The BundleProducts object has no methods that are unique to BundleProducts.
BundleProducts examples
Create a new BundleProduct object using the interactive wizard:
>>>wizard = icct.wizard()
>>>newProduct = icct.bundleproducts.create(wizard)
>>>wizard.toDict()
Create a new BundleProduct using a Python dict object:
>>>newProductDict = {version: 8.1, publisher: IBM, name: Lotus Notes}
>>>newProduct = icct.bundleproducts.create(newProductDict)
BundleProduct object
A BundleProduct object represents product definitions for a bundle defined in the
Image Construction and Composition Tool. Use the object to query and manipulate
the Product definitions. Attributes of the BundleProduct resource are represented
as Jython attributes of the object. Manipulate these Jython attributes using standard
Jython mechanisms to change the corresponding data. Any changes to this object
require the use of the Bundle.setProducts() method to save the change in the Image
Construction and Composition Tool.
446 IBM SmartCloud Orchestrator 2.3: User's Guide
BundleProduct attributes
The BundleProduct object has the following attributes, which are read- only unless
otherwise noted:
name Product name. Writeable.
publisher
Product publisher or vendor. Writeable.
version
Product verrsion. Writeable.
BundleProduct methods
None.
BundleResets reference:
You can manage image capture reset operation included in a bundle using the
command-line interface. BundleReset provides the definition of a reset operation
contained in the bundle on a virtual machine.
BundleResets object
A BundleResets object is used to create a BundleReset object.
BundleResets methods
The BundleResets object has no methods that are unique to BundleResets.
BundleResets examples
Create a new BundleReset object using the interactive wizard:
>>>wizard = icct.wizard()
>>>newReset = icct.bundleresets.create(wizard)
>>>wizard.toDict()
Create a new BundleReset using a Python dict object:
>>>newResetDict = { }
>>>newReset = icct.bundleresets.create(newResetDict)
BundleReset object
A BundleReset object represents an image capture reset operation for a bundle
defined in the Image Construction and Composition Tool. Use the object to query
and manipulate the reset operation. Attributes of the BundleReset resource are
represented as Jython attributes of the object. Manipulate these Jython attributes
using standard Jython mechanisms to change the corresponding data. Any changes
to this object require the use of the Bundle.setReset() method to save the change in
the Image Construction and Composition Tool.
BundleReset attributes
The BundleReset object has the following read-write attributes:
command
A BundleCommand object.
Chapter 5. Managing virtual images 447
files Python list of BundleFile objects.
BundleReset methods
None.
BundleSoftwareRequirements reference:
You can manage software requirements of a bundle using the command-line
interface. BundleSoftwareRequirement provides the definition of a
SoftwareRequirement operation contained in the bundle on a virtual machine.
BundleSoftwareRequirements object
A BundleSoftwareRequirements object is used to create a
BundleSoftwareRequirement object.
BundleSoftwareRequirements methods
The BundleSoftwareRequirements object has no methods that are unique to
BundleSoftwareRequirements.
BundleSoftwareRequirements examples
Create a new BundleSoftwareRequirement object using the interactive wizard:
>>>wizard = icct.wizard()
>>>newSoftwareRequirement = icct.bundlesoftwarerequirements.create(wizard)
>>>wizard.toDict()
Create a new BundleSoftwareRequirement using a Python dict object:
>>>newSoftwareRequirementDict = {minversion: uminversion, name: uname}
>>>newSoftwareRequirement = icct.bundlesoftwarerequirements.create(newSoftwareRequirementDict)
BundleSoftwareRequirement object
A BundleSoftwareRequirement object represents a software requirement for a
bundle defined in the Image Construction and Composition Tool. Use the object to
query and manipulate the SoftwareRequirement operation. Attributes of the
BundleSoftwareRequirement resource are represented as Jython attributes of the
object. Manipulate these Jython attributes using standard Jython mechanisms to
change the corresponding data. Any changes to this object require the use of the
Bundle.setSoftwareRequirements() method to save the change in the Image
Construction and Composition Tool.
BundleSoftwareRequirement attributes
The BundleSoftwareRequirement object has the following read-write attributes:
name Bundle name.
minversion
Minimum version.
BundleSoftwareRequirement methods
None.
448 IBM SmartCloud Orchestrator 2.3: User's Guide
Cloud providers reference:
You can manage cloud providers by using the command-line interface. Cloud
providers provide the definition of hypervisors capable of building and capturing
images.
Cloudproviders object
A cloudproviders object represents the collection of cloudproviders defined in
Image Construction and Composition Tool. Objects of this type are used to create,
delete, iterate over, list, and search cloudproviders.
Cloudproviders methods
The cloudproviders object has the methods described for a typical resource
collection. The following methods are unique to cloudproviders as their parameters
and return values differ from what is expected:
create()
This method creates a cloud provider. As the keys and values required for
creating the various types of cloud provider differ, you can use the sample
scripts in the cli_install_dir\samples directory when creating a cloud
provider. The directory cli_install_dir is the directory where the
command-line interface was downloaded and extracted. The method
accepts the following parameter:
dict A Jython dict object
Cloudprovider object
A cloudprovider object represents a particular cloud provider defined in Image
Construction and Composition Tool. Use the object to query the cloud provider.
Attributes of the cloud provider resource are represented as Jython attributes on
the cloudprovider object. Change these Jython attributes by using standard Jython
mechanisms to change the corresponding data in Image Construction and
Composition Tool.
Cloudprovider attributes
The cloudprovider object has the following attributes, which are read-only unless
otherwise noted:
cloudProviderType
Specifies the cloud provider type:
v openstack: OpenStack
cloudUser
User name of the cloud provider
cloudPassword
Password of the cloud provider user
description
The description of the cloud provider
id Unique identifier of the cloud provider
location
Address to connect to the cloud provider
Chapter 5. Managing virtual images 449
name Name of the cloud provider
ownerId
Owner ID from the user object
status State of the cloud provider. Value is active.
Cloudprovider methods
The following are cloud provider methods:
createImageFromRunningVM()
This method creates an image from a running VM. The method is valid
only for certain cloud providers. This method accepts the following
parameters:
name The image name
universalId
The image unique identifier
version
The image version. The valid format is:
major.minor.micro[.qualifier]
hostname
The IP address or host name of the running VM
username
The user name to log on to the running VM
password
The password to log on to the running VM
description
Optional. The image description
delete()
This method deletes the cloud provider.
getImages()
This method returns a Python list of image objects, which represent all the
images, both imported and extended, for the cloud provider. You can
optionally filter the list by using regular expressions. The method accepts
the following parameters:
nameRegEx
String for a regular expression to match against the image name.
Default is none.
universalIdRegEx
String for a regular expression to match against the image
universalId (symbolicName). Default is none.
versionRegEx
String for a regular expression to match against the image version.
Default is none.
descriptionRegEx
String for a regular expression to match against the image
description. Default is none.
To get a list of all the images for a cloud provider, use the following
method:
450 IBM SmartCloud Orchestrator 2.3: User's Guide
>>> icct.cloudproviders[0].getImages()
To get a list of all the images for a cloud provider that have Linux in the
name, use the following method:
>>> icct.cloudproviders[0].getImages(Linux)
To get a list of all the images for a cloud provider that have suse in the
universalId and 1.0.0 in the version, use the following method:
>>> icct.cloudproviders[0].getImages(None, suse, 1.0.0)
getBaseImages()
This method returns a Python list of image objects, which represent a list
of base images for the cloud provider. Only certain cloud providers
support base images. A cloud provider base image is an image that is
already known to the cloud provider. You must import the base image
definition so that the Image Construction and Composition Tool can use
these images. Base images that are already imported are not listed. You can
optionally filter the list by using regular expressions. The method accepts
the following parameters:
nameRegEx
String for a regular expression to match against the image name.
Default is none.
versionRegEx
String for a regular expression to match against the image version.
Default is none.
descriptionRegEx
String for a regular expression to match against the image
description. Default is none.
To get a list of all the base images, which are not already imported into the
cloud provider and which have Red in the name, use the following
method:
>>> icct.cloudproviders[0].getBaseImages(Red)
importBaseImage()
This method imports a base image definition into the cloud provider for
later use in extending an image. Only certain cloud providers support base
images. The method is synchronous. The method accepts the following
parameter:
dict A single Python dict object from the getBaseImages() method.
To return an image object that represents the imported base image, use the
following code:
>>> cloudprovider = icct.cloudproviders[0]
>>> baseImages = cloudprovider.getBaseImages()
>>> newImage = cloudprovider.importBaseImage(baseImages[0])
Chapter 5. Managing virtual images 451
Images reference:
You can manage images by using the command-line interface. Images provide the
definition of virtual machine images that can be used to import, extend, capture,
and export images.
Images object
An images object represents the collection of images defined in Image Construction
and Composition Tool. Objects of this type are used to create, delete, iterate over,
list, and search images in the tool.
To get a list of all the images, use the following method:
>>>allImages = icct.images
To get list with a specific bundle, for example, "bundle abc", listed first, use the
following method:
>>>bundles = icct.bundles[bundle abc]
Image attributes
The image object has the following attributes. All are read-only, unless otherwise
noted:
assetUri
Unique identifier used by the cloud provider to locate the image on the
server
created
The creation time of the image, in seconds since midnight, 1 January 1970
Coordinated Universal Time (UTC). When the image displays, this value is
shown as the date and time in the local time zone.
currentAssetState
Valid values are: draft, published
currentImageState
Valid values are: "completed", "complete_failed", "capture_failed",
"capturing", "deployable", "deleting", "importing", "out_of_sync", "synced",
"syncing", "sync_failed"
currentState
Valid values are: "draft", "published"
currentAssetState_text
Specifies the textual representation of currentAssetState. This field is a
string representation of currentAssetState in the preferred language of the
requester and is automatically generated by the tool.
currentImageState_text
Specifies the textual representation of currentImageState. This field is a
string representation of currentImageState in the preferred language of the
requester and is automatically generated by the tool.
currentState_text
Specifies the textual representation of currentState. This field is a string
representation of currentState in the preferred language of the requester
and is automatically generated by the tool.
452 IBM SmartCloud Orchestrator 2.3: User's Guide
description
Description of the image
id Unique identifier used by the cloud provider to locate the image on the
server
name Name of the image. Read/write.
remoteImage
Unique identifier used by the cloud provider to locate the image on the
hypervisor
symbolicName
See Universal identifiers on page 397.
updated
The last time the image was changed, in seconds, since midnight, 1
January 1970 UTC. When the image displays, this value is shown as the
date and time in the local time zone.
uri A URL that uniquely identifies the image.
version
The image version.
Image methods
The image object has the following methods:
addBundle()
This method adds a bundle to an image. If the image supports multiple
personalities and there is a single personality in the image, the bundle is
also added to the personality. Depending on how the bundle that is added
is defined, you can specify any installation and deployment parameters
required by the bundle. The addBundle() method accepts the following
parameters:
bundleId
The ID of the bundle to be added to the image. For example,
bundle.id.
installParams
A list of Python dict objects. The set of valid installation
parameters for the bundle can be obtained by calling
bundle.getInstallParameters(). The default value is an empty list.
deployParams
A list of Python dict objects. The set of valid deployment
parameters for the bundle can be obtained by calling
bundle.getDeployParameters(). The default value is an empty list.
>>> bundle = icct.bundles[0]
>>> installParams = bundle.getInstallParameters()
>>> installParams[0][value] = myValue
>>> image.addBundle(bundle.id, installParams)
addBundleToPersonality()
This method adds the specified bundle to a personality.
The addBundleToPersonality() method accepts the following parameters:
Key The unique key used to identify the personality within the image.
Chapter 5. Managing virtual images 453
bundleIdOrUri
The identifier of the bundle to be added to the personality. It can
be specified as either bundle.id or bundle uri.
deployParams
A list of Python dict objects. The set of valid deployment
parameters for the bundle can be obtained by calling
bundle.getDeployParameters(). The default value is an empty list.
Example 1:
>>> image=icct.images[2]
>>> waBundle=icct.bundles[0]
>>> pDeployParams=waBundle.getDeployParameters()
>>> pDeployParams[0][value]=newWaConfig2
>>> image.addBundle(waBundle.id)
>>> image.addBundleToPersonality(Key, waBundle.id, pDeployParams)
Example 2:
>>> image=icct.images[2]
>>> waBundle=icct.bundles[0]
>>> pDeployParams=waBundle.getDeployParameters()
>>> pDeployParams[0][value]=newWaConfig2
>>> image.addBundle(waBundle.id)
>>> bundleUri=image.getPlannedBundles()[1][uri]
>>> image.addBundleToPersonality(key, bundleUri, pDeployParams)
addLicense()
This method is used to add a license to an image. This method accepts the
following parameters:
name The displayable name of the new license.
licenseFile
A fully qualified path to the license file on the local machine.
lang The language of the license file. This parameter is optional and
defaults to en-US.
Example for Linux
>>> image.addLicense(uMy License, /home/license.txt)
Example for Windows
>> image.addLicense(uMy License, C:\\home\\license.txt)
addPersonality()
This method creates a personality with the specified parameters.
The addPersonality() method accepts the following parameters:
label The name of the new personality that you are adding.
key The unique key used to identify the personality within the image.
description
Optional. The description for the new personality that you are
adding.
isGroup
Optional. Boolean parameter that can be set to True to indicate that
multiple instances of the personality can be included in a virtual
system pattern. Otherwise, set to False, which is the default value.
isElastic
Optional. Boolean parameter that can be set to True to indicate that
the image supports dynamic resizing of the number of instances at
454 IBM SmartCloud Orchestrator 2.3: User's Guide
run time. Otherwise, set to False, which is the default value. By
using this option, you can add or remove instances from a
deployed virtual system pattern.
isIPv6 Optional. Boolean parameter that can be set to True to indicate that
the personality supports both IPv4 and IPv6. Set to False to
indicate that the personality supports IPv4 only, which is the
default value.
productGUID
Optional. The product ID for the new personality that you are
adding. Ensure that you specify a valid ID. You can specify
multiple personalities by using the character | as a separator.
>>> image=icct.images[2]
>>> image.addPersonality(personality1,example personality,
key1,False,False,False,5725-D64|5725-D57)
capture()
This method captures the image. An image must be captured before it can
be exported. This method is asynchronous.
>>> image.capture()
>>> image.waitFor()
>>> if image.currentImageState != completed:
>>> print \n\aCapture Failed!!!
delete()
This method is used to delete an image. The method accepts the following
parameter:
deleteFromCloudProvider
Optional, defaults to True. If the image contains a copy of the
image on the cloud provider, specifying True deletes the image
from the cloud provider also.
For example:
>>>image=icct.images[0]
>>>image.delete(False)
deleteLicense()
This method is used to delete a license from an image. The method accepts
the following parameter:
dict A Python dict object that was obtained from the list of dict objects
returned by getLicenses().
>>> licenses = image.getLicenses()
>>> image.deleteLicense(licenses[0])
deletePersonality()
This method deletes the personality with the specified key.
The deletePersonality() method accepts the following parameter:
key The unique key used to identify the personality within the image.
>>> image=icct.images[2]
>>> image.deletePersonality(key1)
When only one personality exists in the image and you attempt to delete it
by calling this method, a default personality is used with the parameter
values that are specified at the image level.
Chapter 5. Managing virtual images 455
export()
This method starts the asynchronous process of exporting an image to a
remote location. This method accepts the following parameters:
export_host
The IP address of the computer where the image is to be copied.
export_path
The directory to copy the image to. By default, the image name is
used to create the file name. To specify a different file name,
include the file name with an .OVA extension.
export_userid
The user ID for UNIX Secure Copy.
export_password
The password for UNIX Secure Copy.
ova_format
The OVA format. Valid values are:
'wca' WebSphere CloudBurst Appliance
privateKeyFile
Optional: The private key file name. If specified, the
export_password parameter is used as the passphrase.
Note: Not all cloud providers support export.
The various pieces of the image are extracted from the internal repository
and used to generate an OVA file. This file is then copied to the specified
location, as shown in the following example:
>>> image = icct.images[0]
>>> imageExportId = image.export(localhost, /tmp, userid, password)
>>> image.waitForExport(imageExportId)
This method returns an identifier for the exporting image task. This
method queues the operation in Image Construction and Composition Tool
and returns immediately. You can use the returned identifier to track the
status of the export process. You can use the waitForExport() method to
pause until the export completes. You can use the exportStatus() method to
query the last known export status but you must call the refresh() method
before calling the exportStatus() method to ensure that you get the latest
status.
exportStatus()
This method checks the status of the asynchronous process that is
exporting the image. This method accepts the following parameter:
exportId
The value returned from a image.export() call.
>>> exportedId = image.export(localhost, /tmp, userid, password)
>>> image.waitForExport(exportedId)
>>> image.refresh()
>>> image.exportStatus(exportedId)"
This method returns a string that specifies the current export status of the
Image object. To ensure the latest status, call the refresh() method before
calling the exportStatus() method. Valid export status values are
Exporting, Complete, Failed.
456 IBM SmartCloud Orchestrator 2.3: User's Guide
extend()
This method is used to extend, or clone, an existing image so that you can
create and update an image, such as adding bundles. This method is
asynchronous. This method accepts the following parameters:
dict: A Python dict object with the following key and value pairs
name The displayable name of the new image
description
A description of the new image
symbolicName
The universal identifier for the new image
version
The version of the new image
This method returns an image object that represents the new image:
>>> params = { }
>>> params[description] = my description
>>> params[name] = MyImageName
>>> params[symbolicName] = com.myname.MyNewImage
>>> params[version] = 1.0.0
>>> print \n Extend the image with the following parameters: %s % (params)
>>> newImage = image.extend(params)
>>> newImage.waitFor()
getLicenses()
This method returns a Python list of Python dict objects. Each Python dict
object contains the following keys:
id Internal identifier for the license.
name The displayable name.
type The type of license. Valid value is text.
content
The actual license agreement.
>>> licenses = image.getLicenses()
>>> print There are %s licenses % len(licenses)
>>> for license in licenses:
>>> print The license name is %s % (license[name])
>>> print %s % (license[ucontent].encode(utf-8))
getPersonalities()
This method returns a list of personalities in the image.
>>> image=icct.images[2]
>>> image.getPersonalities()
getPersonality()
This method returns a python dict object for the personality key specified.
The getPersonality() method accepts the following parameter:
key The unique key used to identify the personality within the image.
>>> image=icct.images[2]
>>> image.getPersonality(aPartKey)
getInstalledBundles()
This method returns all the installed bundles from an image.
Chapter 5. Managing virtual images 457
>>> image=icct.images[2]
>>> imagePlannedBundles=image.getInstalledBundles()
getPlannedBundles()
This method returns all the planned bundles from an image.
>>> image=icct.images[2]
>>> imagePlannedBundles=image.getPlannedBundles()
getSynchronizeLicenseAcceptanceRequired()
This method returns Python True if the license terms must be accepted on
the synchronize() method call, Python False otherwise. If license acceptance
is required by the cloud provider, you must pass the correct flag on the
synchronize() call or the synchronization of the image fails.
>>> image.getSynchronizeLicenseAcceptanceRequired()
getSynchronizeParametersForImage()
This method returns a Python list of Python dict objects that represent the
parameters for an image that must be passed on the synchronize() call.
Each dict object contains the following keys:
tag An internal string identifier. Generated by using the bundle name.
args APython list of Python dict objects. Each dict object contains the
following keys:
label User displayable text
isPassword
Python: True if this field is a password, False otherwise.
name Internal ID for the parameter
type Valid value is string.
userConfigurable
Python: True if the user can change this parameter
value The actual value
visible
Python: True if the user can see this parameter.
>>> syncParamsForImage = newImage.getSynchronize
ParametersForImage()
>>> print Parameter tag is %s %
(syncParamsForImage[0][tag])
>>> for arg in syncParamsForImage[0][args]:
>>> print Label %s has value %s %
(arg[label], arg[value])
getSynchronizeParametersForCloudProvider()
This method returns a Python list of Python dict objects that represent the
cloud provider parameters that must be passed on the synchronize() call.
Each dict object contains the following keys:
description
User displayable description
label User displayable text
isPassword
Python: True if this field is a password, False otherwise.
name Internal ID for the parameter
type Valid value is string.
458 IBM SmartCloud Orchestrator 2.3: User's Guide
validValues
If the value is restricted to a predefined set of values, a Python list
of Python dict objects is returned. Each dict object contains the
following keys: label user displayable text, value internal value
for the selection.
value The actual value.
>>> for aParam in syncParamsForCloud:
>>> if aParam[name] == password:
>>> print \n\n Setting the password
>>> aParam[value]=passw0rd
getVirtualSystemHostname()
This method returns the IP host name of the virtual system that is used to
synchronize an image. If the host name is not available, none is returned.
getVirtualSystemIPAddress()
This method returns the IP address of the virtual system that is used to
synchronize an image. If the IP address is not available, none is returned.
getVirtualSystemLogs()
This method gets the Image Construction and Composition Tool logs for
the virtual system that is used to synchronize an image and saves the
compressed file locally. This method accepts the following parameter: path
- the path on the local file system where the logs compressed file must be
saved. The default is logs.zip.
isPersonalitiesSupported()
This method returns True if the image supports multiple personalities.
>>> image=icct.images[2]
>>> image.isPersonalitiesSupported()
modifyPersonality()
This method modifies a personality, specified by using a personality key,
with the value specified in the parameter dict.
The modifyPersonality() method accepts the following parameters:
key The unique key used to identify the personality within the image.
dict A Python dict object. Allowed values for dict are: 'label',
'description', 'key', 'isGroup', 'isElastic', 'isIPv6', and 'productGUID'.
For 'productGUID', you can specify multiple personalities by using
the character | as a separator.
>>> image=icct.images[2]
>>> image.modifyPersonality(OS Part,{description:OS personality description,
isIPv6:True,productGUID:5725-D64|5725-D57})
modifyPersonalityBundleDeployParams()
This method changes the deployment parameters of the specified bundle,
to the parameters specified in the parameter deployParams.
The modifyPersonalityBundleDeployParams() method accepts the
following parameters:
key The unique key used to identify the personality within the image.
bundleIdOrUri
The identifier of the bundle to be added to the personality. It can
be specified as either bundle.id or bundle uri.
deployParams
A list of Python dict objects. The set of valid deployment
Chapter 5. Managing virtual images 459
parameters for the bundle can be obtained by calling
bundle.getDeployParameters(). The default value is an empty list.
When only one personality exists in the image, the deployParams
values are also applied to the parameters at the image level.
>>> image=icct.images[2]
>>> waBundle=icct.bundles[0]
>>> pDeployParams=waBundle.getDeployParameters()
>>> pDeployParams[0][value]=newWaConfig3
>>> image.modifyPersonalityBundleDeployParams(key1, waBundle.id, pDeployParams)
synchronize()
This method is used to synchronize an image. All bundles that are in the
planned state are added to the image. This method is asynchronous. This
method accepts the following parameters:
parametersForImage
A Python list of Python dict objects with the synchronization
parameters for the image. Use the
image.getSynchronizeParametersForImage() to get the Python list.
parametersForCloudProvider
A Python list of Python dict objects with the synchronization
parameters for the cloud provider. Use the
image.getSynchronizeParametersForCloudProvider() to get the
Python list.
AcceptTerms
Python: True is you accept the license terms, False otherwise.
>>> newImage.synchronize(syncParamsForImage, syncParamsForCloud, True)
>>> newImage.waitFor()
>>> if newImage.currentImageState != synced:
>>> print \n\aSync Failed!!!
waitForExport()
This method can be used to wait a specified time for the export of the
image to finish. The method can assist you in writing scripts that must
wait for Image Construction and Composition Tool to complete a particular
action. The waitForExport() method periodically checks for the export to
finish or a timeout expires. The method accepts the following parameters:
exportId
The ID returned by a call to the image.export() method.
maxWait
The maximum wait time in 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 the image export status is evaluated in
seconds. Floating point values can be used to express fractions of a
second. The default value is 60 seconds.
>>> image = icct.images[0]
>>> imageExportId = image.export(localhost, /tmp, userid, password)
>>> image.waitForExport(imageExportId)
460 IBM SmartCloud Orchestrator 2.3: User's Guide
Users reference:
You can administer the user of Image Construction and Composition Tool using
the command-line interface.
Users object
A users object represents the collection of users defined in Image Construction and
Composition Tool. Objects of this type are used to list and search for users.
Users method
The users object has the following methods:
admin Returns a user object representing the administrative user on the system.
For help on the user object returned, enter the following command:
>>> help(icct.users.admin())
self Returns a user object representing the current user of the command line
interface on the system. For help on the user object returned, enter the
following command:
>>> help(icct.users.self())
User object
A user object represents a particular user defined in the Image Construction and
Composition Tool. Use this object to query and manipulate the user definition on
the tool. Attributes of the user object and relationships between the user object and
other resources in the Image Construction and Composition Tool are represented as
Jython attributes on the user object. Manipulate these Jython attributes using
standard Jython mechanisms to change the corresponding Image Construction and
Composition Tool data.
User attributes
The user object has the following attributes:
currentmessage
The message associated with the status of the user. This field is an eight
character string value that is automatically generated by the tool. This field
is read-only.
currentmessage_text
Specifies the textual representation of currentmessage. This field is a string
representation of currentmessage in the preferred language of the requester
and is automatically generated by the tool.
currentstatus
The status of the user. This field is an eight -character string value that is
automatically generated by the tool. This field is read-only.
currentstatus_text
Specifies the textual representation of currentstatus. This field is a string
representation of currentstatus in the preferred language of the requester
and is automatically generated by the tool.
email The email address of the user. This field is a string value and has a
maximum length of 128 characters.
Chapter 5. Managing virtual images 461
fullname
The full name of the user. This field is a string value and has a maximum
length of 64 characters.
id The ID of the user. This field is read-only. This value is numeric and is
automatically generated by the system.
password
The password of the user. This field is a write-only string value and has a
maximum length of 128 characters.
username
The login name for the user. This field is a string value and has a
maximum length of 64 characters.
To change the user password, use the following code:
>>> user = icct.users[0]
>>> user.password = newpassword
Related tasks:
Command-line interface high-level procedure on page 420
This section provides the high-level steps for using the command-line interface
with links to more detailed information about each section.
Invoking the command-line interface on page 423
To perform administrative functions for Image Construction and Composition Tool,
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.
Getting help on the command-line interface on page 465
As you perform administrative functions using the command-line interface, you
can get help for all resources.
Downloading and configuring the command-line interface on page 422
To perform administrative functions for Image Construction and Composition Tool,
you can download and run the command-line interface on a local machine.
Related reference:
Invoking in batch mode on page 426
To invoke the command-line interface in batch mode, use these optional
parameters in addition to those parameters used to start the command-line
interface in interactive mode.
Invoking in interactive mode on page 425
To invoke the command-line interface in interactive mode, use these parameters.
Invoking the samples
You can invoke the samples by invoking as in batch mode.
Related information:
Python documentation
Linux download information
462 IBM SmartCloud Orchestrator 2.3: User's Guide
Problem determination reference for the command-line interface:
You can work with problem determination using the command-line interface.
Diagnostics object
The diagnostics object represents the diagnostics package in Image Construction
and Composition Tool. Help is available for the diagnostics object on the command
line interface. To get help, pass the diagnostics object as an argument to the help()
function, as shown in the following example:
>>> help(icct.diagnostics)
Diagnostics methods
The diagnostics object has the following method:
get This method gets the logs for Image Construction and Composition Tool
and saves the compressed file locally. This method accepts the following
parameter:
v path: The path on the local file system where the logs compressed file is
saved. The default is logs.zip.
Trace object
The trace object returns a TraceFile object representing the running trace file in
Image Construction and Composition Tool. 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:
v OFF
v SEVERE
v WARNING
v CONFIG
v INFO
v FINE
v FINER
v FINEST
The default value is OFF. The add method is shown in the following
example:
>>> icct.trace.add(com.ibm.cloud.icn, FINE)
>>> icct.trace.add(com.ibm.cloud.icn.not.interested)
remove
Removes an existing logger from the trace file specification. Logger names
use Java package name syntax:
>>> icct.trace.remove(com.ibm.cloud.icn.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
Chapter 5. Managing virtual images 463
v WARNING
v CONFIG
v INFO
v FINE
v FINER
v FINEST
The set method is shown in the following examples:
>>> icct.trace.set(com.ibm.cloud.icn, FINE)
>>> icct.trace.set(com.ibm.cloud.icn, SEVERE)
spec Returns a map with the trace file specification for Image Construction and
Composition Tool. 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. The default
value is 10.
>>> icct.trace.tail()
>>> icct.trace.tail(100)
Error object
The error object returns an ErrorFile object representing the running error file in
the Image Construction and Composition Tool. The error object has one method,
the tail method. The tail method prints the last <n> lines of the file, where <n> is
an integer. The default value is 10. The tail method is shown in the following
example:
>>> icct.error.tail()
>>> icct.error.tail(100)
Related tasks:
Command-line interface high-level procedure on page 420
This section provides the high-level steps for using the command-line interface
with links to more detailed information about each section.
Invoking the command-line interface on page 423
To perform administrative functions for Image Construction and Composition Tool,
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.
Getting help on the command-line interface on page 465
As you perform administrative functions using the command-line interface, you
can get help for all resources.
Downloading and configuring the command-line interface on page 422
To perform administrative functions for Image Construction and Composition Tool,
you can download and run the command-line interface on a local machine.
Related reference:
Invoking in batch mode on page 426
To invoke the command-line interface in batch mode, use these optional
parameters in addition to those parameters used to start the command-line
interface in interactive mode.
Invoking in interactive mode on page 425
To invoke the command-line interface in interactive mode, use these parameters.
Invoking the samples
You can invoke the samples by invoking as in batch mode.
464 IBM SmartCloud Orchestrator 2.3: User's Guide
Related information:
Python documentation
Linux download information
Getting help on the command-line interface
As you perform administrative functions using the command-line interface, you
can get help for all resources.
About this task
You can get help for any Image Construction and Composition Tool 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, but do not include the -c or -f parameters. Enter help, as
shown in the following example:
$ icct -h myicct.mycompany.com -P 443 -u joeadmin -p password
>>> help
The help command shown here is a Jython function. When it is used as shown, 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 command-line interface. In interactive mode, you can
invoke icct.help without the package prefix, as shown in the following example:
>>> help
v Invoke help for the package
To get help for the Image Construction and Composition Tool package, use the
following command:
>>> help(icct)
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(icct.cloudproviders)
The icct prefix is used to group all of the Image Construction and Composition
Tool-specific Jython functions into a single package to reduce the chances of
name collisions with functions and variables in your own scripts.
Related concepts:
Bundles reference on page 428
You can manage bundles using the command-line interface. Bundles provide the
definition of software and the scripts and parameters needed for installation,
configuration, and deployment of software on a virtual machine.
Chapter 5. Managing virtual images 465
Cloud providers reference
You can manage cloud providers by using the command-line interface. Cloud
providers provide the definition of hypervisors capable of building and capturing
images.
Images reference
You can manage images by using the command-line interface. Images provide the
definition of virtual machine images that can be used to import, extend, capture,
and export images.
Problem determination reference for the command-line interface on page 463
You can work with problem determination using the command-line interface.
Users reference on page 461
You can administer the user of Image Construction and Composition Tool using
the command-line interface.
Command-line interface resource object reference on page 428
Anything that can be managed in the Image Construction and Composition Tool is
a resource object on the command-line interface.
Related reference:
Invoking in batch mode on page 426
To invoke the command-line interface in batch mode, use these optional
parameters in addition to those parameters used to start the command-line
interface in interactive mode.
Invoking in interactive mode on page 425
To invoke the command-line interface in interactive mode, use these parameters.
Invoking the samples
You can invoke the samples by invoking as in batch mode.
Related information:
Python documentation
Linux download information
Troubleshooting issues with Image Construction and
Composition Tool
Use the information and content included here to understand how issues occur
during Image Construction and Composition Tool processes.
Log files for troubleshooting
Check the Image Construction and Composition Tool log files to determine where
problems occurred.
To access the Image Construction and Composition Tool server log files, from the
Administer menu, click Download logs. Save the compressed file and examine the
log files. The compressed file contains the following server log files:
v The trace.log file is the most recent trace file. The default size of the trace.log
file is 100 MB, with up to 9 backups.
v The error.log file is the most recent error file. The default size of the error.log
size is 2 MB, with up to 4 backups.
To access the log files from the logs directory, go to /drouter/ramdisk2/mnt/raid-
volume/raid0/logs and review the contents of the trace and error directories.
If problems occur during Image Construction and Composition Tool installation,
check the following Installation Manager log files to troubleshoot installation
problems:
466 IBM SmartCloud Orchestrator 2.3: User's Guide
/var/ibm/InstallationManager/logs/<date_time>.xml
/var/ibm/InstallationManager/logs/ant/<date_time>.log
where <date_time> is the date and time in a format similar to 20111024_1201.
To review specific Image Construction and Composition Tool messages, search in
the log files for the lines that start with the message code CYO.
Setting logging levels for troubleshooting
When troubleshooting is required, trace logs and error logs are generated. The
logged information that is generated depends on definitions that follow the Java
Logging convention and WebSphere Application Server levels.
The following log level values, listed from the least amount of logging (OFF) to the
most amount of logging (ALL) are available:
v OFF
v SEVERE
v WARNING
v INFO
v FINE
v FINER
v FINEST
v ALL
To modify the data that is logged, use one of the following methods.
Using the command-line interface
If you use the command-line interface, you can change the logging levels
dynamically. The changes take effect immediately and do not require Image
Construction and Composition Tool to be stopped and started. However, these
changes are lost after stopping the Image Construction and Composition Tool
server. For more information, see the following commands:
icct.trace.spec()
icct.trace.set(com.ibm.cloud.icn.execution, FINER)
in the topic Problem determination reference for the command-line interface on
page 463.
Modifying Image Construction and Composition Tool file manually
CAUTION:
Follow the exact syntax and format when editing this file.
You can update the file <install_dir>/config/logging-default.config manually.
These changes will take effect the next time the tool is restarted. To update the file,
complete the following steps:
1. Change to the directory <install_dir>. For example:
cd /opt/IBM/icct
2. Create a backup of the following file:
./icn.app/config/logging-default.config
3. Update the following file according to your requirements:
./icn.app/config/logging-default.config
Chapter 5. Managing virtual images 467
4. Stop and restart Image Construction and Composition Tool:
./stop.sh
./start.sh
Adjusting the configuration timeout settings
Adjusting the configuration timeout settings for troubleshooting Image
Construction and Composition Tool issues.
After you change the configuration timeout settings, you must restart the Image
Construction and Composition Tool. You can change the following timeout
settings:
# Configurable timeouts
"ShimTimeoutInMinutes" : 120,
# Enable Single sign-on
"EnableSSO" : false,
# ICCT instance user
"InstanceUser": "",
# When executing windows commands how long do we wait before we timeout
# in minutes. This default value for this timeout is 3 minutes.
"WindowsCommandTimeOut": 3,
# When running the execution bundle during a synchronization,
# how long do we wait before timing out in minutes. Default
# values is 6 hours.
"BundleExeuctionTimeout": 360,
# IWD REST timeout
"restReadTimeout": 90000,
# IWD Max deploy wait time (minutes) Default value is 0 which
# disables the max Deploy time. If set by default we have put in
# 300 minutes (5 hours). If this is set it will work in conjunction
# with the following configuration parameters:
# IWD_SYSTEM_CREATION_ATTEMPTS
# IWD_WAIT_FOR_SYSTEM_CREATION_RETRY_DELAY
# IWD_WAIT_FOR_DEPLOY_STATUS_DELAY
# IWD_WAIT_FOR_STARTUP_COMPLETE_DEALY
# IWD_MAX_SYSTEM_ACTIVATION_WAIT_TIME
"maxIWDDeployWaitTime": 0,
# IWD Max number of creation attempts also the same
# number of attempts for deployment status checks.
"IWD_SYSTEM_CREATION_ATTEMPTS": 120,
# IWD delay between creation retries (seconds)
"IWD_WAIT_FOR_SYSTEM_CREATION_RETRY_DELAY": 30,
# IWD delay between checks for deployment status in (seconds)
"IWD_WAIT_FOR_DEPLOY_STATUS_DELAY": 10,
# IWD wait for startup complete (seconds)
"IWD_WAIT_FOR_STARTUP_COMPLETE_DEALY": 30,
# Amount of time to wait for the system to become active. This is checked
# after system creation and deploy status checks. Default value is 300
# minutes.
"IWD_MAX_SYSTEM_ACTIVATION_WAIT_TIME": 300,
# How many times to check to see if the capture of an image
# has completed before we fail the capture. The default
# value is 180 times.
"IWD_MAX_CAPUTRUE_ATTEMPTS": 180,
468 IBM SmartCloud Orchestrator 2.3: User's Guide
# When capturing an images in IWD. How long to wait before
# we check the status again in seconds. Default value is 60 seconds.
"IWD_WAIT_FOR_CAPTURE_STATUS_DELAY": 60,
# Maximum number of time to attempt to capture a VM.
# Default values is 240 times.
"SCE_MAX_CAPTURE_VM_ATTEMPTS" : 240,
# Time to wait between connection attempts in seconds.
# Default value is 30 seconds.
"SCE_WAIT_BETWEEN_CAPTURE_ATTEMPTS" : 30,
# Maximum number of time to try to connect to a VM.
# Default value is 120 times.
"SCE_MAX_CONNECTION_ATTEMPTS" : 120,
# Time to wait between connecting to the VM.
# Default value is 10 seconds.
"SCE_WAIT_BETWEEN_CONNECTION_ATTEMPTS" : 10,
# When running commands on the VM. Time to delay between checking the return
# code of the command to see if it is done or not. Default value is 60 seconds
"SCE_WAIT_COMMAND_RETRY_DEPLAY" : 60,
# Maximum number of time to try and delete a VM.
# Default value is 30 times.
"SCE_MAX_DELETE_VM_ATTEMPTS" : 30,
# Time to wait between checking to see if the VM is deleted.
# Default value is 60 seconds
"SCE_WAIT_DELETE_VM_DELAY" : 60,
# Time to wait after the VMs deletion state goes to deprovision.
# Default value is 30 seconds.
"SCE_WAIT_DEPROVISION_DELAY" : 30,
Log files for virtual image synchronization
If you are synchronizing a virtual image and the deployed VM for the virtual
image is created, but the synchronization fails, you can download log files for the
synchronization. If the synchronization fails before the deployed VM is created, no
log files are available.
About this task
If the synchronization failed after the deployed VM was created, but before the
bundle installation, the following log files are available:
v error.log
v trace.log
If the synchronization fails during or after bundle installation, the following log
files are available:
error.log
The most recent error file
trace.log
The most recent trace file
Chapter 5. Managing virtual images 469
err.log
The error output of the synchronization script run on the VM, including
output of any bundle installation script run during the sync process
out.log
The standard output of the synchronization script run on the VM,
including output of any bundle installation script run during the sync
process
The err.log and out.log files are the log files for the bundle installation during
the synchronization process. They are located in the directory:/drouter/ramdisk2/
mnt/raid-volume/raid0/local/images/asset_id/logs where asset_id is the asset
identifier for the image. To download the log files, complete the following steps:
Procedure
1. From the Images screen and expand the Virtual System section of the image
that you are synchronizing.
2. Click Download logs. The compressed file containing the log files is
downloaded.
Troubleshooting problems during VM activation
If you encounter problems when activating a VM during deployment or
synchronization.
Symptoms
Problems occur when activating a VM during deployment or synchronization.
Resolving the problem
Linux
1. Log on to the VMware vSphere Client console to access the VM.
2. Review any log files with the extension .out and .err in the directory
/opt/ibm/ae/AR for errors.
3. In the directory /opt/ibm/ae/AP, check if a file named noap exists. If it
does, complete the following actions:
a. Delete the file noap.
b. Remove all contents of the directory AR.
c. Reboot the system.
d. Check that the VM now activates successfully.
If the problem still persists, complete the following steps:
1. Check the console as it starts for any indication of failure. In the user
interface, you might have to press the Esc key.
2. Log in and investigate each activation script, activating each class one
at a time. The scripts that are run during activation are listed in the file
/opt/ibm/ae/AL/master.al.
For example, if ConfigLocale causes problems, run the following
command once:
AE.sh -s ConfigLocale
If a class fails, run the script command. The file master.al lists which
script fails. They are usually in the directory /opt/ibm/ae/AS. Then
debug the script, until you find out which line in the script is failing.
The next step is to determine why the line in the script failed.
470 IBM SmartCloud Orchestrator 2.3: User's Guide
3. Enter the following command:
df -k
and ensure that the file activation.iso is mounted, usually in the
directory /tmp.
Windows
1. Log on to the VMware vSphere Client console to access the VM.
2. Review any log files with the extension .out and .err in the directory
c:\windows\setup\ibm\ar for errors.
3. In the directory c:\windows\setup\ibm\ap, check if a file named noap
exists. If it does, complete the following actions:
a. Delete the file noap.
b. Remove all contents of the directory ar.
c. Reboot the system.
d. Check that the VM now activates successfully.
If the problem still persists, complete the following steps:
1. Check the console as it starts for any indication of failure. In the user
interface, you might have to press the Esc key.
2. Log in and investigate each activation script, activating each class one
at a time. The scripts that are run during activation are listed in the file
c:\windows\setup\ibm\al\master.al.
For example, if ConfigLocale causes problems, run the following
command once:
AE.bat -s ConfigLocale
If a class fails, run the script command. The file master.al lists which
script fails. They are usually in the directory c:\windows\setup\ibm\as.
Then debug the script, until you find out which line in the script is
failing. The next step is to determine why the line in the script failed.
3. Enter the following command:
df -k
and ensure that the file activation.iso is mounted, usually CD-ROM.
Working with enablement bundles
Enablement bundles are bundles that hide cloud-specific details. They provide a
base on which you can build virtual images using cloud-independent bundles.
When you are building a virtual image, Image Construction and Composition Tool
automatically selects an enablement bundle for your virtual image that matches
your cloud provider and operating system and version.
The Image Construction and Composition Tool automatically selects an enablement
bundle for your virtual image. During the virtual image building process, you
cannot remove the enablement bundle from your virtual image. If you are creating
a virtual image and the base virtual image already contains an enablement bundle,
no action is performed.
When you work with virtual images and bundles, you must keep the enablement
bundles in Image Construction and Composition Tool workspace. When you select
a base virtual image, it is automatically added to the appropriate enablement
Chapter 5. Managing virtual images 471
bundle. After you extend your virtual image, giving it a name, symbolic name,
version, and description, you see the following message in the Operating System
section of your virtual image:
Activation Framework: <name of enablement bundle selected by the tool>
You can then add bundles to your virtual image and synchronize it.
Important: Do not delete the Enablement Bundle for Exploiter Name enablement
bundle. This bundle is required.
If the enablement bundle is removed or not available, the following information is
displayed in the Operating System section of your virtual image:
Activation Framework: <Not found>
If you accidentally delete this enablement bundle, you can import it again from the
following location: <installation_path>/icn.app/private/expanded/ibm/
icn.enablement-<version>/bundles/R1/
com.ibm.icon.enablement.ux.iwd_<version>.ras where <installation path> is
similar to /opt/IBM/icon. Access this top-level directory and change directory to
the appropriate cloud provider to find the enablement bundle for the particular
operating system you require.
Updating Activation Engine in a virtual image
If Image Construction and Composition Tool can successfully deploy a virtual
image, Activation Engine is automatically updated. However, you might need to
update Activation Engine if the image cannot be successfully deployed by the
cloud provider.
There is a script provided with the Image Construction and Composition Tool that
you can run to update Activation Engine in virtual images.
Note: This topic describes upgrading from Activation Engine version 2.0 and
higher. Upgrading from version 1.x is a more complex procedure that requires
more than a simple version upgrade. For more information, see the Activation
Engine documentation.
You can check the version of Activation Engine in one of the following ways:
v Display the content of file /opt/ibm/ae/version.
Note: Does not apply to IBM i.
v Call Activation Engine with the --version flag by running ./AE.sh --version.
Look for a line similar to: [2012-05-12 23:29:15,510] INFO: 2.1.1.14.
v Use RPM to query the installed version of Activation Engine by running rpm -qa
| grep activation-engine.
Note: Does not apply to IBM i.
Some Activation Engine versions between versions 2.1 and 2.1-1.23 delete user data
because some RPM scripts are incorrectly called during the upgrade. So, for
versions between 2.1 and 2.1-1.23, invoke the RPM with the --noscripts flag to
preserve user data.
Automated upgrade
472 IBM SmartCloud Orchestrator 2.3: User's Guide
To perform an automated upgrade, run the following script:/opt/ibm/ae/
upgradae.sh new-rpm-path where new-rpm-path is the new RPM that upgrades an
installed RPM.
Note: Does not apply to IBM i.
Manual upgrade
To upgrade Activation Engine manually, determine the level of the RPM installed.
Depending on the level, run the following command:
RPM prior to version 2.1-1.24
rpm --noscripts --force -Uvh new-rpm-path
RPM from 2.1-1.24 and higher
rpm -Uvh new-rpm-path
Note: Does not apply to IBM i.
Image Construction and Composition Tool does not respond
Determine the reasons that the Image Construction and Composition Tool might
not respond.
Image Construction and Composition Tool does not start after installation:
Before running the IBM Installation Manager installer to install Image Construction
and Composition Tool on a system, ensure that the port number 443 is not in use
by another application. If the port number 443 is not available, Image Construction
and Composition Tool does not start after you completed the installation.
Symptoms
The Image Construction and Composition Tool fails to start and a ZSO error
occurs.
Causes
Port 443 is in use by another application.
Diagnosing the problem
Check the following Installation Manager log files to troubleshoot the problem:
/var/ibm/InstallationManager/logs/<date_time>.xml
/var/ibm/InstallationManager/logs/ant/<date_time>.log
where date_time is the date and time in a format similar to 20111024_1201.
The following error message appears in the Installation Manager log files:
CWPZC8028E: An unknown ZSO error occurred.
Launching of the ZSO failed with return code -1
CWPZT0601E: Error: Command start failed
Resolving the problem
Before installing Image Construction and Composition Tool, ensure that port
number 443 is not in use by another application on the system.
Chapter 5. Managing virtual images 473
Image Construction and Composition Tool returns EOFException:
While running the Image Construction and Composition Tool on a system, you
receive a 500 error code and an EOFException.
Symptoms
The Image Construction and Composition Tool fails to respond to user requests
and EOFExceptions are generated.
Causes
The Image Construction and Composition Tool has run out of disk space.
Diagnosing the problem
The following error appears in the user interface: java.lang.RuntimeException:
Unable to create /drouter/ramdisk2/mnt/raid-volume/raid0/.zero/
userzoneStore/.
Check the log file to troubleshoot the problem. The following error message
appears in the log file:
[2012-06-19 12:42:16:980 EDT] 00000021 JavaGCSeriali E
zero.core.context.zones.JavaGCSerializer
deserialize CWPZC0029E: Unable to serialize key <[B@7ee67ee6> in the ser zone.
java.io.EOFException
at java.io.ObjectInputStream$PeekInputStream.readFully
(ObjectInputStream.java:2298)
Resolving the problem
To resolve the problem, complete the following steps:
1. Stop the Image Construction and Composition Tool using stop.sh.
2. Delete all .ser files located in the /drouter/ramdisk2/mnt/raid-volume/raid0/
.zero/userzoneStore directory and subdirectories.
3. Start the Image Construction and Composition Tool using start.sh.
4. Free up /drouter disk space by deleting any images that you do not need.
Install executable launcher error during installation
If you try to install the Image Construction and Composition Tool on a system
where it already exists, the installation is not successful.
Symptoms
When you run ./install, the Image Construction and Composition Tool
installation fails with the following error message:
The Install executable launcher was unable to locate its companion shared library.
Causes
The error indicates that a version of the Image Construction and Composition Tool
already exists on the system.
Resolving the problem
Upgrade the Image Construction and Composition Tool instead of installing it. For
more information, see Upgrading from a previous version on page 393.
Note: If you launched the installation from a mounted Windows driver, copy and
run the installation locally.
474 IBM SmartCloud Orchestrator 2.3: User's Guide
Exec error 1 during installation
You receive an executable error when you try to install the Image Construction and
Composition Tool on a system.
Symptoms
You receive the following error during installation:
exec error 1
Causes
The error indicates that port 443 is already in use and the Image Construction and
Composition Tool cannot access it.
Resolving the problem
Ensure that port 443 is not in use by other applications.
Universal ID and version must be unique
The combination of universal ID and version for every asset must be unique. If
you extend an image and you do not enter a unique universal ID and version
number combination for the newly extended virtual image, you receive an error
message.
Symptoms
When you are extending a virtual image, the following error message is included
in the trace.log and error.log files:
Cannot create the image: Error: HTTP response code:409
message: "CYOIG0005E: Universal ID <ID>_<version> is not unique."
Causes
The universal ID in combination with the version for the new virtual image that
you are extending must be unique.
Resolving the problem
Enter a unique universal ID and version combination for the extended asset.
Cancel - use the current file link does not work
The Cancel - use the current file link, located on the Files to Copy section on the
Install or Config tab for a software bundle, might not work correctly.
Symptoms
This problem might occur if you upload a file to the Files to Copy section on the
Install or Config tab for a software bundle, save that file, and edit it. After saving
and editing the file, you then select a new file to upload and click Cancel - use the
current file. Although you tried to revert to the previous file, the new file is still
displayed.
Resolving the problem
If the file is not being updated correctly, click Cancel . If you click OK, and see the
wrong file, refresh the software bundle to omit all the changes.
Chapter 5. Managing virtual images 475
Failure during OVA disk conversion
Conversion of disk files contained in the Open Virtualization Appliance (OVA) files
fails.
Symptoms
During OVA import or OVA export operations, errors occur when the disk files are
converted.
Resolving the problem
Verify that the following conditions are met:
v Verify the available disk space in the directory /drouter. The amount of free
space must be at least twice the size of the disk being converted.
v Ensure that the required ld-linux shared library is available. If you are getting
errors similar to the following example:
Error messages such as "Bad ELF interpreter"
verify that the required software is installed. For example, on Red Hat Enterprise
Linux V6.1, you must install the following packages:
yum install libz.so.1
yum install ld-linux.so.2
Import or export of the OVA file fails
Symptoms
During OVA import or OVA export operations, errors occur. The log has the
following message:
java.io.IOException: No space left on device.
Resolving the problem
Ensure that the following conditions are met:
v Verify the available disk space in the directory /drouter. In some cases, the
amount of free disk space must be at least twice the size of the image being
converted.
v Ensure that unneeded images are deleted from the Image Construction and
Composition Tool to allow for more disk space.
v Ensure that older archived log files are removed to allow for more disk space.
Error occurs during OVA export
Symptoms
During OVA export operations, errors occur. You might see the following error
message in the log files:
CYOCU0005
Resolving the problem
Ensure that the user specified in the user interface has write permission for the
specified target folder. For information about the log files, see Log files for
troubleshooting on page 466.
476 IBM SmartCloud Orchestrator 2.3: User's Guide
Virtual image capture fails
If the virtual image capture fails, you might need to delete the failed virtual image
and then create the virtual image and complete the capture process again.
Symptoms
The virtual image capture fails with the following error message:
CYOCE0002E: The capture cannot be started because the resources are
not sufficient to capture the image.
Check your private instance quota. The image cannot be saved.
Resolving the problem
To enable the capture option again, expand the virtual image capture error and
click the option to try to capture again. Alternatively, delete the failed virtual
image and create the virtual image again. Then, complete the capture process
again.
If the problem is not resolved, check the image quota of your IBM SmartCloud
Enterprisecloud provider. Log on to IBM SmartCloud Enterprisevia a web browser
and check how many stored images you are allowed versus how many you have.
You might need to delete a stored image or increase the quota for the number of
stored images.
Extending an image fails
In IBM SmartCloud Orchestrator version 2.1 fix pack 1, when you attempt to
extend one of the IBM WebSphere Application Server Hypervisor Edition images
with any bundle, the capture process might fail in the Image Construction and
Composition Tool.
Symptoms
You receive an error in the trace log, similar to the following error:
00000045 ClientRestHel I com.ibm.cloud.icn.core.rest.ClientRestHelper executeRequestInternal
executeRequest: PUT https://172.16.19.22/resources/virtualImages/66/viparts/161/vitopologies/0
00000045 ClientRestHel I com.ibm.cloud.icn.core.rest.ClientRestHelper executeRequestInternal
user: cbadmin
00000045 ClientRestHel I com.ibm.cloud.icn.core.rest.ClientRestHelper executeRequestInternal
read timeout: 90000
00000045 ClientRestHel I com.ibm.cloud.icn.core.rest.ClientRestHelper executeRequestInternal
Response code = 500
00000045 ClientRestHel I com.ibm.cloud.icn.core.rest.ClientRestHelper executeRequestInternal
Message= Internal Server Error
00000045 ? R java.io.IOException: Server returned HTTP response code: 500 for URL:
https://172.16.19.22/resources/virtualImages/66/viparts/161/vitopologies/0
00000045 ? R at sun.reflect.NativeConstructorAccessorImpl.newInstance0(Native Method)
00000045 ? R at sun.reflect.NativeConstructorAccessorImpl.
newInstance(NativeConstructorAccessorImpl.java:44)
00000045 ? R at sun.reflect.DelegatingConstructorAccessorImpl.
newInstance(DelegatingConstructorAccessorImpl.java:27)
00000045 ? R at java.lang.reflect.Constructor.newInstance(Constructor.java:516)
00000045 ? R at sun.net.http://www.protocol.http.httpurlconnection$6.
run/(HttpURLConnection.java:1491)
00000045 ? R at java.security.AccessController.doPrivileged(AccessController.java:251)
00000045 ? R at sun.net.http://www.protocol.http.httpurlconnection.
getchainedexception/(HttpURLConnection.java:1485)
00000045 ? R at sun.net.http://www.protocol.http.httpurlconnection.
getinputstream/(HttpURLConnection.java:1139)
00000045 ? R at com.ibm.net.ssl.www2.protocol.https.b.getInputStream(b.java:96)
00000045 ? R at com.ibm.cloud.icn.core.rest.ClientRestHelper.
executeRequest(ClientRestHelper.java:159)
00000045 ? R at com.ibm.cloud.icn.core.rest.ClientRestHelper.
putRequest(ClientRestHelper.java:136)
00000045 ? R at com.ibm.cloud.icn.cloudprovider.iwd.IWDCloudProviderUtils.
updateRemoteTop(IWDCloudProviderUtils.java:863)
00000045 ? R at com.ibm.cloud.icn.cloudprovider.iwd.IWDCloudProviderUtils.
Chapter 5. Managing virtual images 477
updateRemoteIWDMetadata(IWDCloudProviderUtils.java:466)
00000045 ? R at com.ibm.cloud.icn.cloudprovider.iwd.IWDCloudProviderImpl.
updateCloudBaseImage(IWDCloudProviderImpl.java:2753)
00000045 ? R at com.ibm.cloud.icn.cloudprovider.CloudProvider.
updateCloudBaseImage(CloudProvider.java:613)
00000045 ? R at com.ibm.cloud.icn.execution.engine.IconImageCompleter.
run(IconImageCompleter.java:65)
00000045 ? R at com.ibm.cloud.icn.execution.engine.IconImageCapturer.
run(IconImageCapturer.java:121)
00000045 ? R at java.lang.Thread.run(Thread.java:736)
00000045 ? R Caused by:
00000045 ? R java.io.IOException: Server returned HTTP response code: 500 for URL:
https://172.16.19.22/resources/virtualImages/66/viparts/161/vitopologies/0
00000045 ? R at sun.net.http://www.protocol.http.httpurlconnection.
getinputstream/(HttpURLConnection.java:1436)
00000045 ? R at java.net.HttpURLConnection.getResponseCode(HttpURLConnection.java:379)
00000045 ? R at com.ibm.net.ssl.www2.protocol.https.b.getResponseCode(b.java:12)
00000045 ? R at com.ibm.cloud.icn.core.rest.ClientRestHelper.
executeRequestInternal(ClientRestHelper.java:245)
00000045 ? R at com.ibm.cloud.icn.core.rest.ClientRestHelper.
executeRequest(ClientRestHelper.java:153)
00000045 ? R ... 8 more
00000311 IWDCloudProvi I com.ibm.cloud.icn.cloudprovider.iwd.IWDCloudProviderImpl deleteVM vm record:
{MEMORY=2048, CPUPERCENTAGE=null, POWERON=null, CPUCOUNT=1, CREATED=1350473787243,
CURRENTSTATUS=CYO01011, VMLOCATION=null, IPADDRESS=9.60.18.160,
DATASTOREID=http://127.0.0.1:9777/resources/ensembles/9.60.18.165/storages/LINUX165,
RUNTIMEID=1350473793462, HOSTNAME=9.60.18.160, IMAGEID=66, USERNAME=root, UPDATED=1350489882462,
PASSWORD=w9z7riSNOhGlEl8IVx96SA==, ID=3, UUID=162, MEMORYPERCENTAGE=null}
00000311 IWDCloudProvi I com.ibm.cloud.icn.cloudprovider.iwd.IWDCloudProviderImpl deleteVM calling
delete of virtual system with id: 162
00000311 ClientRestHel I com.ibm.cloud.icn.core.rest.ClientRestHelper executeRequest executeRequest :
GET /resources/virtualSystems/162
00000311 ClientRestHel I com.ibm.cloud.icn.core.rest.ClientRestHelper executeRequest user : cbadmin
00000311 ClientRestHel I com.ibm.cloud.icn.core.rest.ClientRestHelper executeRequestInternal
executeRequest: GET https://172.16.19.22/resources/virtualSystems/162
00000311 ClientRestHel I com.ibm.cloud.icn.core.rest.ClientRestHelper executeRequestInternal
user: cbadmin
00000311 ClientRestHel I com.ibm.cloud.icn.core.rest.ClientRestHelper executeRequestInternal
read timeout: 90000
00000311 ClientRestHel I com.ibm.cloud.icn.core.rest.ClientRestHelper executeRequest executeRequest :
GET /resources/virtualSystems/162
00000311 ClientRestHel I com.ibm.cloud.icn.core.rest.ClientRestHelper executeRequest user : cbadmin
00000311 ClientRestHel I com.ibm.cloud.icn.core.rest.ClientRestHelper executeRequestInternal
executeRequest: GET https://172.16.19.22/resources/virtualSystems/162
00000311 ClientRestHel I com.ibm.cloud.icn.core.rest.ClientRestHelper executeRequestInternal
user: cbadmin
00000311 ClientRestHel I com.ibm.cloud.icn.core.rest.ClientRestHelper executeRequestInternal
read timeout: 90000
Resolving the problem
If you have the Intelligent Management Pack option available for WebSphere
Application Server Hypervisor Edition images, enable the option in IBM
SmartCloud Orchestrator version 2.1 fix pack 1. Afterwards, perform the following
steps:
1. Import the image into the Image Construction and Composition Tool again.
2. Extend the image.
3. Add one or more bundles.
4. Capture the image again.
478 IBM SmartCloud Orchestrator 2.3: User's Guide
Virtual images that contain old versions of the activation engine
cannot be deployed
If you are attempting to deploy virtual images by using Image Construction and
Composition Tool, the deployment of these images might stop unexpectedly.
Symptoms
When deploying virtual images in Image Construction and Composition Tool, if
the activation engine version in these images is earlier than 2.1.1.24, the
deployment of these images might stop unexpectedly.
Causes
If the version of the activation engine used in the image is earlier than 2.1.1.24, the
file ovf-env.done might not be generated and the process cannot detect that the
activation completed.
Resolving the problem
Upgrade the automation engine. For more information, see Updating Activation
Engine in a virtual image on page 472.
Files are not replaced correctly
If you add a file to the Files to Copy section on the Install, Config, or Rest tab of
a software bundle and later replace that file, the content of the file is not updated,
even though the name of the file is updated correctly in the Image Construction
and Composition Tool. The content is updated correctly after you save the software
bundle.
Symptoms
If you replace the file in the Files to Copy section on the Install, Config, or
Resttab of a software bundle, the content of the file is not updated unless you save
the software bundle. However, the name of the new file is displayed in the Image
Construction and Composition Tool.
Resolving the problem
Save the software bundle before you click the file to download the contents.
The user interface stops responding while uploading files
Image Construction and Composition Tool stops responding when uploading a file
that is larger than 2 GB.
Symptoms
When you create a software bundle and upload a file with a size larger than 2 GB
in the Install section. You might be waiting a long time for the file to upload,
while the user interface seems to stop responding.
Causes
There is a 2-GB file size limit for uploading in the browser. There is little
information in the trace and error log files.
Resolving the problem
To upload large files to a software bundle:
1. In the New file dialog box, select the Remote option and specify the URL for
the file to upload in the text box. Uploads done on this dialog box are
asynchronous, while local uploads are synchronous.
2. Verify that the file is uploading by checking the status indicator for the entry in
the Files to copy table.
Chapter 5. Managing virtual images 479
3. Continue to refresh the software bundle definition until the upload is
completed.
Limitation when performing concurrent updates
Do not perform concurrent update operations on images, bundles, and other
objects in Image Construction and Composition Tool, either using different
browsers or using a browser and the command line interface.
Symptoms
The object might not be updated correctly.
Resolving the problem
Only use a single mechanism of updating an object in Image Construction and
Composition Tool, either using the web interface in a single browser, or using the
command-line interface.
Cannot remove software bundles from a personality
If a software bundle is added to a personality and then the virtual image is
synchronized, the added software bundles cannot be removed from the personality.
Symptoms
The software bundles cannot be removed from the personality.
Resolving the problem
Delete the existing personality and create another personality where you add only
the software bundles that you need.
Bundles are not displayed in the list of compatible images
Symptoms
Bundles are not displayed in the list of compatible images.
Resolving the problem
On the Add software bundles dialog box, clear the check box Show only bundles
compatible with the image.
Limitation when adding bundles to a personality
For virtual images that have a single personality, all software bundles that are
added to the image are automatically added to the personality. This behavior
means that, in this case, the personality is identified with the image itself.
Symptoms
For virtual images that have multiple personalities, software bundles that are
added to the image are not added automatically to any of the personalities in the
image. For these images, you must explicitly add the software bundles to the
personalities, as needed.
Resolving the problem
If you want to avoid this limitation, complete steps in the following order:
1. Extend the virtual image with the single personality.
2. Add software bundles, as required. The bundles are added to the personality
by default.
3. Add another personality to the image.
4. Add more bundles to the images. The bundles are not added to any personality
by default.
5. If required, add the bundles to the appropriate personality.
480 IBM SmartCloud Orchestrator 2.3: User's Guide
For more information about completing these tasks, see:
v Extending virtual images
v Adding software bundles to virtual images on page 403
v Adding personalities to virtual images on page 405
Limitation when deleting images that are synchronizing
You cannot delete an image while it is synchronizing.
Symptoms
The image is synchronizing and the synchronization is not proceeding successfully.
Resolving the problem
Do not delete an image while it is synchronizing. Wait until the synchronization
process has completed and then delete it.
Time lag when deleting virtual images
If you delete a virtual image, it might take awhile for the virtual image to be
completely removed from view.
Symptoms
A virtual image that you deleted is still displayed in a view in the tool. You can
view and select the virtual image for some time until the deletion process has
completed.
Causes
There is a refresh issue that causes a deleted virtual image to remain in view until
the deletion process has completed. The deletion process can take awhile to
complete.
Resolving the problem
Wait until the deletion process has completed and refresh your browser.
Note: The final time that you refresh the resource and then select the virtual
image, you receive an unable to load resource error message because the virtual
image has been deleted at this point. After this, the view is refreshed.
Virtual image synchronization takes a long time
Your virtual image synchronization process takes a long time to complete.
Symptoms
Virtual image synchronization takes a long time and might time out and fail.
Causes
The cloud performance is poor. Cloud performance is not always consistent and
can vary depending on usage and your connection. Depending on the cloud
performance at any particular time, your synchronization can take longer to
complete. The synchronization process continues if there are performance issues. If
the synchronization process is very slow and the performance is particularly poor,
the synchronization eventually times out and you are notified that the
synchronization failed because of performance issues.
Resolving the problem
Solution 1
After the virtual image synchronization process times out, try the
synchronization again.
Chapter 5. Managing virtual images 481
Solution 2
If you are still having synchronization problems, check the log files to
determine the particular cloud provider issue that is affecting
synchronization. Resolve the problem and try again.
Solution 3
This solution applies to IBM SmartCloud Orchestrator.
If you are still having synchronization problems, complete the following
steps:
1. Open the configuration file /opt/IBM/icon/icn.app/config/
configuration.config and locate the parameter restReadTimeout in the
file.
The contents of the file is similar to the following example:
# Configurable timeouts
"ShimTimeoutInMinutes" : 120,
# Enable Single sign-on
"EnableSSO" : false,
# ICCT instance user
"InstanceUser": "",
# IWD REST timeout
"restReadTimeout": 90000,
2. Increase the value for the parameter restReadTimeout to allow for a
longer timeout between REST calls.
This parameter is defined in milliseconds (ms). From the default value
90000 ms, increase this number in 20000 ms (20 seconds) increments:
110000, 130000, and so on.
3. Between the steps of increasing the values, restart Image Construction
and Composition Tool, and try the synchronization again.
Virtual image synchronization fails after five hours for images
Virtual image synchronization fails after five hours for images on IBM Workload
Deployer and IBM SmartCloud Orchestrator.
Symptoms
Virtual image synchronization fails after five hours even if the image deployment
is still running on IBM Workload Deployer.
Causes
By default, the Image Construction and Composition Tool waits up to five hours
for the deployment of an image on IBM Workload Deployer or IBM SmartCloud
Orchestrator. If the deployment does not complete within that time, the Image
Construction and Composition Tool returns a failure.
Resolving the problem
In the configuration.config file in the <ICCT_INST_DIR>/icn.app/config/
directory, edit the parameter maxIWDDeployWaitTime to increase the wait time. The
default value is 300 minutes which is five hours.
Restart the Image Construction and Composition Tool to apply the changes.
482 IBM SmartCloud Orchestrator 2.3: User's Guide
SSL exception
In the command-line interface on Linux, you receive an SSL exception error.
Symptoms
On Linux, in the command-line interface of the Image Construction and
Composition Tool, you receive the SSL exception error socket.sslerror: (-1,
SSL exception).
Causes
If you are using the command-line interface on Linux and receive an SSL exception
error, there might be a compatibility issue with the Java Runtime Environment
(JRE) that you are using.
Resolving the problem
Use the java -version command to verify which JRE version you are using.
To resolve the communication error, you can use a different JRE. You can
download IBM JRE version 6 for Linux from the following web address:
http://www.ibm.com/developerworks/java/jdk/linux/download.html.
Once you have the JRE installed, you can set environment variables to allow this
new JRE to be used by the command-line interface instead of the existing JRE. For
example:
export JAVA_HOME=/opt/IBM/icct/jre
export PATH=$JAVA_HOME/bin:$PATH
Cannot pass characters for arguments on the command line
You might not be able to pass certain characters for arguments on the
command-line interface.
Symptoms
When invoking the command-line interface on Windows and passing arguments
that contain an exclamation point (!), this character is removed from the argument
during processing.
Causes
The command-line interface is based on Python. In certain cases, specific characters
are used to indicate special characteristics.
Resolving the problem
When you want to pass the exclamation point as a command-line argument, use
the caret character (^) to escape the exclamation point character. Also, enclose the
argument in double quotation marks. For example, instead of "password!", use
"password^!"
Deploying a pattern with parts created by Image Construction
and Composition Tool might not work
Deploying a pattern containing parts created by the Image Construction and
Composition Tool might not work correctly.
Symptoms
Deploying a pattern with parts coming from an image created in Image
Construction and Composition Tool for a Windows operating system might not
activate correctly if the bundles specified in the corresponding Image Construction
and Composition Tool personality contain dependencies against other bundles.
Chapter 5. Managing virtual images 483
Resolving the problem
When you define bundles to be added to personalities, do not specify
dependencies. This prevents the Image Construction and Composition Tool from
performing a set of validation checks against the installation order and the
presence of any dependant bundle, but it allows a successfully activated
personality. Because the Image Construction and Composition Tool does not
perform dependency checks in this case, ensure that all the dependant bundles are
added to the image and required personalities. Ensure that their order is correct,
for example, any dependant bundle must come after its dependency.
Import fails using OpenStack cloud provider
The import of a virtual image fails when you are using the OpenStack cloud
provider.
Symptoms
Import fails when you are using the OpenStack cloud provider and the trace file
contains: Unable to find specified platform for import to Image Construction and
Composition Tool.
Causes
You are using the OpenStack cloud provider with the connection Direct to
OpenStack. This configuration is not supported in IBM SmartCloud Orchestrator.
Resolving the problem
Create the OpenStack cloud provider with a connection type of Indirect through
the IBM IaaS Gateway.
New password is not set after upgrade or reinstallation
When you upgrade or reinstall IBM Image Construction and Composition Tool
after unistallation, the new password is not set.
Symptoms
When you upgrade or reinstall Image Construction and Composition Tool, if you
decide to keep the current drouter directory, the password is not set to the new
one specified during the installation or upgrade. Instead, the original password is
still used.
Resolving the problem
After you install or upgrade to the higher version of Image Construction and
Composition Tool, update the password on the Image Construction and
Composition Tool user interface.
Virtual image synchronization problems
Determine the reason why your virtual image synchronization fails.
Synchronization fails for a virtual image imported from a running virtual
machine:
If you import a virtual image from a running virtual machine, the virtual image
does not synchronize if Network Manager is running on the virtual machine.
Network Manager must be disabled on the virtual machine.
Symptoms
The virtual image does not synchronize.
Causes
484 IBM SmartCloud Orchestrator 2.3: User's Guide
Network Manager has not been disabled on the virtual machine.
Resolving the problem
Disable Network Manager on the virtual machine and import the virtual image
again.
To disable network manager, complete a procedure similar to the following:
1. From the command line, run the following:
service NetworkManager stop
2. Run the following command:
chkconfig NetworkManager off
3. Ensure that the interfaces are not controlled by Network Manager by editing
the following items in the /etc/sysconfig/network-scripts/ifcfg-eth0 file:
NM_controlled = no
and
ONBOOT=yes
After you have disabled Network Manager on the virtual machine, try to import
and synchronize the virtual image again.
There are many reasons for a synchronization failure. To help determine the
problem, check the Image Construction and Composition Tool log files to debug.
Virtual image synchronization fails because of return code value:
Virtual image synchronization fails if you use a script for the bundle installation
that produces a return code value that is greater than zero. The Image
Construction and Composition Tool checks the return value of the installation
scripts used in bundles. A zero return code indicates success and the
synchronization process can proceed.
Symptoms
Virtual image synchronization fails with the error: Unable to initiate add of
execution bundle to VM.
Causes
The script used to install software in a bundle does not return a zero value.
Resolving the problem
Make sure that the scripts that you are using to install the software return a zero
value to indicate successful installation. A value greater than zero indicates a
failure and your virtual image cannot be synchronized. The installation script
checks for error conditions relevant to the installation of the bundle. For errors that
might compromise the bundle installation, an exit code greater than zero must be
returned, indicating failure. If a script returns no exit code explicitly, the exit code
of the last command of the script is implicitly returned. Make sure that the bundle
installation script can handle parameters passed in the following format:
scriptname -parameter1 <parameter1 value> -parameter2 <parameter2 value>
A sample installation script is as follows:
#!/bin/sh
#
# Licensed Materials - Property of IBM
# (C) Copyright IBM Corp. 2011
# All Rights Reserved
Chapter 5. Managing virtual images 485
# US Government Users Restricted Rights -Use, duplication or
# disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
#
# ----------------------------------------------------------------
#
# Description:
# Sample install script for an ICON bundle
#
#
function usage ()
{
echo ""
echo " Usage :"
echo " installBundleSample.sh -parm1 \"parm1value\" -parm2 \"parm2value\""
echo ""
exit 1
}
echo "$0: === Starting Install of Bundle Sample === "
echo
echo "$0: Arguments are: $* "
echo
#Init
MY_PARM1="Default parm1 value"
MY_PARM2="Default parm2 value"
echo "$0: Parsing Arguments "
echo
#Read arguments
while [ $# -ne 0 ]
do
case $1 in
-parm1*)
MY_PARM1=$2
;;
-parm2*)
MY_PARM2=$2
;;
*)
;;
esac
shift 1
done
# Now perform the work and actually do the install stuff - check the return code
echo "$0: About to do the real work..."
echo parm1 is "$MY_PARM1" parm2 is "$MY_PARM2"
if [ $? -gt 0 ]; then
echo "$0: echo $MY_PARM1 $MY_PARM2 failed" >&2
exit 1
fi
# finish up and return zero to indicate everything went ok
# (non-zero return code signifies an error)
echo " "
echo "$0: Done."
exit 0
486 IBM SmartCloud Orchestrator 2.3: User's Guide
Virtual image synchronization fails and troubleshooting is not possible:
If the synchronization fails, it is difficult to troubleshoot the problem because the
deployed image and the bundles used for synchronization are removed.
Symptoms
The synchronization fails and it is difficult to perform problem determination
because the deployed image and the compressed package are removed. Problems
with the bundle installation scripts are difficult to troubleshoot.
Resolving the problem
Use the ICCT_DEBUG variable to troubleshoot the problem.
If this variable is not defined on your system, you can set it up by following these
steps:
1. If Image Construction and Composition Tool is started, stop it:
cd <install_dir>
./stop.sh
2. Define the ICCT_DEBUG variable:
export ICCT_DEBUG=true
3. Restart Image Construction and Composition Tool:
./start.sh
If later you no longer need the ICCT_DEBUG variable, you can disable it:
cd <install_dir>
./stop.sh
export ICCT_DEBUG=
./start.sh
Windows image synchronization fails:
Synchronization of a Windows image fails.
Symptoms
Windows image synchronization to the virtual machine can fail if the /etc/hosts
file, required by the RXA protocol, in the Image Construction and Composition
Tool server configuration is not configured correctly.
Resolving the problem
In addition to the localhost entry, the machine where the Image Construction and
Composition Tool is installed must contain an entry with the Image Construction
and Composition Tool server IP and the related host name and fully qualified host
name, for example:
9.168.12.202 nc12202 nc12202.it.ibm.com
Chapter 5. Managing virtual images 487
Synchronization fails on a Linux operating system:
Synchronization of a virtual image fails on a Linux operating system.
Symptoms
The virtual image does not synchronize on Linux.
Causes
In a Linux operating system, during synchronization, the Image Construction and
Composition Tool copies the bundles files to the /tmp directory.
Resolving the problem
Ensure that there is enough space in the /tmp directory. For the enablement
bundle, the space in the /tmp directory must be 15 MB. You can calculate the total
space needed in the /tmp directory by adding the bundles size that must be
installed in the base image. Ensure that the Linux images allows execution under
/tmp for the activation engine to be installed.
Image management
The following topics cover the import, registration, deployment, and extension of
images in SmartCloud Orchestrator.
Note: SmartCloud Orchestrator supports virtual images that contains the
scp-cloud-init script and the Activation Engine. SmartCloud Orchestrator also
supports virtual images that run on VMware, if the images contain the Activation
Engine and the VMware tools are installed. Use the Image Construction and
Composition Tool to create images that are supported by SmartCloud Orchestrator.
Creating new images or using existing images
These topics describe how you can create new images or use existing images on
KVM or VMware.
Creating new AIX or Linux images or using existing ones
These topics describe how you create new Linux images or use existing AIX or
Linux images on KVM or VMware.
Prerequisites for KVM or VMware images:
Check the prerequisites for creating new KVM or VMware images or use KVM or
VMware existing images on Linux.
Note:
v The image must be created in the hypervisor. This topic only describes the
settings that needs to be applied to the image to be compatible with SmartCloud
Orchestrator.
v After you create the image, you must extend it by using the Image Construction
and Composition Tool. For more information, see Extending images on page
505.
v The parted RPM is an image prerequisite to use the Disk add-on capability.
v Be sure that Python 2.4, or later, and libxml2-python are installed on the image.
488 IBM SmartCloud Orchestrator 2.3: User's Guide
For Red Hat Enterprise Linux (RHEL) and Community Enterprise Operating
System (CentOS)
v Edit /etc/hosts to add the following lines:
#: vi /etc/hosts
# Do not remove the following line, or various programs
# that require network functionality will fail.
127.0.0.1 localhost.localdomain localhost
v Edit /etc/sysconfig/network to set the following value:
#: vi /etc/sysconfig/network
NETWORKING=yes
Note: All the other lines in the file must be commented out or deleted.
v Edit /etc/sysconfig/network-scripts/ifcfg-eth0 to set the following values:
#: vi /etc/sysconfig/network-scripts/ifcfg-eth0
# Intel Corporation 82562GT 10/100 Network Connection
DEVICE=eth0
BOOTPROTO=dhcp
ONBOOT=yes
TYPE=Ethernet
PERSISTENT_DHCLIENT=1
Note: Comment out or delete the line starting with HWADDR, if existing.
v Edit /etc/rc.local to add modprobe acpiphp as follows:
#: vi /etc/rc.local
#!/bin/sh
#
# This script will be executed *after* all the other init scripts.
# You can put your own initialization material here if you do not
# want to do the full Sys V style init.
modprobe acpiphp
touch /var/lock/subsys/local
v Edit /etc/udev/rules.d/70-persistent-net.rules and remove any lines that are
associated with one of the NICs (that is, eth0, eth1, and so forth). For example,
you must remove this line because it configures eth0:
SUBSYSTEM=="net", , ACTION=="add", DRIVERS=="?*", \
ATTR{address}="00:00:29:77:5a:ee", ATTR{type}=="1", \
KERNEL=-"eth*", NAME="eth0"
v Remove /lib/udev/write_net_rules as follows:
#: mv /lib/udev/write_net_rules /lib/udev/write_net_rules.bak
v Be sure that the following directories exist in the image:
/etc/sysconfig/networking/profiles/default/
/etc/sysconfig/networking/devices/
Tip: When you create a RHEL KVM image, be sure to remove the splash image
and rhgb from the /boot/grub/menu.lst file.
See the following example of the menu.1st file:
default=0
timeout=1
splashimage=(hd0,0)/boot/grub/splash.xpm.gz
hiddenmenu
title Red Hat Enterprise Linux Server (2.6.32-220.7.1.el6.x86_64)
root (hd0,0)
kernel /boot/vmlinuz-2.6.32-220.7.1.el6.x86_64 ro root=UUID=f77150a6-7cb9-4a0e-be81-1eaf2f3b34f2
rd_NO_LUKS rd_NO_LVM rd_NO_MD rd_NO_DM LANG=en_US.UTF-8 SYSFONT=latarcyrheb-sun16 KEYBOARDTYPE=pc
Chapter 5. Managing virtual images 489
KEYTABLE=us crashkernel=auto rhgb quiet acpi=force
initrd /boot/initramfs-2.6.32-220.7.1.el6.x86_64.img
title Red Hat Enterprise Linux Server (2.6.32-220.4.2.el6.x86_64)
For SLES 11
v In the /etc directory, ensure the HOSTNAME file is not empty.
v In the /lib/udev/rules.d directory, move the 75-persistent-net-
generator.rules file to 75-persistent-net-generator.rules.bak.
v Remove /lib/udev/write_net_rules as follows:
#: mv /lib/udev/write_net_rules /lib/udev/write_net_rules.bak
v In the /etc/init.d directory, create a file called loadmodel with the following
content:
modprobe acpiphp
v In the /etc/init.d directory, run the following commands:
#: chmod 755 loadmodel
#: chkconfig --add loadmodel
#: chkconfig loadmodel on
v After implementing these settings, reboot and then verify the settings by
running lsmod|grep acpiphp.
Creating new images or using existing images on KVM:
There are several pre-built images for OpenStack available from various sources.
You can download such images and use them to get familiar with OpenStack. You
can refer to http://docs.openstack.org/grizzly/openstack-compute/admin/
content/starting-images.html for details on using such images.
For any production deployment, you might like to have the ability to bundle
custom images with a custom set of applications or configuration. This topic
guides you through the process of creating Linux images of Debian and RedHat
based distributions from scratch.
There are some minor differences in the way you bundle a Linux image, based on
the distribution. Ubuntu makes it very easy by providing a cloud-init package,
which can be used to take care of the instance configuration at the time of launch.
cloud-init handles importing ssh keys for password-less login, setting hostname
and so forth. The instance acquires the instance specific configuration from
Nova-compute by connecting to a meta data interface running on 169.254.169.254.
While creating the image of a distribution that does not have cloud-init or an
equivalent package, you might need to take care of importing the keys, and so
forth, by running a set of commands at boot time from rc.local.
The process used for Ubuntu and Fedora is largely the same with a few minor
differences, which are explained in this topic.
In both cases, it is assumed that you have a working KVM installation to use for
creating the images. We are using the machine called client1 as explained in the
chapter Installing" for this purpose.
The approach explained in this topic gives you disk images that represent a disk
without any partitions. Nova-compute can resize these disks ( including resizing
the file system) based on the instance type chosen at the time of launching the
instance. These images cannot have a bootable flag and hence it is mandatory to
490 IBM SmartCloud Orchestrator 2.3: User's Guide
associate kernel and ramdisk images. Kernel and ramdisk images must be used by
nova-compute at the time of launching the instance.
However, we have also added a small section towards the end of the chapter about
creating bootable images with multiple partitions that can be used by nova to
launch an instance without the need for kernel and ramdisk images. Note that
disks cannot be re-sized if they are created using multiple partitions.
Kernel and Initrd for OpenStack
Copy the kernel and the initrd image from /mnt/boot to the user home directory.
These images will be used later for creating and uploading a complete virtual
image to OpenStack:
sudo cp /mnt/boot/vmlinuz-2.6.38-7-server /home/localadmin
sudo cp /mnt/boot/initrd.img-2.6.38-7-server /home/localadmin
Unmount the Loop partition:
sudo umount /mnt
Change the filesystem label of serverfinal.img to uec-rootfs:
sudo tune2fs -L uec-rootfs serverfinal.img
Now we have all the components of the image ready to be uploaded to the
OpenStack imaging server.
Registering with OpenStack
The last step is to upload the images to the OpenStack image service. The files that
must be uploaded for the above sample setup of Ubuntu are: vmlinuz-2.6.38-7-
server, initrd.img-2.6.38-7-server, serverfinal.img. Run the following
command:
uec-publish-image -t image --kernel-file vmlinuz-2.6.38-7-server
--ramdisk-file initrd.img-2.6.38-7-server amd64 serverfinal.img bucket1
For Fedora, the process is similar. Make sure that you use the right kernel and
initrd files extracted above.
The uec-publish-image command returns the prompt back immediately. However,
the upload process takes some time and the images are only usable only after the
process is complete. You can keep checking the status using the command nova
image-list as mentioned in the following sections.
Bootable Images
You can register bootable disk images without associating kernel and ramdisk
images. When you do not want the flexibility of using the same disk image with
different kernel and ramdisk images, you can go for bootable disk images. This
greatly simplifies the process of bundling and registering the images. However, the
caveats mentioned in the introduction to this chapter apply. Note that the
following instructions use server.img and you can skip all the cumbersome steps
related to extracting the single ext4 partition:
glance image-create --name="My Server" --is-public=true --container-format=ovf
--disk-format=raw < server.img
Chapter 5. Managing virtual images 491
Image Listing
The status of the images that have been uploaded can be viewed by using the
nova image-list command. The output should like this:
nova image-list
+----+---------------------------------------------+--------+
| ID | Name | Status |
+----+---------------------------------------------+--------+
| 6 | ttylinux-uec-amd64-12.1_2.6.35-22_1-vmlinuz | ACTIVE |
| 7 | ttylinux-uec-amd64-12.1_2.6.35-22_1-initrd | ACTIVE |
| 8 | ttylinux-uec-amd64-12.1_2.6.35-22_1.img | ACTIVE |
+----+---------------------------------------------+--------+
Creating new images or using existing images on VMware:
Follow this procedure to create an image or use an existing image that can be
deployed as a VMware guest of any operating system family.
To create an image for VMware, you must use VMware vCenter or vSphere Client
to connect to the ESXi node of VMware.
You must install the VMware tools.
Images must have only one network interface. Additional network interfaces can
be defined at deployment time.
Important: Virtual machines that were imported from OVF/OVA directly in
vCenter have the vApp flag automatically enabled. You must disable the vApp flag
before converting such a virtual machine to a template. To disable the flag, go to
Edit Settings > Options > vApp Options.
Creating new images or using existing images on VMControl:
Follow this procedure to create an image or use an existing image that can be
deployed as a VMControl guest of any operating system family.
Note: The image imported or created in VMControl must have the VMControl
Activation Engine. For more information, see Installing the VMControl activation
engine on AIX and Linux.
Note: PowerVM images with multiple NICs cannot be extended by using Image
Construction and Composition Tool. To extend an image with multiple NICs, you
must clone it and modify the related OVF file by removing all the sections related
to the additional NICs.
To import a new Linux or AIX image, use the IBM Systems Director VMControl
user interface, as follows:
1. Open the VMControl user interface at the following URL:
https://<vmc_ip>:8422/ibm/console
2. In the navigation area, click System Configuration > VMControl to open the
VMControl notebook.
3. In the Virtual Appliances tab, click Import to open the Import wizard.
a. On the Source page, specify the name and location of the OVA file that
contains the package to be imported. Click Next.
492 IBM SmartCloud Orchestrator 2.3: User's Guide
b. On the Digital Signature page, select the Import without digital signature
check box. Click Next.
c. On the Name page, review the text in the Name and Description fields, and
update if necessary. To add search tags, enter the tags in the Search tags
field. Click Next.
d. On the Repository page, select the image repository where you want to
store the imported image. You must specify a repository that matches the
disk file type in the image. For example:
v If the disk-file-name extension is .mksysb, load the image into a Network
Installation Management (NIM) server repository.
v If the disk-file-name extension is .raw, load the image into a Storage
Copy Services (SCS) storage pool repository.
Tip: To determine the disk file type, open the OVA file to find the file name
extension of the disk file. The disk file is usually the largest file in the OVA
file.
Click Next.
e. On the Version Control page, specify the version information for the new
image. You can create a new version tree with the new image as root, or
you can select an existing image to be the parent version of the new image.
Click Next.
f. On the Summary page, review the details for the new image. To change any
detail, click Back until you display the required page, and make your
changes. When the details on the Summary page are correct, click Finish to
import the image package and create the image.
4. Run the nova-remove-ovf-limits command on the Region Server for
VMControl management, to remove the limit fields from the image definition.
These limit fields, which are defined in the OVF file associated with the image,
can greatly restrict the amount of CPU and memory that is used when you
deploy the image as a virtual machine. Some images, especially IBM
PureApplication images, are almost unusable with traditional OpenStack flavor
definitions, because of these limit fields.
Tip: You should run the nova-remove-ovf-limits command in the following
circumstances:
v After the original connection to VMControl by SmartCloud Orchestrator
v Each time you use the IBM Systems Director VMControl user interface to
import a new image, as described in this topic.
The syntax of the nova-remove-ovf-limits command is as follows:
/opt/ibm/openstack/iaas/smartcloud/bin/nova-remove-ovf-limits [--os-region-name <region-name>]
<cloud-name>
--os-region-name <region-name>
The name of the OpenStack region. This argument is optional. If used,
this argument must be the first argument in the command.
<cloud-name>
The name of the cloud. To list all clouds, run the nova-cloud-show
command.
Example 1: No errors returned
nova-remove-ovf-limits --os-region-name RegionOne vmcontrol
{"id":"842e7a8e-18de-4e34-ae9f-40a50a41c9c3"}
Example 2: Errors returned
Chapter 5. Managing virtual images 493
nova-remove-ovf-limits --os-region-name RegionOne vmcontrol
{"message":"COPIML606E Additional details about the failure can be found in the
Virtual Image Library log files.",
"failedList":"19a29982-519a-4446-bd8c-742530d5cf1b::capture_icct_test9,
27008847-39f5-4560-b1f7-c79876535f3f::IBM AIX-Luisa,
2c4f38bf-55bd-4cc1-842a-52ff74888d65::pRhel64Image-capture,
3d488db1-a147-4432-956d-5c27b16bb9a6::pRhel64Image-Luisa1Nic,
5925d273-cbf4-487b-972a-e8cb6ef3e07e::WebSphere Application Server 8.5.0.2 64-bit AIX 6 (PowerVM),
5ab09eaf-2532-42db-9961-f661a9eca4ce::IBM AIX,
89f17cf6-b02f-4259-80d1-ead5e5e390e3::rhel64-running-cap,
a2458f6b-9556-4548-912b-6020a4fab1dc::WebSphere Application Server 8.5.0.2 64-bit AIX 7 (PowerVM),
a6675669-b3cf-4b63-8a6c-7e99d3d9f61e::pRhel64Image-test1,
bdeb2883-5d74-4164-8bc2-71ea83961efb::pRhel64Image-synch,
d25f7102-8c43-4d3f-b815-78e992b3d10e::pRhel64Image,
f1a25cbb-2d28-469a-8016-d5e80f5b38e0::IBM AIX,
f3307131-3fd3-422e-a5b8-e1dbef45629e::pRhel64Image",
"id":"842e7a8e-18de-4e34-ae9f-40a50a41c9c3"}
5. You can now deploy the new image into your environment.
Creating new Windows images or using existing ones
These topics describe how to create a new Windows image or to use an existing
Windows image on KVM or VMware.
Prerequisites for KVM or VMware images:
This topic describes the prerequisites for creating new Windows images or use
existing Windows images on KVM or VMware.
After the installation is complete, boot the machine and install any additional
applications you need and make any configuration changes you need to make.
Note: For a VMware image, ensure that the Windows image virtual machine has
network adapter type E1000. After you have created the image, you must extend it
using the Image Construction and Composition Tool. To do so, refer to the topic
Extending images on page 505.
Windows targets
v Windows 7 (64-bit)
Windows firewall needs to be configured to allow incoming ICMP and RDP
connections. Make sure that RDP is enabled and not blocked by a firewall to
allow the connection to the running instances of Windows. For ICMP, the
predefined rule in the Windows firewall is File and Printer Sharing (Echo
Request - ICMPv4-In). Open the rule and make sure that:
In the Advanced tab, all the profiles (Domain, Private, and Public) to which
this rule applies are checked.
In the Scope tab, in the Local IP address and Remote IP address sections,
Any IP address is checked.
Port 445 must not be blocked by a firewall. The predefined rule in the Windows
firewall for this port is Netlogon Service (NP-In).
For OpenStack, to allow incoming RDP connections, make sure that port 3389 is
not blocked by a firewall.
On Windows 7, the default startup type for the Remote Registry service is
manual. The Remote Registry service must be running to enable RXA.
By default the administrator account in not enabled in a Windows 7 image, so it
must not be used to run an Image Construction and Composition Tool
synchronization or to deploy a VM created in SmartCloud Orchestrator.
To check if the Remote Registry service is enabled and started:
494 IBM SmartCloud Orchestrator 2.3: User's Guide
1. Click Start, click Run, type services.msc, and press ENTER.
2. When Microsoft Management Console starts, in the console pane, ensure that
the Remote Registry service status is started. If not, right-click Remote
Registry and click Start. To avoid problems with the manual startup, you
might want to set the Remote Registry service startup type to automatic.
If you want to automatically start the service after the server boot:
1. Right-click Remote Registry and select Properties.
2. In Startup type, choose Automatic.
3. Click Apply and OK.
When the system starts up, Remote Registry automatically starts.
If you are a member of a local administrators group and you use a local user
account, complete the following steps to perform administrative tasks on the
target machine:
1. Turn off the User Account Control to Never Notify.
2. Disable User Account Control when you administer a workstation with a
Security Account Manager local user account. If you do not disable this
option, you do not connect as a full administrator and cannot perform
administrative tasks. To disable User Account Control perform the following
steps:
a. Click Start, click Run, type regedit, and press ENTER.
b. Locate and then click the following registry subkey:
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\
CurrentVersion\Policies\System.
c. If the LocalAccountTokenFilterPolicy registry entry does not exist,
complete the following steps:
1) On the Edit menu, point to New, and click DWORD(32-bit) VALUE.
2) Type LocalAccountTokenFilterPolicy and press ENTER.
3) Right-click LocalAccountTokenFilterPolicy, and click Modify.
4) In the Value data field, type 1 and click OK.
5) Restart the computer.
Alternatively, you can modify the registry entry manually by typing the
following command line:
cmd /c reg add HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\
system /v LocalAccountTokenFilterPolicy /t REG_DWORD /d 1 /f
Ensure that Enable NetBIOS over TCP/IP is selected in the Control Panel
settings for the network connections properties of the computer. In the Control
Panel, go to Network and Internet > Network and Sharing Center >
<your-network-connection> > Properties > Internet Protocol (TCP/IP) >
Properties > Advanced > WINS > Enable NetBIOS over TCP/IP.
v Windows Server 2008 R2 (64-bit)
Windows firewall needs to be configured to allow incoming ICMP and RDP
connections. Make sure that RDP is enabled and not blocked by a firewall to
allow the connection to the running instances of Windows. For ICMP, the
predefined rule in the Windows firewall is File and Printer Sharing (Echo
Request - ICMPv4-In). Open the rule and make sure that:
In the Advanced tab, all the profiles (Domain, Private, and Public) to which
this rule applies are checked.
In the Scope tab, in the Local IP address and Remote IP address sections,
Any IP address is checked.
Chapter 5. Managing virtual images 495
Port 445 must not be blocked by a firewall. The predefined rule in the Windows
firewall for this port is Netlogon Service (NP-In).
For OpenStack, to allow incoming RDP connections, make sure that port 3389 is
not blocked by a firewall.
You might need to disable User Account Control if your account is not a domain
user account. If you have a domain user account, ensure that the local and the
target machine are both members of a Windows domain.
If you are a member of a local administrators group and you use a local user
account, complete the following steps to perform administrative tasks on the
target machine:
1. Disable User Account Control when you administer a workstation with a
Security Account Manager local user account. If you do not disable this
option, you do not connect as a full administrator and cannot perform
administrative tasks. To disable User Account Control perform the following
steps:
a. Click Start, click Run, type regedit, and press ENTER.
b. Locate and then click the following registry subkey:
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\
CurrentVersion\Policies\System.
c. If the LocalAccountTokenFilterPolicy registry entry does not exist,
complete the following steps:
1) On the Edit menu, point to New, and click DWORD Value.
2) Type LocalAccountTokenFilterPolicy and press ENTER.
3) Right-click LocalAccountTokenFilterPolicy, and click Modify.
4) In the Value data field, type 1 and click OK.
5) Restart the computer.
Alternatively, you can modify the registry entry manually by typing the
following command line:
cmd /c reg add HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\
system /v LocalAccountTokenFilterPolicy /t REG_DWORD /d 1 /f
Ensure that Enable NetBIOS over TCP/IP is selected in the Control Panel
settings for the network connections properties of the computer. In the Control
Panel, go to Network and Dial-Up Connections > Properties > Internet
Protocol (TCP/IP) > Advanced > WINS > Enable NetBIOS over TCP/IP.
v Windows Server 2012 (64-bit)
Windows firewall needs to be configured to allow incoming ICMP and RDP
connections. Make sure that RDP is enabled and not blocked by a firewall to
allow the connection to the running instances of Windows. For ICMP, the
predefined rule in the Windows firewall is File and Printer Sharing (Echo
Request - ICMPv4-In). Open the rule and make sure that:
In the Advanced tab, all the profiles (Domain, Private, and Public) to which
this rule applies are checked.
In the Scope tab, in the Local IP address and Remote IP address sections,
Any IP address is checked.
Port 445 must not be blocked by a firewall. The predefined rule in the Windows
firewall for this port is Netlogon Service (NP-In).
For OpenStack, to allow incoming RDP connections, make sure that port 3389 is
not blocked by a firewall.
496 IBM SmartCloud Orchestrator 2.3: User's Guide
You might need to disable User Account Control if your account is not a domain
user account. If you have a domain user account, ensure that the local and the
target machine are both members of a Windows domain.
If you are a member of a local administrators group and you use a local user
account, complete the following steps to perform administrative tasks on the
target machine:
1. Disable User Account Control when you administer a workstation with a
Security Account Manager local user account. If you do not disable this
option, you do not connect as a full administrator and cannot perform
administrative tasks. To disable User Account Control perform the following
steps:
a. Click Start, click Run, type regedit, and press ENTER.
b. Locate and then click the following registry subkey:
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\
CurrentVersion\Policies\System.
c. If the LocalAccountTokenFilterPolicy registry entry does not exist,
complete the following steps:
1) On the Edit menu, point to New, and click DWORD Value.
2) Type LocalAccountTokenFilterPolicy and press ENTER.
3) Right-click LocalAccountTokenFilterPolicy, and click Modify.
4) In the Value data field, type 1 and click OK.
5) Restart the computer.
Alternatively, you can modify the registry entry manually by typing the
following command line:
cmd /c reg add HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\
system /v LocalAccountTokenFilterPolicy /t REG_DWORD /d 1 /f
Ensure that Enable NetBIOS over TCP/IP is selected in the Control Panel
settings for the network connections properties of the computer. In the Control
Panel, go to Network and Dial-Up Connections > Properties > Internet
Protocol (TCP/IP) > Advanced > WINS > Enable NetBIOS over TCP/IP.
Creating new images or using existing images on KVM:
This topic describes how to create a new Windows image or to use an existing
Windows image on KVM.
The first step is to create a raw image. This represents, on the Region Server or on
any machine with KVM installed, the main HDD of the virtual machine, so make
sure to give it as much space as you need:
qemu-img create -f raw windowsserver.img 20G
OpenStack presents the disk using a VIRTIO interface while launching the instance.
Therefore the operating system needs to have drivers for VIRTIO. By default, the
Windows Server 2008 ISO does not have drivers for VIRTIO. So you must
download a virtual floppy drive containing the VIRTIO drivers from the following
location: http://alt.fedoraproject.org/pub/alt/virtio-win/latest/images/bin/ and
attach it during the installation.
Start the installation by running:
sudo kvm -m 2048 -cdrom win2k8_dvd.iso -drive file=windowsserver.img,if=virtio
-drive file=virtio-win-0.1-22.iso,index=3,medie=cdrom -net nic,model=virtio
-net user -nographic -vnc :0
Chapter 5. Managing virtual images 497
When the installation prompts you to choose a hard disk device, you will not see
any devices available. Click Load drivers at the bottom left and load the drivers
from A:\i386\Win2008.
Shutdown the virtual machine and upload the image to OpenStack:
glance image-create --name="My WinServer" --is-public=true --container-format=ovf
--disk-format=raw < windowsserver.img
Creating new images or using existing images on VMware:
Follow this procedure to create an image or use an existing image that can be
deployed as a VMware guest of any operating system family.
To create an image for VMware, you must use VMware vCenter or vSphere Client
to connect to the ESXi node of VMware.
You must install the VMware tools.
Images must have only one network interface. Additional network interfaces can
be defined at deployment time.
Important: Virtual machines that were imported from OVF/OVA directly in
vCenter have the vApp flag automatically enabled. You must disable the vApp flag
before converting such a virtual machine to a template. To disable the flag, go to
Edit Settings > Options > vApp Options.
Importing images
This topic describes how to import Open Virtualization Archive (OVA) images in
the system.
498 IBM SmartCloud Orchestrator 2.3: User's Guide
About this task
Procedure
1. The user wants to import an OVA file in SmartCloud Orchestrator.
2. The user opens the SmartCloud Orchestrator Virtual Images view in the
SmartCloud Orchestrator UI and open the import dialog (refer to Importing a
virtual image to the catalog on page 289). The system processes the import
request, uploading the OVA file into the SmartCloud Orchestrator server. The
image metadata is stored locally in SmartCloud Orchestrator before the image
is imported into Virtual Image Library.
3. The imported OVA image is sent to Virtual Image Library to be stored in the
Reference repository. For an overview about repositories, refer to Virtual
Image Library basics on page 296. Virtual Image Library always keeps all the
metadata locally and returns to SmartCloud Orchestrator the reference image
UUID, which is used later at deployment time.
4. The Virtual Image library administrator selects the imported image and then
checks the image out (refer to Copying an image from the reference
repository on page 322).
Image metadata
Image disk
Legend
Disk Adapter
Virtual Image
Library
Connector
Glance
OpenStack
Nova
import
Check out image
Image
database
Reference
repository
11
33
Store metadata 22
55
laaS gateway
Workload Deployer
OVA
Scalable Web
Infrastructure
44 Select target repository
and checkout image
Import image in Virtual Image
Library reference repository
vCenter
Database
Chapter 5. Managing virtual images 499
5. The image is copied into the target operational repository.
Registering images
This topic describes how linked images are managed when it comes to deployment
and metadata handling.
About this task
These are the assumptions:
v Remote vCenter and VMControl are mapped to availability zones.
v The images coming from either Remote vCenter or VM Control are seen as part
of the OpenStack instance that contains those remote hypervisor managers.
v The linked images can be used in the following deployment use cases:
Virtual system patterns.
Virtual applications.
Image
database
Reference
repository
Database
laaS gateway
Image metadata
Image disk
Legend
Disk Adapter
Virtual Image
Library
Connector
Glance
OpenStack
Nova
Get list of images
Register images
Workload Deployer
11
Query image list 22
33
Query image metadata 3.1 3.1
Scalable Web
Infrastructure
vCenter
500 IBM SmartCloud Orchestrator 2.3: User's Guide
Procedure
1. The user wants to register one or more images into SmartCloud Orchestrator to
use them in patterns. The user opens the Virtual Images view in the
SmartCloud Orchestrator user interface and opens the register dialog (refer to
Registering a virtual image on page 290). The dialog shows how to register
images, filtered by OpenStack region.
2. The system queries the Virtual Image Library service to get the list of images
that match the selected scope. The returned list must contain at least the image
identifier, the name, the OS and the OS version, to allow the easy identification
of the image to register.
3. If the user wants to use the same OVA file to register multiple images in
different regions, the user maps the new image to an image that is already
registered. For more information about image mapping, see Registering a
virtual image on page 290.
4. The user selects one or more of the available images for the selected region.
This starts the image registration into SmartCloud Orchestrator. The registration
of a remote image also creates the metadata in SmartCloud Orchestrator,
querying Virtual Image Library for them. Virtual Image Library returns the
Open Virtualization Format (OVF) associated to the images (it is generated if
not stored in Virtual Image Library). The image native UUID returned to
SmartCloud Orchestrator is the Glance image UUID.
Deploying images
The following topics describe the deployment of images through patterns.
Deploying an image through a pattern in OpenStack
This topic describes how to deploy an image using a pattern in native OpenStack.
Chapter 5. Managing virtual images 501
About this task
Procedure
1. The user opens the virtual system pattern catalog and creates a new pattern
(refer to Creating a virtual system pattern on page 519).
2. The user selects the image to be included in the pattern.
3. The image displayed in the list is taken from the local Workload Deployer
repository of metadata, containing all the details to define which parts are
exposed by the image. These are of all the images that have been successfully
imported and registered to SmartCloud Orchestrator.
4. For the selected image, the system queries the Virtual Image Library service
exposed through the IAAS gateway to get the image capabilities. This allows
laaS gateway
OVA is imported in Glance
and a new image is created
as ISO file, to store the
additional metadata
(parts, topology...)
Disk Adapter
Virtual Image
Library
Connector
Glance
Image1
OpenStack
Nova
Create a pattern
Select image(s)
Configure pattern
Deploy pattern
11
22
Identify image capabilities 33
55
66
Query image
capabilities
Query image UUID
44
6.1 6.1
Get back from Virtual
Image Library the
Glance image UUID
to use for deployment
6.1 6.1
Call Nova boot 6.2 6.2
Image
database
Reference
repository
ISO
Scalable Web
Infrastructure
Workload Deployer
Image metadata
Image disk
Legend
vCenter
Database
502 IBM SmartCloud Orchestrator 2.3: User's Guide
managing the kind of configuration that can be done on the image in terms of
add-on and script package execution, as well as in terms of conditioning the
steps.
5. The user can configure the pattern using the pattern editor, depending on the
image capabilities returned by Virtual Image Library (refer to Editing a virtual
system pattern on page 521). This step allows to associate add-on scripts to
the image, using the image capabilities.
6. The user can deploy the pattern and, in case, customize any OVF parameters
associated to the selected image (refer to Deploying a virtual system pattern
on page 547). The pattern deployment triggers additional handshaking with
Virtual Image Library to get the UUID of the image. In points 6.1 and 6.2,
Workload Deployer calls the OpenStack Nova API to deploy the virtual
machine.
Deploying an image through a pattern in vCenter or VMControl
This topic describes how to deploy an image through a pattern in vCenter or
VMControl.
Chapter 5. Managing virtual images 503
About this task
Note: The picture refers to a vCenter scenario. For VMControl the scenario is the
same if you replace vCenter with VMControl in the picture.
Follow the same steps described in Deploying an image through a pattern in
OpenStack on page 501.
laaS gateway
Image metadata
Image disk
Legend
Disk Adapter
Virtual Image
Library
Connector
Glance
OpenStack
Nova
Create a pattern
Select image(s)
Configure pattern
Deploy pattern
11
22
Identify image capabilities 33
55
66
Query image
capabilities
Query image UUID
44
6.1 6.1
Get back from Virtual
Image Library the
Glance image UUID
to use for deployment
6.1 6.1
Call Nova boot 6.2 6.2
Image
database
Reference
repository
Scalable Web
Infrastructure
Workload Deployer
ISO
vCenter
Database
Discover
and register
504 IBM SmartCloud Orchestrator 2.3: User's Guide
Extending images
The following topics describe the extension of images using the Image
Construction and Composition Tool.
About this task
Image Construction and Composition Tool interacts directly with the IAAS
gateway, without using the existing Workload Deployer cloud provider. This
allows to save effort to make the connection work, and to focus more on the IAAS
gateway connector.
Extending images in OpenStack
This topic describes how to extend an existing image in OpenStack with the Image
Construction and Composition Tool.
About this task
For this procedure there are some prerequisite steps, which refer to the import of
image metadata inside the Image Construction and Composition Tool. The first
three steps describe the process of importing images from the cloud to the Image
Construction and Composition Tool, while the subsequent steps describe the real
extension flow.
Chapter 5. Managing virtual images 505
Procedure
1. To import images in the Image Construction and Composition tool, the user
opens the import dialog (refer to Importing base images from Workload
Deployer). The system queries the Virtual Image Library service exposed
through the IaaS gateway to get the list of images. The list of images is
filtered by cloud group (region), and it contains only images that are
registered in Virtual Image Library, read-only and with Linux or Windows OS.
2. The user selects one or more images to import. This is the standard Image
Construction and Composition Tool flow that triggers the process to get
metadata about the selected images.
3. Image Construction and Composition Tool queries the Virtual Image Library
service exposed through the IaaS gateway to get details about the selected
images. At this point, Image Construction and Composition Tool creates
metadata inside its own repository. Details include location information like,
laaS gateway
Image metadata
Image disk
Extended image
metadata
Extended image
Legend
Disk Adapter
Virtual Image
Library
Connector
Glance
Image1
Image2
OpenStack
Import image
Query image metadata
Select image to extend
Add bundles
Start synchronization
Capture VM
Create VM
Update metadata
Workload Deployer
Update metadata
Image
database
22
33
44
55
66
88
77
99
9.1 9.1
Capture Image2 8.1 8.1
Create ISO image 9.2 9.2
Specify which cloud group
(i.e. availability zone inside
a region) to use. In this case
select an OpenStack region
Image Construction
and Composition Tool
11 Get image list
Nova vm1
vCenter
Database
506 IBM SmartCloud Orchestrator 2.3: User's Guide
region, project, availability zone, which must be persisted by Image
Construction and Composition Tool for later use.
4. Now that the images have been imported in Image Construction and
Composition Tool, the user can select which image to extend (refer to
Building virtual images on page 401). This is the standard Image
Construction and Composition Tool flow to create a new image representation
in its database.
5. The user selects one or more bundles from the local Image Construction and
Composition Tool catalog and modifies the new image. This is also standard
flow in the Image Construction and Composition Tool.
6. The user starts the synchronization, which interacts with the IaaS gateway to
trigger the deployment of a virtual machine in OpenStack, based on the
selected image that is being extended.
7. A new virtual machine is created in OpenStack. The region, project,
availability zone where the action is triggered depend on the selected image.
When the virtual machine is created, Image Construction and Composition
Tool connects to it and installs the required bundles.
8. The user captures the modified virtual machine into a new image. This is the
standard flow of Image Construction and Composition Tool driven through
the IaaS gateway and the OpenStack APIs.
9. The last step of the capturing process is to update the metadata of the new
image. This is done by creating a new OVF for the image (or by modifying
the existing OVF if the image had an associated OVF), and creating the related
parts files and topology files. This is done through the Virtual Image Library
APIs to manage metadata associated with an image.
10. Virtual Image Library creates a new ISO file into Glance to store additional
metadata files associated with the extended image.
Extending images in vCenter
This topic describe how to extend an existing image with the Image Construction
and Composition Tool, when the image is not a native OpenStack image but is
reference of an image in vCenter. The same applies if the image is in VMControl.
About this task
For this procedure there are some prerequisite steps, which refer to the import of
image metadata inside the Image Construction and Composition Tool. The first
three steps describe the process of importing images from the cloud to the Image
Construction and Composition Tool, while the subsequent steps describe the real
extension flow.
Chapter 5. Managing virtual images 507
Procedure
1. To import images in the Image Construction and Composition tool, the user
opens the import dialog (refer to Importing base images from Workload
Deployer). The system queries the Virtual Image Library service exposed
through the IaaS gateway to get the list of images. The list of images is
filtered by cloud group (region), and it contains only images that are
registered in Virtual Image Library, read-only and with Linux or Windows OS.
2. The user selects one or more images to import. This is the standard Image
Construction and Composition Tool flow that triggers the process to get
metadata about the selected images.
3. Image Construction and Composition Tool queries the Virtual Image Library
service exposed through the IaaS gateway to get details about the selected
images (refer to Building virtual images on page 401). At this point, Image
Construction and Composition Tool creates metadata inside its own repository.
508 IBM SmartCloud Orchestrator 2.3: User's Guide
Details include location information like, region, project, availability zone,
which must be persisted by Image Construction and Composition Tool for
later use.
4. Now that the images have been imported in Image Construction and
Composition Tool, select the image to extend. This is the standard Image
Construction and Composition Tool flow to create a new image representation
in its database.
5. The user selects one or more bundles from the local Image Construction and
Composition Tool catalog and modify the new image. This is also standard
flow in the Image Construction and Composition Tool.
6. The user starts the synchronization, which interacts with the IaaS gateway to
trigger the deployment of a virtual machine in OpenStack, based on the
selected image that is being extended.
7. Since the user selected a vCenter availability zone, the new virtual machine is
created in vCenter. When the virtual machine is created, Image Construction
and Composition Tool connect to it and installs the required bundles.
8. The user captures the modified virtual machine into a new image. This is the
standard flow of Image Construction and Composition Tool driven through
the IaaS gateway and the OpenStack APIs.
9. The last step of the capturing process is to update the metadata of the new
image. This is done by creating a new OVF for the image (or by modifying
the existing OVF if the image had an associated OVF), and creating the related
parts files and topology files. This is done through the Virtual Image Library
APIs to manage metadata associated with an image.
10. Virtual Image Library creates a new ISO file into Glance to store additional
metadata files associated with the extended image (point 9.2 in the picture).
What to do next
Note: After extending a VMware image, if you log on to the image in VMware
and then convert it back to template, when deploying the image in SmartCloud
Orchestrator the deployment might hang. For information about solving this
problem, see Deployment might hang on page 1103.
Image management on Power
This topic describes how images are managed on the Power hypervisor.
In the Power hypervisor, two images are maintained:
IBM HyperVisor Edition (HVE) OVA images
Use the following steps to use an IBM HVE OVA image:
1. Import OVA into Workload Deployer
2. Import OVA into VMControl and remove the limits. For more
information about this, see Creating new images or using existing
images on VMControl.
3. Map Workload Deployer Imported image (step 1) to VMControl
imported image (Step 2)
Customer images
Use the following steps to create a PowerVM image from an existing
Customer image:
1. Create the image into VMControl (skip if you already have a
VMControl Virtual Appliance) - you can create images or Virtual
Appliance (VA) in VMControl in different ways, you can start from an
Chapter 5. Managing virtual images 509
existing VMControl OVA, a media file, a mksysb, and so on.
Depending on the operating system and image repository that is used,
these virtual appliances must meet specific requirements on the
VMControl side. For more information, see the following topics:
v Requirements for AIX
VMControl NIM based image
v Requirements for AIX/Linux VMControl SCS based image
2. Import OVA into VMControl and remove the limits. For more
information about this, see Creating new images or using existing
images on VMControl.
3. Enable the VMControl Virtual Appliance so it can be used in
SmartCloud Orchestrator - Before one of the VMControl Virtual
Appliances, that are not IBM HVE OVA, can be used in SmartCloud
Orchestrator, you must register and extend these images by using the
Image Construction and Composition Tool. For more information see
the following topic:
v Working with virtual images on page 400
Image Construction and Composition Tool steps extend the base VSAE
agent that is installed at the VMControl level with extra features that
permit to customize the image when it is deployed.
4. Register the image in the SmartCloud Orchestrator UI - For information
about this task see the following topic:
v Registering a virtual image on page 290
Note: Virtual Image Library check-out and check-in operations do not apply to
Power images.
510 IBM SmartCloud Orchestrator 2.3: User's Guide
Chapter 6. Managing and deploying virtual patterns
You can perform a variety of tasks on virtual applications, virtual systems and
shared services.
Virtual pattern types
There are three types of virtual patterns: virtual systems, virtual applications, and
shared services.
Virtual systems are deployed from virtual system patterns. Those patterns consist
of parts which are virtual machines and scripts running on those virtual machines.
Virtual system
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, see Working with virtual system patterns.
Virtual application
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. For more information about virtual application
patterns, see Working with virtual applications on page 581.
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 754.
For more information about virtual pattern types, see Managing pattern types on
page 585.
Working with virtual system patterns
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, perform the following steps:
Procedure
1. Use one, or both, of the following options that SmartCloud Orchestrator
provides for working with virtual system patterns:
v Use the user interface, as described in Working with virtual system patterns
in the user interface on page 513.
Copyright IBM Corp. 2013, 2014 511
v Use the command-line interface, as described in Pattern command-line
interface reference on page 844.
2. Configure the advanced options. You can configure advanced options for the
virtual system patterns, as described in Configuring advanced options on
page 529.
Related tasks:
Working with virtual system patterns in the user interface on page 513
Virtual system patterns implement deployment topologies from one or more
virtual images and applications from the SmartCloud Orchestrator catalog.
Related reference:
Supported virtual system patterns
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.
Virtual system pattern editing views and parts on page 522
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.
Pattern command-line interface reference on page 844
You can work with the pattern and patterns objects on the SmartCloud
Orchestrator command-line interface.
Patterns REST API on page 997
You can use the representational state transfer (REST) application programming
interface (API) to manage patterns.
Supported virtual system patterns
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
(https://www-304.ibm.com/software/brandcatalog/puresystems/centre/
browse#rc=Company_IBM&page=1).
For example, you can download the following virtual system patterns:
v DB2 Enterprise Server Edition.
v IBM WebSphere Application Server Hypervisor Edition.
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 on page 516.
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 on page 517.
v Create a virtual system pattern.
512 IBM SmartCloud Orchestrator 2.3: User's Guide
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 on page 519.
Working with virtual system patterns in the user interface
Virtual system patterns implement deployment topologies from one or more
virtual images and applications from the SmartCloud 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 on page 512 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 SmartCloud 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 window is
provided in Virtual system pattern windows on page 552.
Procedure
1. From the menu, open the Virtual System Patterns window by clicking Images
& Patterns > Virtual System Patterns.
2. Determine the task to perform. You can perform the following tasks with the
SmartCloud 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 on page 514.
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 on page 521.
Configure advanced options.
You can edit and configure the advanced options for a virtual system
pattern, as described in Configuring advanced options on page 529.
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
read-only on page 546.
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 on page 547.
Chapter 6. Managing and deploying virtual patterns 513
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 on page 551.
Related tasks:
Using a predefined virtual system pattern on page 516
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 SmartCloud Orchestrator catalog. Virtual system patterns
provide a topology definition for repeatable deployment that can be shared.
Creating a virtual system pattern on page 519
You can create a virtual system pattern using the SmartCloud Orchestrator user
interface. Virtual system patterns are topology definitions for repeatable
deployment that can be shared.
Related reference:
Supported virtual system patterns on page 512
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.
Virtual system pattern editing views and parts on page 522
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.
Selecting a virtual system pattern
You can use a set of predefined virtual system patterns that is provided by IBM.
You can also clone an existing SmartCloud 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 on page 512 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 on
page 516 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 on page 517 for more information. See Editing a virtual system
pattern on page 521 for more information.
514 IBM SmartCloud Orchestrator 2.3: User's Guide
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 on page 519 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 on page 547 for more information.
Related tasks:
Using a predefined virtual system pattern on page 516
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 SmartCloud Orchestrator catalog. Virtual system patterns
provide a topology definition for repeatable deployment that can be shared.
Cloning an existing virtual system pattern on page 517
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.
Creating a virtual system pattern on page 519
You can create a virtual system pattern using the SmartCloud Orchestrator user
interface. Virtual system patterns are topology definitions for repeatable
deployment that can be shared.
Editing a virtual system pattern on page 521
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.
Configuring advanced options on page 529
When you have edited the topology of a virtual system pattern, you can configure
advanced function for the virtual system pattern.
Making virtual system patterns read-only on page 546
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 on page 547
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.
Related reference:
Supported virtual system patterns on page 512
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.
Virtual system pattern editing views and parts on page 522
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.
Chapter 6. Managing and deploying virtual patterns 515
Using a predefined virtual system pattern:
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 SmartCloud 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 SmartCloud Orchestrator to
determine which virtual system pattern best fits your needs. See Supported
virtual system patterns on page 512 for information about these virtual system
patterns.
About this task
You can use the virtual system patterns provided by SmartCloud 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 on page 547.
Results
The virtual system pattern is now running in the virtual system instance.
Related tasks:
Cloning an existing virtual system pattern on page 517
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.
Deploying a virtual system pattern on page 547
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 529
When you have edited the topology of a virtual system pattern, you can configure
advanced function for the virtual system pattern.
Related reference:
Supported virtual system patterns on page 512
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.
516 IBM SmartCloud Orchestrator 2.3: User's Guide
Cloning an existing virtual system pattern:
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 on page 512 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
Images & Patterns > Virtual Images. See Chapter 5, Managing virtual images,
on page 287 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.
Procedure
1. From the left panel Virtual System Patterns 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
window.
2. Clone the virtual system pattern. Click the clone icon on the upper right panel
of the Virtual System Patterns 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
Chapter 6. Managing and deploying virtual patterns 517
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 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 windows on page 552.
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
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 editing views and parts on page 522.
6. Edit the parts on the canvas. See Editing a virtual system pattern on page 521
for more information about editing functions you can perform on virtual
system patterns.
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 529.
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 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 read-only on page 546. You can
deploy the virtual system pattern to the cloud. For more information, see
Deploying a virtual system pattern on page 547.
Related tasks:
Chapter 5, Managing virtual images, on page 287
Virtual images provide the operating system and product binary files that are
required to create a virtual system instance.
518 IBM SmartCloud Orchestrator 2.3: User's Guide
Making virtual system patterns read-only on page 546
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 on page 547
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 529
When you have edited the topology of a virtual system pattern, you can configure
advanced function for the virtual system pattern.
Related reference:
Supported virtual system patterns on page 512
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.
Virtual system pattern editing views and parts on page 522
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.
Creating a virtual system pattern:
You can create a virtual system pattern using the SmartCloud 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 on page 512.
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 Systems
Patterns window, click add beside the Virtual System Patterns label 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.
Chapter 6. Managing and deploying virtual patterns 519
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 Systems Patterns 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 windows on page 552.
3. Edit the virtual system pattern. To change the virtual system pattern topology,
click edit on the upper right panel of the Virtual Systems Patterns 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 Remove script packages from the parts
v Configure properties for the parts
v Configure parameters for script packages that have them
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 editing views and parts on page 522.
4. Edit the parts on the canvas. See Editing a virtual system pattern on page 521
for more information about editing functions you can perform on virtual
system patterns.
5. 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 529.
6. Optional: Modify the default order in which the parts run at deployment. See
Ordering parts to run at deployment on page 526 for more information.
7. 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 read-only on page 546. You can
deploy the virtual system pattern to the cloud. For more information, see
Deploying a virtual system pattern on page 547.
Related tasks:
Making virtual system patterns read-only on page 546
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
520 IBM SmartCloud Orchestrator 2.3: User's Guide
consistent reuse in the cloud.
Deploying a virtual system pattern on page 547
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 529
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 editing views and parts on page 522
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.
Editing a virtual system pattern
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
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 window. Details about the virtual system pattern are
shown in the right panel of the Virtual System Patterns window.
2. From the top of the right panel of the Virtual System Patterns window, click the
edit icon The Virtual System Patterns 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.
Chapter 6. Managing and deploying virtual patterns 521
The editing canvas graphically shows the topology of the virtual system
pattern. See Virtual system pattern editing views and parts 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 529.
5. Optional: Configure the order in which the parts are to deploy. For more
information, see Ordering parts to run at deployment on page 526.
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 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 lock the virtual system pattern against future editing. For more
information, see Making virtual system patterns read-only on page 546. You can
deploy the virtual system pattern to the cloud. For more information, see
Deploying a virtual system pattern on page 547.
Related tasks:
Cloning an existing virtual system pattern on page 517
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.
Configuring advanced options on page 529
When you have edited the topology of a virtual system pattern, you can configure
advanced function for the virtual system pattern.
Related reference:
Supported virtual system patterns on page 512
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.
Virtual system pattern 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 window
When you select a virtual system pattern to edit in Virtual System Patterns
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 window. For more information about the predefined virtual system
patterns and what they provide, see Supported virtual system patterns on page
512.
522 IBM SmartCloud Orchestrator 2.3: User's Guide
The Pattern Editor window
Clicking the edit icon on the upper right panel of the Virtual System Patterns
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 window. The following
virtual image parts are examples of the parts available for IBM WebSphere
Application Server Hypervisor Edition images:
v Administrative agents
v Custom nodes
v Deployment manager
v IBM HTTP servers
v Job manager
v Stand-alone server
v 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 5, Managing virtual images, on
page 287.
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 527.
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 window. This list can contain script
packages associated with the virtual image and any that you have defined for use
with SmartCloud Orchestrator. For more information about script packages, see
Adding a script package on page 243 and Associating a script package with a
pattern on page 247. Script packages can then be added to the virtual image parts.
Add-ons
The following default add-ons are provided with SmartCloud 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
Chapter 6. Managing and deploying virtual patterns 523
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 RedHat 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.
Note: When using this add on for images to be deployed on VMware,
consider that SmartCloud Entry has a default configuration concerning the
maximum number of disks and their size. You can change the default
configuration, editing, on the system where SmartCloud Entry runs,
/root/.SCE/31/deployment.properties, modify com.ibm.cfs.vs.max.disks
and com.ibm.cfs.vs.max.disksize according to your needs and restart
SmartCloud Entry.
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: SmartCloud 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
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: When using this add on for images to be deployed on VMware,
consider that SmartCloud Entry has a default configuration concerning the
maximum number of disks and their size. You can change the default
configuration, editing, on the system where SmartCloud Entry runs,
/root/.SCE/31/deployment.properties, modify com.ibm.cfs.vs.max.disks
and com.ibm.cfs.vs.max.disksize according to your needs and restart
SmartCloud Entry.
Note: SmartCloud Orchestrator does not support the disk add-on function
for PowerVM with Shared Storage pool.
524 IBM SmartCloud Orchestrator 2.3: User's Guide
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 254. 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 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.
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
Chapter 6. Managing and deploying virtual patterns 525
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 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.
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 window.
2. From the upper right of the Virtual System Patterns window, click the edit icon.
The Pattern Editor window is opened for the selected virtual system pattern.
526 IBM SmartCloud Orchestrator 2.3: User's Guide
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 529
and Deploying a virtual system pattern on page 547.
Related tasks:
Cloning an existing virtual system pattern on page 517
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.
Configuring advanced options on page 529
When you have edited the topology of a virtual system pattern, you can configure
advanced function for the virtual system pattern.
Related reference:
Supported virtual system patterns on page 512
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.
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 6. Managing and deploying virtual patterns 527
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 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
window, click the Deploy icon. on the upper right of the Virtual
System Patterns 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:
528 IBM SmartCloud Orchestrator 2.3: 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.
Related tasks:
Configuring advanced options
When you have edited the topology of a virtual system pattern, you can configure
advanced function for the virtual system pattern.
Editing a virtual system pattern on page 521
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.
Related reference:
Supported virtual system patterns on page 512
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.
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.
Chapter 6. Managing and deploying virtual patterns 529
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 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.
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 on page 543.
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 on page 532.
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 536.
4. Save your changes. When you change the settings and click OK, your changes
are saved in place of the default values.
530 IBM SmartCloud Orchestrator 2.3: User's Guide
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 541.
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
545 for more information.
What to do next
You can perform the following tasks after configuring the advanced options for a
virtual system pattern:
Configure the parts
For more information about configuring the parts in your virtual system
pattern, see Configuring parts on page 527.
Make the virtual system pattern read only
For more information about locking the virtual system pattern against
future editing, see Making virtual system patterns read-only on page
546.
Deploy the virtual system pattern
For more information about deploying the virtual system pattern to a
cloud, see Deploying a virtual system pattern on page 547.
Related tasks:
Configuring advanced options on page 529
When you have edited the topology of a virtual system pattern, you can configure
advanced function for the virtual system pattern.
Configuring advanced options for cluster virtual system patterns on page 532
You can use the advanced virtual system patternconfiguration function as a
starting point in configuring the cluster virtual system pattern that defines your
cell.
Configuring advanced options for single server virtual system patterns on page
543
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.
Working with virtual system patterns in the user interface on page 513
Virtual system patterns implement deployment topologies from one or more
virtual images and applications from the SmartCloud Orchestrator catalog.
Related reference:
Virtual system pattern editing views and parts on page 522
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.
Pattern command-line interface reference on page 844
You can work with the pattern and patterns objects on the SmartCloud
Orchestrator command-line interface.
Patterns REST API on page 997
You can use the representational state transfer (REST) application programming
Chapter 6. Managing and deploying virtual patterns 531
interface (API) to manage patterns.
Configuring advanced options for cluster virtual system patterns:
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.
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 541.
Use the following options to configure messaging with SmartCloud
Orchestrator:
Standard messaging engine configuration
When configuring the standard Java Message Service (JMS),
SmartCloud Orchestrator provides the following function:
532 IBM SmartCloud Orchestrator 2.3: User's Guide
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 541 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.
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.
Chapter 6. Managing and deploying virtual patterns 533
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, SmartCloud 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.
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
534 IBM SmartCloud Orchestrator 2.3: User's Guide
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. SmartCloud 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 545.
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 SmartCloud Orchestrator
v Use both LTPA and BasicAuth for authentication (BasicAuth is needed for
stand-alone clients)
v Use an SSL-allowed policy for CSIv2
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
Chapter 6. Managing and deploying virtual patterns 535
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 541.
Related tasks:
Configuring advanced options on page 529
When you have edited the topology of a virtual system pattern, you can configure
advanced function for the virtual system pattern.
Configuring advanced messaging for databases on page 541
When you are configuring 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.
Deploying a virtual system pattern on page 547
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 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 529.
About this task
In addition to the basic advanced options described in Configuring advanced
options on page 529, 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.
536 IBM SmartCloud Orchestrator 2.3: User's Guide
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 DYNAMIC_CLUSTER_PREFIX
v NUMBER_OF_DYNAMIC_CLUSTERS
v MAXIMUM_INSTANCES_PER_NODE
v MAXIMUM_NODES
v MINIMUM_TOTAL_INSTANCES
v 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
540 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:
Chapter 6. Managing and deploying virtual patterns 537
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 SMTP_HOST_NAME
v SMTP_PORT
v SMTP_USERID
v SMTP_PASSWORD
v EMAIL_ADDRESSES_TO_NOTIFY
v 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
538 IBM SmartCloud Orchestrator 2.3: User's Guide
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 541.
Related tasks:
Configuring advanced options for cluster virtual system patterns on page 532
You can use the advanced virtual system patternconfiguration function as a
starting point in configuring the cluster virtual system pattern that defines your
cell.
Deploying a virtual system pattern on page 547
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.
Chapter 6. Managing and deploying virtual patterns 539
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 536.
v For optimal performance, ensure that your dynamic clusters are running in
supervised mode or automatic mode. It is not recommended to have elasticity
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.
540 IBM SmartCloud Orchestrator 2.3: User's Guide
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
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 are configuring 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 on
page 532.
Chapter 6. Managing and deploying virtual patterns 541
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 SmartCloud Orchestrator sample authentication alias. The sample
authentication alias can be used by the messaging engines for databases other
than Derby. If you use the SmartCloud Orchestrator messaging
recommendations and a database (like DB2 or Oracle, for example), 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
SmartCloud 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 properly start and use clustered messaging engines, a
database server is required. You can use the Derby database server shipped with
WebSphere Application Server. SmartCloud 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. SmartCloud Orchestrator provides this function for
messaging to minimize later configuration. To start Derby from the deployment
manager before starting the messaging cluster, you can 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.
Related tasks:
Making virtual system patterns read-only on page 546
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.
542 IBM SmartCloud Orchestrator 2.3: User's Guide
Configuring advanced options for cluster virtual system patterns on page 532
You can use the advanced virtual system patternconfiguration function as a
starting point in configuring the cluster virtual system pattern that defines your
cell.
Deploying a virtual system pattern on page 547
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 529
When you have edited the topology of a virtual system pattern, you can configure
advanced function for the virtual system pattern.
Configuring advanced options for single server virtual system patterns:
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
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. SmartCloud 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
Chapter 6. Managing and deploying virtual patterns 543
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 545.
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 SmartCloud 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
implemented session persistence for Derby on page 545.
Related tasks:
Configuring advanced options on page 529
When you have edited the topology of a virtual system pattern, you can configure
advanced function for the virtual system pattern.
Working with virtual system patterns in the user interface on page 513
Virtual system patterns implement deployment topologies from one or more
virtual images and applications from the SmartCloud Orchestrator catalog.
Related reference:
Virtual system pattern editing views and parts on page 522
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.
544 IBM SmartCloud Orchestrator 2.3: User's Guide
Pattern command-line interface reference on page 844
You can work with the pattern and patterns objects on the SmartCloud
Orchestrator command-line interface.
Patterns REST API on page 997
You can use the representational state transfer (REST) application programming
interface (API) to manage patterns.
Configuring database implemented session persistence for Derby:
Because SmartCloud 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.
Related tasks:
Cloning an existing virtual system pattern on page 517
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.
Configuring advanced options on page 529
When you have edited the topology of a virtual system pattern, you can configure
advanced function for the virtual system pattern.
Working with virtual system patterns on page 511
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.
Chapter 6. Managing and deploying virtual patterns 545
Working with virtual system patterns in the user interface on page 513
Virtual system patterns implement deployment topologies from one or more
virtual images and applications from the SmartCloud Orchestrator catalog.
Related reference:
Supported virtual system patterns on page 512
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.
Virtual system pattern editing views and parts on page 522
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.
Pattern command-line interface reference on page 844
You can work with the pattern and patterns objects on the SmartCloud
Orchestrator command-line interface.
Patterns REST API on page 997
You can use the representational state transfer (REST) application programming
interface (API) to manage patterns.
Making virtual system patterns 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.
Procedure
1. From the left panel of the Virtual System Patterns 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 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 window.
v If virtual system pattern editing is not complete, see the information in
Editing a virtual system pattern on page 521 and Configuring advanced
options on page 529.
546 IBM SmartCloud Orchestrator 2.3: User's Guide
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.
Related tasks:
Editing a virtual system pattern on page 521
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.
Configuring advanced options on page 529
When you have edited the topology of a virtual system pattern, you can configure
advanced function for the virtual system pattern.
Deploying a virtual system pattern
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.
Deploying a virtual system pattern
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 on
page 521 and Configuring advanced options on page 529 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 Modifying project quotas on page 86. To
modify quotas in the environment profile, refer to Creating an environment
profile on page 223.
About this task
This task describes deploying a virtual system pattern to run in the cloud group.
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 window.
Chapter 6. Managing and deploying virtual patterns 547
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 SmartCloud Orchestrator.
Note: SmartCloud 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 220.
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.
Run indefinitely
Runs this virtual system pattern continuously. Run indefinitely
is the default option.
548 IBM SmartCloud Orchestrator 2.3: User's Guide
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.
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
Chapter 6. Managing and deploying virtual patterns 549
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, refer to Creating new flavors in
OpenStack on page 560.
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 window on page 577.
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.
550 IBM SmartCloud Orchestrator 2.3: User's Guide
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 on page 562.
Related tasks:
Cloning an existing virtual system pattern on page 517
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.
Configuring advanced options on page 529
When you have edited the topology of a virtual system pattern, you can configure
advanced function for the virtual system pattern.
Related reference:
Supported virtual system patterns on page 512
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.
Deploying a pattern 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 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 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 on page 547.
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
You can delete any virtual system patterns you own using the SmartCloud
Orchestrator user interface.
Before you begin
You must be the owner of a virtual system pattern you want to delete.
Chapter 6. Managing and deploying virtual patterns 551
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 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 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.
v If you want to change the virtual system pattern instead of deleting it, see
the information in Editing a virtual system pattern on page 521 and
Configuring advanced options on page 529.
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 window and the virtual system pattern
has been deleted and is no longer shown in the list on the left panel.
Related concepts:
Virtual system pattern processing on page 559
When deploying a virtual system instance, that is a collection of virtual machines,
SmartCloud Orchestrator virtual system pattern processing follows a specific
startup sequence.
Related tasks:
Editing a virtual system pattern on page 521
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.
Configuring advanced options on page 529
When you have edited the topology of a virtual system pattern, you can configure
advanced function for the virtual system pattern.
Making virtual system patterns read-only on page 546
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.
Virtual system pattern windows
The Virtual System Patterns 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 window provides the following interactive panels:
Left panel
The left panel of the Virtual System Patterns window lists the virtual
552 IBM SmartCloud Orchestrator 2.3: User's Guide
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 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 window, see
Fields on the Virtual System Patterns window on page 554.
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 556.
Related tasks:
Cloning an existing virtual system pattern on page 517
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.
Working with virtual system patterns on page 511
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 reference:
Fields on the Virtual System Patterns window on page 554
The SmartCloud Orchestrator Virtual System Patterns window lists the virtual
system patterns you have configured and provides fields to view and work with
your topology. The Virtual System Patterns window graphically shows the parts,
scripts, and add-ons in your topology.
Fields on the Pattern Editor window on page 556
The SmartCloud 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.
Chapter 6. Managing and deploying virtual patterns 553
Fields on the Virtual System Patterns window:
The SmartCloud Orchestrator Virtual System Patterns window lists the virtual
system patterns you have configured and provides fields to view and work with
your topology. The Virtual System Patterns window graphically shows the parts,
scripts, and add-ons in your topology.
There are two interactive panels of the Virtual System Patterns 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 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 on page 519 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 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 on page 547 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 on page 521 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 on
page 517 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 read-only on page 546 for more
information.
Delete Deletes the virtual system pattern from SmartCloud Orchestrator. See
Deleting a virtual system pattern on page 551 for more information
about deleting virtual system patterns.
554 IBM SmartCloud Orchestrator 2.3: User's Guide
Fields on the right configuration panel
Selecting a virtual system pattern in the left panel of the Virtual System Patterns
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.
Topology for this pattern
Displays any warnings or errors. This section of the panel provides a
graphical representation of the topology.
Chapter 6. Managing and deploying virtual patterns 555
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.
Related tasks:
Cloning an existing virtual system pattern on page 517
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.
Working with virtual system patterns on page 511
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.
Fields on the Pattern Editor window:
The SmartCloud 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 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
556 IBM SmartCloud Orchestrator 2.3: User's Guide
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
SmartCloud 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.
For more information about script packages, see Adding a script package
on page 243 and Associating a script package with a pattern on page
247.
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 SmartCloud
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 258.
See Virtual system pattern editing views and parts on page 522 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.
Chapter 6. Managing and deploying virtual patterns 557
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 SmartCloud
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.
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 529.
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 IBM HTTP Server
v Job manager
v Stand-alone server
v 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)
558 IBM SmartCloud Orchestrator 2.3: User's Guide
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
Related tasks:
Configuring advanced options on page 529
When you have edited the topology of a virtual system pattern, you can configure
advanced function for the virtual system pattern.
Cloning an existing virtual system pattern on page 517
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.
Working with virtual system patterns on page 511
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 reference:
Virtual system pattern windows on page 552
The Virtual System Patterns 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.
Virtual system pattern processing
When deploying a virtual system instance, that is a collection of virtual machines,
SmartCloud Orchestrator virtual system pattern processing follows a specific
startup sequence.
A virtual system pattern is one or more virtual images and applications from the
SmartCloud 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 SmartCloud 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 editing views and parts on page 522 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
Chapter 6. Managing and deploying virtual patterns 559
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.
Related concepts:
Script packages overview on page 235
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.
Related tasks:
Working with virtual system patterns on page 511
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.
Creating new flavors in OpenStack
When you are deploying a virtual system pattern in OpenStack, you can create
new flavors using the nova flavor-create command.
With some images there are issues with resizing images larger than the size of the
image. If you do not have a reason to change the size, you can use a flavor with a
disk size of 0 (zero). You can create new flavors in OpenStack using the nova
flavor-create command.
nova flavor-create [--ephemeral <ephemeral>] [--swap <swap>] \
[--rxtx-factor <factor>] [--is-public <is-public>]
<name> <id> <ram> <disk> <vcpus>
where:
v --ephemeral <ephemeral> (optional) is the ephemeral space size in GB (the
default is 0).
v --swap <swap> (optional) is the swap size in MB (the default is 0).
v --rxtx-factor <factor> is the RX/TX factor (the default is 1).
v --is-public <is-public> makes the flavor accessible to the public (the default is
true).
v <name> is the name of the new flavor.
560 IBM SmartCloud Orchestrator 2.3: User's Guide
v <id> is the unique integer ID for the new flavor.
v <ram> is the memory size in MB.
v <disk> is the disk size in GB.
v <vcpus> is the number of vCPUs.
Flavors must be formed in a way that memory, CPU, and disk in flavor should be
larger or equal to the image requirement (in the disk case, it might be 0). These
image requirements can be seen in the SmartCloud Orchestrator UI under the
Hardware section for the registered/imported virtual image.
Example of the command:
nova flavor-create 4gb1cpu 12345 4096 0 1
Note: The ID (12345) is any number that has not been ever used before.
To view the currently defined flavors, use the nova flavor-list command.
Customizing flavors for Power features
Use flavor keys to manage PowerVM LPAR settings.
If you run the nova image-show <image-uuid> | grep cpu command against a
VMControl based image, you get the list of the different cpu related parameters
that can be set inside a flavor. This is an example of a configurable parameter:
customization.cpushmax
| {"name": "cpushmax", "rules": [{"id": "increment", "value": "1"},
{"id": "incrementType", "value": "LINEAR"}, {"id": "max", "value": "4"},
{"id": "min", "value": "1"}], "required": false, "value": 1, "type": "LONG",
"description": "The maximum number of virtual processors to be assigned to the virtual
server. This parameter is only valid when using shared processors."}
The following list contains all the recommended flavor-controllable settings. Note
that many of these parameters are already configured for the five primary
OpenStack flavors for the VMControl region as part of the default installation.
memmin The minimum amount of memory (MB) to be assigned to the virtual server
(DLPAR minimum).
memmax The maximum amount of memory (MB) to be assigned to the virtual
server (DLPAR maximum).
cpushmax
The minimum number of shared virtual processors assigned to the virtual
server.
cpushmaxu
The maximum number of physical processing units to be assigned to the
virtual server.
cpushmin
The minimum number of shared virtual processors assigned to the virtual
server.
cpushminu
The minimum number of physical processing units assigned to the virtual
server.
cpushu The current amount of physical processing units assigned to the virtual
server.
Chapter 6. Managing and deploying virtual patterns 561
cpumode
SHARED or DEDICATED. Default value is SHARED.
cpudedmax
The maximum number of dedicated processors that can be assigned to the
virtual server.
cpudedmin
The minimum number of dedicated processors that can be assigned to the
virtual server.
storageconnection
VSCSI or NPIV. Note that NPIV is only available for SCS based hosts with
proper hardware configuration.
The traditional OpenStack vcpus value in a flavor maps to the number of virtual
processors (or physical processors if cpumode == "DEDICATED"). Similarly the
OpenStack memory value in a flavor maps to the current amount of memory.
Note that the storageconnection == NPIV setting must only be used against a
Server Pool which has all of its hosts being NPIV capable.
To change the settings of these parameters for a given flavor, use the nova
flavor-key <flavor-name> set "ibm:<key>=<value>" command to configure
memory and CPU characteristics of the LPAR. You can use ibm: or
ibm-smartcloud: as prefix in the command. For example, to set a different value as
opposed to the default cpushmax value for the m1.small flavor, update the flavor by
running the following command:
nova flavor-key m1.small set "ibm:cpushmax=6"
Managing virtual system instances
A virtual system instances is the virtual environment that is being managed by
your SmartCloud 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 created by deploying virtual images or by using
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 SmartCloud Orchestrator called placement. The placement component is an
internal component that 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 SmartCloud 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.
562 IBM SmartCloud Orchestrator 2.3: User's Guide
The virtual system instances are managed by SmartCloud Orchestrator and can be
serviced and accessed through the user interface. Virtual system instances managed
by SmartCloud 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
v You can use the user interface to manage your virtual system instance. See
Managing virtual system instances with the user interface for more
information.
v You can administer your virtual system instances using the SmartCloud
Orchestrator command-line interface. See Virtual system instances
command-line interface reference on page 902 for more information.
Results
You have become familiar with all the actions associated with managing a virtual
system instances.
Related reference:
Virtual system instances command-line interface reference on page 902
This topic provides a reference for administering virtual system instances using the
SmartCloud Orchestrator command-line interface.
Managing virtual system instances with the user interface
You can manage your SmartCloud 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 on page 547, for more information about
creating a virtual system instance by deploying a pattern.
About this task
You can perform a variety of tasks to manage your SmartCloud Orchestrator
virtual system instances with the user interface.
Note: Creating, restoring, or deleting snapshots for virtual system instances is not
available on Power instances.
Procedure
1. Navigate to the Virtual System Instances window by clicking Instances >
Virtual Systems from the menu bar.
The list of the virtual system instances being managed by SmartCloud
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
Chapter 6. Managing and deploying virtual patterns 563
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 SmartCloud 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 on page 566. Virtual system
instances can be stopped without removing the virtual system instance from
SmartCloud 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 SmartCloud Orchestrator and the virtual system
instance remains available for redeployment in the future.
v Removing a virtual system instance on page 567. You can remove a virtual
system instance when it is no longer needed. By removing a virtual system
instance, you release all the SmartCloud Orchestrator resources, making them
available for placement decisions.
v Creating a snapshot image on page 569. 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 from a snapshot image on page 570. 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 571. 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 on page 573.
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 SmartCloud Orchestrator user interface.
v Viewing the details for your virtual machines on page 575. 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.
Related reference:
Virtual system instances command-line interface reference on page 902
This topic provides a reference for administering virtual system instances using the
SmartCloud Orchestrator command-line interface.
564 IBM SmartCloud Orchestrator 2.3: User's Guide
Starting a persistent virtual system instance:
Virtual system instances managed by SmartCloud 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 on page 547, for more information
about creating a virtual system instance by deploying a pattern.
About this task
When a virtual system instance is stopped, the SmartCloud Orchestrator resources
are not released and the virtual system instance remains managed by SmartCloud
Orchestrator. The virtual system instance still has an impact on placement
decisions though it is not actively running on the hypervisor. The SmartCloud
Orchestrator resources assigned to this virtual system instance are maintained to
ensure that SmartCloud 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.
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 on page 573 for more information.
Related tasks:
Chapter 6. Managing and deploying virtual patterns 565
Managing virtual system instances on page 562
A virtual system instances is the virtual environment that is being managed by
your SmartCloud Orchestrator.
Related reference:
Virtual system instances command-line interface reference on page 902
This topic provides a reference for administering virtual system instances using the
SmartCloud Orchestrator command-line interface.
Stopping a persistent virtual system instance:
You can stop a persistent virtual system instance without removing the virtual
system instance from SmartCloud 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 SmartCloud 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
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 on page
547 and Accessing virtual machines in your virtual system instance on page 573
for more information.
Related tasks:
566 IBM SmartCloud Orchestrator 2.3: User's Guide
Managing virtual system instances on page 562
A virtual system instances is the virtual environment that is being managed by
your SmartCloud Orchestrator.
Starting a persistent virtual system instance on page 565
Virtual system instances managed by SmartCloud 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.
Removing a virtual system instance
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.
Related reference:
Virtual system instances command-line interface reference on page 902
This topic provides a reference for administering virtual system instances using the
SmartCloud Orchestrator command-line interface.
Removing a virtual system instance:
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 SmartCloud 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
SmartCloud Orchestrator.
Procedure
1. From the Virtual System Instances window, click the remove icon to remove the
virtual system instance and release the SmartCloud 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.
Chapter 6. Managing and deploying virtual patterns 567
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 on page 547 for more information about creating a virtual system instance
by deploying a pattern. See Accessing virtual machines in your virtual system
instance on page 573 for more information about accessing a virtual system
instance.
Related tasks:
Managing virtual system instances on page 562
A virtual system instances is the virtual environment that is being managed by
your SmartCloud Orchestrator.
Related reference:
Virtual system instances command-line interface reference on page 902
This topic provides a reference for administering virtual system instances using the
SmartCloud Orchestrator command-line interface.
568 IBM SmartCloud Orchestrator 2.3: User's Guide
Creating a snapshot image:
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.
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
Using the snapshot function, you are able to 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 their states that existed when the snapshot was taken. You should 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 Instances > Virtual Systems.
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.
Related tasks:
Chapter 6. Managing and deploying virtual patterns 569
Restoring virtual system instances 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.
Deleting snapshot images on page 571
You can delete a snapshot image of a virtual system instance that you no longer
require.
Restoring virtual system instances 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.
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 Instances > Virtual Systems.
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.
4.
Results
After completing these steps, 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.
Related tasks:
570 IBM SmartCloud Orchestrator 2.3: User's Guide
Creating a snapshot image on page 569
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.
Deleting snapshot images
You can delete a snapshot image of a virtual system instance that you no longer
require.
Deleting snapshot images:
You can delete a snapshot image of a virtual system instance 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 Instances > Virtual Systems.
2. Select the virtual system instance for which you want to delete the snapshot
image.
3. Click Delete next to the snapshot.
Results
The snapshot image is deleted from the system memory.
Related tasks:
Creating a snapshot image on page 569
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.
Restoring virtual system instances from a snapshot image on page 570
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.
Chapter 6. Managing and deploying virtual patterns 571
Virtual Systems fields on the user interface:
The Virtual System Instances window provides fields to view and work with the
virtual system instances in SmartCloud Orchestrator.
Virtual Systems fields
The following fields are used when working with a virtual system instance:
Created on
This field specifies the date and time when the virtual system instance was
created. This field is automatically generated.
From pattern
This field 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
This field specifies the state of the virtual machine.
Updated on
This field 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, then you need to manually add
the projects to which these users belong. See User roles in SmartCloud
Orchestrator on page 151 for more information about object level
permissions.
Snapshot
This field includes links to any snapshot images that have been taken of
this virtual system instance.
History
This field specifies the activity that has been performed on this virtual
system instance.
Virtual Machines
This field 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 window on page 577.
Comments
This field specifies optional information a user can append to a virtual
system instance.
Related tasks:
Managing virtual system instances on page 562
A virtual system instances is the virtual environment that is being managed by
572 IBM SmartCloud Orchestrator 2.3: User's Guide
your SmartCloud Orchestrator.
Working with virtual system patterns on page 511
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.
Managing environment profiles on page 220
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.
Related reference:
Virtual machine panel fields on the Virtual System window on page 577
You can view information about the virtual machines that are associated with a
virtual system instance using the Virtual machines panel on the Virtual Systems
window of the user interface.
Accessing virtual machines in your virtual system instance:
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 SmartCloud 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 Systems window by clicking
Instances > Virtual Systems on the menu.
Tip: You can also access virtual machine, in more detail, when they are hosted
by hypervisors. For more information, see Administering virtual machines on
page 194.
2. From the left panel of the Virtual System Instances 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:
Chapter 6. Managing and deploying virtual patterns 573
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
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. For more information
about configuring DNS, see Configuring DNS for the Workload Deployer IP
groups on page 61.
Results
After completing these steps, you have accessed your virtual machine from the
Virtual System Instances window of the user interface.
Related tasks:
Managing virtual system instances on page 562
A virtual system instances is the virtual environment that is being managed by
your SmartCloud Orchestrator.
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
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 Instances > Virtual Systems to access the Virtual System Instances
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 247.
574 IBM SmartCloud Orchestrator 2.3: User's Guide
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 Components > 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.
Viewing the details for your virtual machines:
Each virtual system instance 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 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
Chapter 6. Managing and deploying virtual patterns 575
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
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
window on page 577.
Related tasks:
Managing virtual system instances on page 562
A virtual system instances is the virtual environment that is being managed by
your SmartCloud Orchestrator.
Working with virtual system patterns on page 511
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.
Managing script packages on page 234
You can use script packages to customize the behavior of parts in SmartCloud
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.
Related reference:
576 IBM SmartCloud Orchestrator 2.3: User's Guide
Virtual machine panel fields on the Virtual System 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 Systems
window of the user interface.
Virtual machine panel fields on the Virtual System 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 Systems
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 SmartCloud 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 Clicking the Login link opens a dialog to log in to an SSH session.
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.
Chapter 6. Managing and deploying virtual patterns 577
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.
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:
578 IBM SmartCloud Orchestrator 2.3: User's Guide
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 574.
Note: If you are using SmartCloud 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 on page 511 for more
details on the pattern options.
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.
Chapter 6. Managing and deploying virtual patterns 579
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 251 for more information about the environment
variables.
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 234 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 254.
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 on page 573 for more information about accessing you virtual
machines.
580 IBM SmartCloud Orchestrator 2.3: User's Guide
Working with virtual applications
SmartCloud 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. SmartCloud Orchestrator determines the infrastructure
and middleware that is required to host the virtual application at deployment time.
Virtual application patterns
SmartCloud 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.
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 SmartCloud 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
Chapter 6. Managing and deploying virtual patterns 581
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.
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 Virtual
Application Builder. Within Virtual Application 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.
582 IBM SmartCloud Orchestrator 2.3: User's Guide
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.
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. Use layers and reusable components to simplify creation of additional virtual
application patterns.
v Groups components into layers or import a virtual application into your
virtual application pattern a layer.
v Add predefined reusable components to the virtual application. For more
information, see Working with reusable application components on page
598.
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.
Chapter 6. Managing and deploying virtual patterns 583
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.
Components
The following components are available with the virtual application patterns
provided with SmartCloud Orchestrator or purchasable at the IBM PureSystems
Centre.
Important: Components that require disk add-ons are not supported in
SmartCloud Orchestrator.
v Application
Additional archive file
Enterprise application
Existing Web Service Provider Endpoint on page 615
Policy Set on page 617
Web application, such as IBM WebSphere Application Server
v Database
Data Studio web console
Database, such as IBM DB2
Existing database (DB2) on page 626
Existing database (Informix)
Existing database (Oracle)
Existing IMS database on page 631
v Messaging
Existing Messaging Service (WebSphere MQ) on page 643
Existing Queue (WebSphere MQ) on page 647
Existing Topic (WebSphere MQ) on page 645
v OSGi
External OSGi bundle repository
OSGi application
v Transaction Processing
CICS
Transaction Gateway.
Existing IMS TM on page 656.
v User Registry
Existing User Registry (IBM Tivoli Directory Server) on page 633
Existing User Registry (Microsoft Active Directory) on page 636
User Registry (Tivoli Directory Server) on page 640
v Other components
Generic target
Debug on page 702
Policies
You can optionally apply policies to a virtual application to configure specific
behavior in the deployed virtual application instance. Two virtual applications
584 IBM SmartCloud Orchestrator 2.3: User's Guide
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
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 SmartCloud 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.
Other pattern types are purchasable at the IBM PureSystems Centre.
Note: The following pattern types are supported by the current version of
SmartCloud Orchestrator:
foundation 2.0.1.1
dbaas 1.1.0.7
webApp 1.0 1.0.1.0
webApp 2.0 2.0.1.0
application 1.0.1.0
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 SmartCloud Orchestrator.
To use the command-line interface, see the information provided in Pattern type
command-line interface on page 870.
Use the following steps to work with pattern types:
Procedure
1. View the pattern types.
2. View the system plug-ins in the pattern types.
3. Import a pattern type.
Chapter 6. Managing and deploying virtual patterns 585
4. 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 Configuration > 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 SmartCloud 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:
Procedure
1. Click 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.
586 IBM SmartCloud Orchestrator 2.3: User's Guide
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 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.
Related tasks:
Importing pattern types
You can import a new pattern type to SmartCloud Orchestrator.
Importing pattern types
You can import a new pattern type to SmartCloud Orchestrator.
Before you begin
You must be assigned the admin role to perform these steps.
Avoid trouble: To upload a file that is larger than 2 GB, you must either upload it
from a remote system or use the command line. To upload a file from a local
system, the size of the file must be smaller than 2 GB.
About this task
Complete the following procedure to upload and import a new pattern type from a
local system.
Procedure
1. Click 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.
Chapter 6. Managing and deploying virtual patterns 587
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.
Related reference:
Pattern type command-line interface on page 870
You can administer pattern types using the SmartCloud Orchestrator
command-line interface.
Removing a pattern type
You can remove a pattern type from the SmartCloud 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 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.
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.
588 IBM SmartCloud Orchestrator 2.3: User's Guide
If you download an update from Fix Central, and import the file into SmartCloud
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 SmartCloud 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 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.
Related tasks:
Upgrading a deployed pattern type
You can upgrade a pattern type that is associated with a virtual application
instance through the SmartCloud Orchestrator user interface.
Upgrading a deployed pattern type
You can upgrade a pattern type that is associated with a virtual application
instance through the SmartCloud Orchestrator user interface.
Before you begin
The pattern type license must be enabled before you can upgrade. Click
Configuration > Pattern Types > pattern_type > Enable.
About this task
Perform the following steps:
Chapter 6. Managing and deploying virtual patterns 589
Procedure
1. View the virtual application instances. Click 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 SmartCloud 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"
590 IBM SmartCloud Orchestrator 2.3: User's Guide
},
"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"
}
]
}
]
}
}
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 Virtual Application Builder. You can find
information about plug-in components, links, and policies at Virtual application
pattern components on page 583. 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.
Chapter 6. Managing and deploying virtual patterns 591
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 Virtual Application 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.
Procedure
1. Click Images & Patterns > 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 Virtual Application 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.
592 IBM SmartCloud Orchestrator 2.3: User's Guide
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 Virtual Application 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 Use reusable components that you created. For more information, see
Working with reusable application components on page 598. A reusable
component is a saved configuration that can be reused to build applications.
Components that are reusable display a triangle. Click the triangle to get a
list of reusable components. Then drag the reusable component to the Virtual
Application Builder canvas. This creates a new component that has the same
configuration as the reusable component. You can also add a reusable
component in Virtual Application Builder. Select a component in the canvas,
configure its properties and then click Add to my palette. The reusable
component displays in the left pane.
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.
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 Virtual Application Builder to edit your virtual application pattern. You
can add, edit or remove components, links and policies.
Chapter 6. Managing and deploying virtual patterns 593
Procedure
1. Click Images & Patterns > 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 Use reusable components that you created. For more information, see
Working with reusable application components on page 598. A reusable
component is a saved configuration that can be reused to build applications.
Components that are reusable display a triangle. Click the triangle to get a
list of reusable components. Then drag the reusable component to the Virtual
Application Builder canvas. This creates a new component that has the same
configuration as the reusable component. You can also add a reusable
component in Virtual Application Builder. Select a component in the canvas,
configure its properties and then click Add to my palette. The reusable
component displays in the left pane.
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.
Procedure
1. Click Images & Patterns > 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.
594 IBM SmartCloud Orchestrator 2.3: User's Guide
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 Images & Patterns > 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 Virtual Application Builder in SmartCloud 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 Virtual Application 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.
Follow these steps to create an application layer:
Procedure
1. Click Images & Patterns > Virtual Application Patterns. The Virtual
Application Pattern palette displays.
2. Select the virtual application for which you want to create a layer.
Chapter 6. Managing and deploying virtual patterns 595
3. Click the Open icon to edit the pattern layer. The Virtual Application Builder
displays. The Layers palette displays on the bottom left of the Virtual
Application 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 Virtual Application Builder in SmartCloud 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 Virtual Application 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:
Procedure
1. Click Images & Patterns > 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 Virtual Application Builder opens.
596 IBM SmartCloud Orchestrator 2.3: User's Guide
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 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.
Related tasks:
Deploying virtual application patterns on page 736
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.
Deleting virtual application pattern layers
You can use the Virtual Application Builder in SmartCloud Orchestrator to delete
virtual application pattern layers.
About this task
In the Virtual Application 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 Images & Patterns > 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 Virtual Application Builder opens. The Layers palette
displays on the lower left of the Virtual Application 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.
Chapter 6. Managing and deploying virtual patterns 597
Results
You deleted a virtual application pattern layer.
Importing virtual application pattern layers
You can use the Virtual Application Builder in SmartCloud Orchestrator to import
an application as a reference layer.
About this task
In the Virtual Application 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 Images & Patterns > 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 Virtual Application 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 reusable application components
You can create a reusable virtual application component and associate the
component with an available pattern type. The reusable components are saved in
the SmartCloud Orchestrator catalog.
Before you begin
You must be assigned the catalogeditor role or the admin role to perform these
steps.
598 IBM SmartCloud Orchestrator 2.3: User's Guide
About this task
To create a reusable application component in the user interface, follow these steps:
Procedure
1. Click Components > Reusable Components. The Reusable Components palette
displays.
2. From the left panel of the Reusable Components palette, click the New icon to
create a reusable component. The Create dialogue window displays.
3. Select the pattern type from the drop down menu.
4. Select a component type from the drop down menu. The components available
depend on which pattern type that you choose. The components that are
included in that pattern type are available for selection.
5. Click Next.
6. Complete the configuration settings for the component. The type of information
requested for components is different for each type of component created,
including, name, server host name, IP address, user name and password, and
server port number. You can edit the components as follows: Select the reusable
component in the Reusable Components palette and click the Edit icon in the
upper right.
For a list of settings for each component type, see Virtual application pattern
components on page 583.
7. Click Done.
Results
You have created and added a reusable component to the catalog. The component
is now listed in the left hand panel of the Reusable Components palette.
What to do next
Use the component to create an application or edit the component.
If you want to delete the reusable component, select the component in the
Reusable Components palette and click the Delete icon in the upper right.
Related information:
Virtual application pattern components on page 583
A virtual application pattern contains components that represent middleware
services that are required by the virtual appliance instance.
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
Chapter 6. Managing and deploying virtual patterns 599
templates also provide a more flexible deployment option. When you deploy from
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 Components > 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 SmartCloud 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
Images & Patterns > 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 Virtual Application Builder.
Procedure
1. Click Components > 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 Virtual Application 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.
600 IBM SmartCloud Orchestrator 2.3: User's Guide
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 Virtual Application 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 Components > 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.
Chapter 6. Managing and deploying virtual patterns 601
b. Click the Open icon in the Virtual Application Pattern pane. The Virtual
Application 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.
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 Components > 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
602 IBM SmartCloud Orchestrator 2.3: User's Guide
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 Virtual Application Builder. The application model
source is displayed. Search for the element plugins to view the list.
6. Click Save.
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 Components > 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 Virtual Application
Builder opens.
Importing a virtual application template:
You can import a virtual application template to the SmartCloud 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 Components > 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 6. Managing and deploying virtual patterns 603
Exporting a virtual application template:
You can export a virtual application template from the SmartCloud 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 Components > 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 SmartCloud 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 Components > 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.
604 IBM SmartCloud Orchestrator 2.3: User's Guide
Results
The virtual application template has been removed from the catalog.
Related tasks:
Creating a virtual application template on page 600
You can create a new virtual application template that is used to create a virtual
application. The template can be saved in the SmartCloud Orchestrator catalog.
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 Virtual
Application 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
Virtual Application Builder. In the Virtual Application 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 Virtual
Application 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.
Related tasks:
Managing pattern types on page 585
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.
Related reference:
Plug-in development guide on page 676
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
Chapter 6. Managing and deploying virtual patterns 605
effort.
Managing system plug-ins
SmartCloud 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.
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 SmartCloud Orchestrator pattern types. You can use these plug-ins to
extend the function of virtual applications.
In the SmartCloud Orchestrator user interface, click Configuration > System
Plug-ins and select the Foundation pattern type to see a list of the related plug-ins.
In the Virtual Application Builder, components are grouped into categories.
Related information:
Virtual application pattern components on page 583
A virtual application pattern contains components that represent middleware
services that are required by the virtual appliance instance.
606 IBM SmartCloud Orchestrator 2.3: User's Guide
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 SmartCloud Orchestrator user interface.
2. Click 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 SmartCloud Orchestrator user interface.
2. Click 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.
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.
Chapter 6. Managing and deploying virtual patterns 607
Components
The following components are available with the virtual application patterns
provided with SmartCloud Orchestrator or purchasable at the IBM PureSystems
Centre.
Important: Components that require disk add-ons are not supported in
SmartCloud Orchestrator.
v Application
Additional archive file
Enterprise application
Existing Web Service Provider Endpoint on page 615
Policy Set on page 617
Web application, such as IBM WebSphere Application Server
v Database
Data Studio web console
Database, such as IBM DB2
Existing database (DB2) on page 626
Existing database (Informix)
Existing database (Oracle)
Existing IMS database on page 631
v Messaging
Existing Messaging Service (WebSphere MQ) on page 643
Existing Queue (WebSphere MQ) on page 647
Existing Topic (WebSphere MQ) on page 645
v OSGi
External OSGi bundle repository
OSGi application
v Transaction Processing
CICS Transaction Gateway.
Existing IMS TM on page 656.
v User Registry
Existing User Registry (IBM Tivoli Directory Server) on page 633
Existing User Registry (Microsoft Active Directory) on page 636
User Registry (Tivoli Directory Server) on page 640
v Other components
Generic target
Debug on page 702
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
608 IBM SmartCloud Orchestrator 2.3: User's Guide
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
v Enterprise application component on page 610
v Existing Web Service Provider Endpoint on page 615
v Policy Set on page 617
v Web application component on page 618
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 32. 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)
Chapter 6. Managing and deploying virtual patterns 609
Table 32. Incoming connectable components (continued)
Component name Description Connection properties
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 Images & Patterns > Virtual Application Patterns.
2. Select a virtual_application_pattern.
3. Click Edit the virtual application icon located in the upper right corner of the
Virtual Application Builder palette.
4. To edit an existing archive file component, select the Additional archive file
component part on the Virtual Application 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 Virtual Application Builder canvas. The properties
panel for the component displays to the right of the Virtual Application 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 additional archive file component properties by viewing
the plug-in information. Click 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 .
610 IBM SmartCloud Orchestrator 2.3: User's Guide
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
Table 33. 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
enterprise bundle archive (EBA) application)
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
record files.
JVM policy (web or enterprise application) A policy to control features of the
underlying Java Virtual Machine (JVM).
Table 34. 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.
Chapter 6. Managing and deploying virtual patterns 611
Table 34. Incoming connectable components (continued)
Component name Description
System updates System updates for download and update
on the virtual machine.
Table 35. Outgoing connectable components
Component name Description Connection
Existing Topic (WebSphere
MQ)
An existing topic represents a
message destination on an
external IBM WebSphere MQ
messaging service through
which messages are
published and subscribed.
v Java Naming and
Directory Interface (JNDI)
name
v Resource environment
references
v Message destination
references
Additional archive file An additional archive file
component for your primary
archive.
Existing messaging service
(WebSphere MQ)
A 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
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
that represents a
pattern-deployed database
service.
v JNDI name of the data
source
v Resource references of the
data source
v Non-transactional data
source
v Minimum connections
v Maximum connections
v Connection timeout
612 IBM SmartCloud Orchestrator 2.3: User's Guide
Table 35. Outgoing connectable components (continued)
Component name Description Connection
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.
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.
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
v Group filter
v Role name
v User role mapping
v Group role mapping
v Special subject mapping
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.
Chapter 6. Managing and deploying virtual patterns 613
Table 35. Outgoing connectable components (continued)
Component name Description Connection
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).
Existing web service provider
endpoint
A web service provider
provided by a remote server.
Existing queue (WebSphere
MQ)
A message queue on an
external WebSphere MQ
messaging service through
which messages are sent and
received.
v JNDI name
v Resource environment
references
v Message destination
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
614 IBM SmartCloud Orchestrator 2.3: User's Guide
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 Images & Patterns > Virtual Application Patterns.
2. Select a virtual_application_pattern.
3. Click Edit the virtual application icon located in the upper right corner of the
Virtual Application Builder palette.
4. To edit an existing enterprise application component, select the Enterprise
Application component part on the Virtual Application 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 enterprise application component to a virtual application pattern, click
the Enterprise Application component listed under the Application
Components and drag the icon to the Virtual Application Builder canvas. The
properties panel for the component displays to the right of the Virtual
Application 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 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 SmartCloud 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.
Chapter 6. Managing and deploying virtual patterns 615
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 36. 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
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 Images & Patterns > Virtual Application Patterns.
2. Select a virtual_application_pattern.
3. Click Edit the virtual application icon located in the upper right corner of the
Virtual Application Builder palette.
4. To edit an existing enterprise application component, select the Existing Web
Service Provider Endpoint component part on the Virtual Application 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
Virtual Application Builder canvas. The properties panel for the component
616 IBM SmartCloud Orchestrator 2.3: User's Guide
displays to the right of the Virtual Application 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 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
Table 37. 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
v Service name
v Binding file
v Key store
v Trust store (encryption)
v Trust store (digital
signature)
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 Provider policy set binding
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.
Chapter 6. Managing and deploying virtual patterns 617
About this task
You can view, edit, or add this virtual application component in the user interface
as follows:
Procedure
1. Click Images & Patterns > Virtual Application Patterns.
2. Select a virtual_application_pattern.
3. Click Edit the virtual application icon located in the upper right corner of the
Virtual Application Builder palette.
4. To edit an existing policy set component, select the Policy Set component part
on the Virtual Application 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 Virtual Application Builder canvas. The properties panel for the
component displays to the right of the Virtual Application 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 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.
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 38. Policy components for web applications
Policy name Description
Routing policy (web, enterprise, or OSGi
enterprise bundle archive (EBA) application)
Routing policy for a web application,
enterprise application, or an OSGi EBA
application.
618 IBM SmartCloud Orchestrator 2.3: User's Guide
Table 38. Policy components for web applications (continued)
Policy name Description
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 39. 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 40. Outgoing connectable components
Component name Description Connection
Existing Topic (WebSphere
MQ)
An existing topic represents a
message destination on an
external IBM WebSphere MQ
messaging service through
which messages are
published and subscribed.
v Java Naming and
Directory Interface (JNDI)
name
v Resource environment
references
v Message destination
references
Additional archive file An additional archive file
component for your primary
archive.
Existing messaging service
(WebSphere MQ)
A 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
Policy set A component used to define
quality of service policies.
Chapter 6. Managing and deploying virtual patterns 619
Table 40. 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
that represents a
pattern-deployed database
service.
v JNDI name of the data
source
v Resource references of the
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.
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.
620 IBM SmartCloud Orchestrator 2.3: User's Guide
Table 40. Outgoing connectable components (continued)
Component name Description Connection
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.
v User filter
v Group filter
v Role name
v User role mapping
v Group role mapping
v Special subject mapping
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 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).
Existing web service provider
endpoint
A web service provider
provided by a remote server.
Chapter 6. Managing and deploying virtual patterns 621
Table 40. Outgoing connectable components (continued)
Component name Description Connection
Existing queue (WebSphere
MQ)
A message queue on an
external WebSphere MQ
messaging service through
which messages are sent and
received.
v JNDI name
v Resource environment
references
v Message destination
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.
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 Images & Patterns > Virtual Application Patterns.
2. Select a virtual_application_pattern.
3. Click Edit the virtual application icon located in the top right corner of the
Virtual Application Builder palette.
4. To edit an existing web application component, select the Web Application
component part on the Virtual Application 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 Virtual Application Builder canvas. The properties panel
for the component displays to the right of the Virtual Application 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 Configuration > System plug-ins. Select was/x.x.x.x
622 IBM SmartCloud Orchestrator 2.3: User's Guide
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 624
v Existing database (DB2) on page 626
v Existing database (Oracle) on page 629
v Existing IMS database on page 631
v Existing database (Informix) on page 628
v Database Studio web console
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 Virtual Application 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 Images & Patterns > Virtual Application Patterns.
2. Select a virtual_application_pattern.
3. Click Edit the virtual application icon located in the top right corner of the
Virtual Application Builder palette.
Chapter 6. Managing and deploying virtual patterns 623
4. To edit an existing Data Studio web console component, select the Data Studio
web console component part on the Virtual Application 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 Virtual Application Builder
canvas. The properties panel for the component displays to the right of the
Virtual Application 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 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.
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.
624 IBM SmartCloud Orchestrator 2.3: User's Guide
- 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 41. 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 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 Images & Patterns > Virtual Application Patterns.
2. Select a virtual_application_pattern.
3. Click Edit the virtual application icon located in the upper right corner of the
Virtual Application Builder palette.
4. To edit an existing DB2 database component, select the Database (DB2)
component part on the Virtual Application 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 Virtual Application Builder canvas. The properties panel for the
component is displayed to the right of the Virtual Application 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.
Chapter 6. Managing and deploying virtual patterns 625
6. You can also view the DB2 database component properties by viewing the
plug-in information. Click 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>.
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 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 applications
(WAR files).
v Java Naming and
Directory Interface (JNDI)
name of the data source
v Resource references of the
data source
v Non-transactional data
source
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 JNDI name of the data
source
v Resource references of the
data source
v Non-transactional data
source
626 IBM SmartCloud Orchestrator 2.3: User's Guide
Table 42. Incoming connectable components (continued)
Component name Description Connection properties
OSGi application (WebSphere
Application Server)
OSGi application on
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
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 Images & Patterns > Virtual Application Patterns.
2. Select a virtual_application_pattern.
3. Click Edit the virtual application icon located in the upper right corner of the
Virtual Application Builder palette.
4. To edit an existing remote DB2 database component, select the Existing
Database component part on the Virtual Application 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 Virtual Application Builder canvas. The
properties panel for the component displays to the right of the Virtual
Application 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 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.
Chapter 6. Managing and deploying virtual patterns 627
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.
v Password: Specifies the password to access the existing Informix database. This
attribute is required.
Connections
Table 43. 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
v Resource references of the
data source
v Non-transactional data
source
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 JNDI name of the data
source
v Resource references of the
data source
v Non-transactional data
source
OSGi application (WebSphere
Application Server)
OSGi application on
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
628 IBM SmartCloud Orchestrator 2.3: 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 Images & Patterns > Virtual Application Patterns.
2. Select a virtual_application_pattern.
3. Click Edit the virtual application icon located in the upper right corner of the
Virtual Application Builder palette.
4. To edit an existing remote Informix database component, select the Existing
Database component part on the Virtual Application 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 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 Virtual Application Builder
canvas. The properties panel for the component displays to the right of the
Virtual Application 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 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.
Chapter 6. Managing and deploying virtual patterns 629
Connections
Table 44. 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
v Resource references of the
data source
v Non-transactional data
source
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 JNDI name of the data
source
v Resource references of the
data source
v Non-transactional data
source
OSGi application (WebSphere
Application Server)
OSGi application on
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 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 Images & Patterns > Virtual Application Patterns.
2. Select a virtual_application_pattern.
3. Click Edit the virtual application icon located in the upper right corner of the
Virtual Application Builder palette.
4. To edit an existing remote Oracle database component, select the Existing
Database (Oracle) component part on the Virtual Application 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 Virtual Application Builder canvas. The
630 IBM SmartCloud Orchestrator 2.3: User's Guide
properties panel for the component displays to the right of the Virtual
Application 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 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.
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 45. 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
v Resource references of the
data source
Chapter 6. Managing and deploying virtual patterns 631
Table 45. Incoming connectable components (continued)
Component name Description Connection properties
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 JNDI name of the data
source
v Resource references of the
data source
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:
Procedure
1. Click Images & Patterns > Virtual Application Patterns.
2. Select a virtual_application_pattern.
3. Click Edit the virtual application icon located in the upper right corner of the
Virtual Application 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 Virtual Application Builder canvas. The
properties panel for the database component displays to the right of the Virtual
Application 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 Virtual Application 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 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.
632 IBM SmartCloud Orchestrator 2.3: User's Guide
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 636
v User Registry (Tivoli Directory Server) on page 640
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.
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
Chapter 6. Managing and deploying virtual patterns 633
Table 46. 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
Application Server)
OSGi application on
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
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 Images & Patterns > Virtual Application Patterns.
2. Select a virtual_application_pattern.
3. Click Edit the virtual application icon located in the upper right corner of the
Virtual Application Builder palette.
4. To edit an existing user registry component, select the component part on the
Virtual Application 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
634 IBM SmartCloud Orchestrator 2.3: User's Guide
under the User Registry Components and drag the icon to the Virtual
Application Builder canvas. The properties panel for the component displays to
the right of the Virtual Application 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 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>
Chapter 6. Managing and deploying virtual patterns 635
</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>
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.
636 IBM SmartCloud Orchestrator 2.3: User's Guide
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
Table 47. 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
v User role mapping
v Group role mapping
v Mapping special subjects
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 Role name
v User role mapping
v Group role mapping
v Mapping special subjects
OSGi application (WebSphere
Application Server)
OSGi application on
WebSphere Application
Server
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
Chapter 6. Managing and deploying virtual patterns 637
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 Images & Patterns > Virtual Application Patterns.
2. Select a virtual_application_pattern.
3. Click Edit the virtual application icon located in the upper right corner of the
Virtual Application Builder palette.
4. To edit an existing user registry component, select the component part on the
Virtual Application 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
Virtual Application Builder canvas. The properties panel for the component
displays to the right of the Virtual Application 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 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
638 IBM SmartCloud Orchestrator 2.3: User's Guide
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.
<?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"
Chapter 6. Managing and deploying virtual patterns 639
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.
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 48. 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
640 IBM SmartCloud Orchestrator 2.3: User's Guide
Table 48. Incoming connectable components (continued)
Component name Description Connection properties
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
Application Server)
OSGi application on
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.
You can view, edit, or add this virtual application component in the user interface
as follows:
Procedure
1. Click Images & Patterns > Virtual Application Patterns.
2. Select a virtual_application_pattern.
3. Click Edit the virtual application icon located in the upper right corner of the
Virtual Application Builder palette.
4. To edit an existing user registry component, select the component part on the
Virtual Application 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 Virtual Application Builder canvas. The properties
panel for the component displays to the right of the Virtual Application 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 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.
Chapter 6. Managing and deploying virtual patterns 641
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>
<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>
642 IBM SmartCloud Orchestrator 2.3: User's Guide
<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>
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 645
v Existing Queue (WebSphere MQ) on page 647
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.
Chapter 6. Managing and deploying virtual patterns 643
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 49. 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
v Resource references of JMS
connection factory
v Client ID
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 JNDI Name of JMS
connection factory
v Resource references of JMS
connection factory
v Client ID
OSGi application (WebSphere
Application Server)
OSGi application on
WebSphere Application
Server
v JNDI Name of JMS
connection factory
v Resource references of JMS
connection factory
v Client ID
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 Virtual Application 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 Images & Patterns > Virtual Application Patterns.
2. Select a virtual_application_pattern.
644 IBM SmartCloud Orchestrator 2.3: User's Guide
3. Click Edit the virtual application icon located in the upper right corner of the
Virtual Application Builder palette.
4. To edit an existing messaging service component, select the component part on
the Virtual Application 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 Virtual Application Builder canvas. The
properties panel for the transaction processing component displays to the right
of the Virtual Application 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 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.
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 50. 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
v Resource environment
references
v Message destination
references
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 JNDI name
v Resource environment
references
v Message destination
references
Chapter 6. Managing and deploying virtual patterns 645
Table 50. Incoming connectable components (continued)
Component name Description Connection properties
OSGi application (WebSphere
Application Server)
OSGi application on
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.
About this task
You can view, edit, or add this virtual application component in the user interface
as follows:
Procedure
1. Click Images & Patterns > Virtual Application Patterns.
2. Select a virtual application pattern.
3. Click Edit the virtual application icon located in the upper right corner of the
Virtual Application Builder palette.
4. To edit an existing topic, select the Existing Topic component part on the
Virtual Application 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 Virtual Application Builder canvas. The properties
panel for the component displays to the right of the Virtual Application 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 Configuration > System plug-ins. Select wasmqt/x.x.x.x
646 IBM SmartCloud Orchestrator 2.3: User's Guide
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 51. 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
v Resource environment
references
v Message destination
references
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 JNDI name
v Resource environment
references
v Message destination
references
OSGi application (WebSphere
Application Server)
OSGi application on
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 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.
Chapter 6. Managing and deploying virtual patterns 647
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 Images & Patterns > Virtual Application Patterns.
2. Select a virtual_application_pattern.
3. Click Edit the virtual application icon located in the upper right corner of the
Virtual Application Builder palette.
4. To edit an existing queue, select the Existing Queue component part on the
Virtual Application 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 Virtual Application Builder canvas. The
properties panel for the component displays to the right of the Virtual
Application 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 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) on page 649
v OSGi Application (WebSphere Application Server) on page 650
648 IBM SmartCloud Orchestrator 2.3: User's Guide
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 52. 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 Images & Patterns > Virtual Application Patterns.
2. Select a virtual_application_pattern.
3. Click Edit the virtual application icon located in the upper right corner of the
Virtual Application Builder palette.
4. To edit an existing external OSGi bundle repository component, select the
External OSGi Bundle Repository component part on the Virtual Application
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 Virtual Application Builder
canvas. The properties panel for the component displays to the right of the
Virtual Application 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 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.
Chapter 6. Managing and deploying virtual patterns 649
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 53. 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).
Table 54. Outgoing connectable components
Component name Description Connection
Existing Topic (WebSphere
MQ)
An existing topic represents
a message destination on an
external IBM WebSphere MQ
messaging service through
which messages are
published and subscribed.
v Java Naming and
Directory Interface (JNDI)
name
v Resource environment
references
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
650 IBM SmartCloud Orchestrator 2.3: User's Guide
Table 54. 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
that represents a
pattern-deployed database
service.
v JNDI name of the data
source
v Resource references of the
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.
v JNDI name of the data
source
v Resource references of the
data source
v Non-transactional data
source
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
v Resource references of the
data source
v Non-transactional data
source
Existing CICS Transaction
Gateway (TG)
An existing CICS TG
component represents an
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.
v JNDI name of the CICS
TG resource
Chapter 6. Managing and deploying virtual patterns 651
Table 54. Outgoing connectable components (continued)
Component name Description Connection
Existing User Registry (Tivoli
Directory Server)
An existing user registry
(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.
v User filter
v Group filter
v Role name
v User role mapping
v Group role mapping
v Special subject mapping
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.
Existing Queue (WebSphere
MQ)
A message queue on an
external WebSphere MQ
messaging service through
which messages are sent and
received.
v JNDI name
v Resource environment
references
v Message destination
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.
652 IBM SmartCloud Orchestrator 2.3: User's Guide
About this task
You can view, edit, or add this virtual application component in the user interface
as follows:
Procedure
1. Click Images & Patterns > Virtual Application Patterns.
2. Select a virtual_application_pattern.
3. Click Edit the virtual application icon located in the upper right corner of the
Virtual Application Builder palette.
4. To edit an existing OSGi application component, select the OSGi application
component part on the Virtual Application 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 Virtual Application Builder canvas. The properties
panel for the component displays to the right of the Virtual Application 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 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.
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 656
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 SmartCloud 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:
Chapter 6. Managing and deploying virtual patterns 653
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 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 JNDI Name of the JCA
Connection Factory
v Maximum number of
connections to the CICS
Transaction Gateway
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 JNDI Name of the JCA
Connection Factory
v Maximum number of
connections to the CICS
Transaction Gateway
OSGi application (WebSphere
Application Server)
OSGi application on
WebSphere Application
Server
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 Virtual Application Builder canvas,
a properties panel is displayed.
You can view, edit, or add this virtual application component in the user interface
as follows:
654 IBM SmartCloud Orchestrator 2.3: User's Guide
Procedure
1. Click Images & Patterns > Virtual Application Patterns.
2. Select a virtual_application_pattern.
3. Click Edit the virtual application icon located in the upper right corner of the
Virtual Application 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 Virtual
Application Builder canvas. The properties panel for the transaction processing
component displays to the right of the Virtual Application 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 Virtual Application 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 Configuration > System 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 SmartCloud
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. SmartCloud 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 SmartCloud 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.
Chapter 6. Managing and deploying virtual patterns 655
Procedure
1. Click Cloud > 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).
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.
656 IBM SmartCloud Orchestrator 2.3: User's Guide
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 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 EE
web applications (WAR files).
v JNDI Name of the JCA
Connection Factory, or
v Resource references
mapping
v Maximum number of
connections to IMS TM
v Connection timeout
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 JNDI Name of the JCA
Connection Factory, or
v Resource references
mapping
v Maximum number of
connections to IMS TM
v Connection timeout
OSGi application (WebSphere
Application Server)
OSGi application on
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 Virtual Application
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 Images & Patterns > Virtual Application Patterns.
2. Select a virtual_application_pattern.
3. Click Edit the virtual application icon located in the upper right corner of the
Virtual Application Builder palette.
Chapter 6. Managing and deploying virtual patterns 657
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 Virtual Application Builder
canvas. The properties panel for the transaction processing component displays
to the right of the Virtual Application 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 Virtual Application 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 Configuration > System 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 702
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
658 IBM SmartCloud Orchestrator 2.3: User's Guide
Table 57. 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:
Procedure
1. Click Images & Patterns > Virtual Application Patterns.
2. Select a virtual_application_pattern.
3. Click Edit the virtual application icon located in the upper right corner of the
Virtual Application Builder palette.
4. To edit an existing generic target component, select the Generic target
component part on the Virtual Application 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 Virtual Application Builder canvas. The properties panel for the
component displays to the right of the Virtual Application 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 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.
Chapter 6. Managing and deploying virtual patterns 659
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 662
v Log policy on page 663
v JVM policy on page 664
Scaling policy:
Scaling is a Virtual Application 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.
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%.
660 IBM SmartCloud Orchestrator 2.3: User's Guide
Note: Due to OpenStack limitations, vertical scaling (increasing memory and CPU
on running systems without stopping the service) is not supported by SmartCloud
Orchestrator. Only horizontal scaling (increasing the number of virtual machines to
balance the workload) is supported when required by the scaling policy.
Connections
Table 58. 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:
Procedure
1. Click Images & Patterns > Virtual Application Patterns.
2. Select a virtual_application_pattern.
3. Click Edit the virtual application icon located in the upper right corner of the
Virtual Application Builder palette.
4. To edit an existing scaling policy, select the Scaling Policy part on the Virtual
Application 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 Virtual Application 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.
Chapter 6. Managing and deploying virtual patterns 661
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 59. 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
You can view, edit, or add a routing policy in the user interface as follows:
Procedure
1. Click Images & Patterns > Virtual Application Patterns.
2. Select a virtual_application_pattern.
3. Click Edit the virtual application icon located in the upper right corner of the
Virtual Application Builder palette.
4. To edit an existing routing policy, select the Routing Policy part on the Virtual
Application 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 Virtual Application Builder canvas. The policy is applied to
all applicable components in the canvas.
662 IBM SmartCloud Orchestrator 2.3: User's Guide
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 60. 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 log policy in the user interface as follows:
Procedure
1. Click Images & Patterns > Virtual Application Patterns.
2. Select a virtual_application_pattern.
3. Click Edit the virtual application icon located in the upper right corner of the
Virtual Application Builder palette.
4. To edit an existing log policy, select the Log Policy part on the Virtual
Application 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:
Chapter 6. Managing and deploying virtual patterns 663
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 Virtual Application 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.
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 61. 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).
664 IBM SmartCloud Orchestrator 2.3: User's Guide
Table 61. Outgoing connectable components (continued)
Component name Description
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 Images & Patterns > Virtual Application Patterns.
2. Select a virtual_application_pattern.
3. Click Edit the virtual application icon located in the upper right corner of the
Virtual Application Builder palette.
4. To edit an existing JVM policy, select the JVM Policy part on the Virtual
Application 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
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 Virtual Application 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.
Chapter 6. Managing and deploying virtual patterns 665
In SmartCloud 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 Virtual
Application 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 SmartCloud 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.
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",
666 IBM SmartCloud Orchestrator 2.3: User's Guide
"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 Virtual Application 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
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, SmartCloud 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.
Chapter 6. Managing and deploying virtual patterns 667
The WASCE package contains the parts/wasce.tgz part file. This archive
contains the wasce image - all the files that compose wasce. The binary
files 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 binary files. You can
define a file attribute and have administrators upload the required binary
files after loading the plug-in in SmartCloud 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
Virtual Application 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,
"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 Virtual Application 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 Virtual
Application 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 Virtual
Application Builder into a concrete topology.
668 IBM SmartCloud Orchestrator 2.3: User's Guide
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.
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
SmartCloud 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:
Chapter 6. Managing and deploying virtual patterns 669
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 binary files to a
monitored directory. The following example includes the contents of the
configure.py script:
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]
670 IBM SmartCloud Orchestrator 2.3: User's Guide
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 SmartCloud 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
SmartCloud Orchestrator. The custom plug-ins can be added to the SmartCloud
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
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 SmartCloud 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.
Chapter 6. Managing and deploying virtual patterns 671
v pdk-debug-{version}.tgz
This file is the debug plug-in that can be installed into the SmartCloud
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 SmartCloud 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
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 702.
672 IBM SmartCloud Orchestrator 2.3: User's Guide
Related tasks:
Developing plug-ins on page 666
Plug-ins define the components, links, and policies that you use in the Virtual
Application 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.
Working with virtual application pattern plug-ins on page 605
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.
Sample: Setting up the plug-in development environment on page 725
Set up the environment for the plug-in Samples.
Related reference:
Plug-in development guide on page 676
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.
Samples on page 723
Use these samples to help you learn how to develop custom plug-ins. The plug-ins
that you develop can be added to the SmartCloud Orchestrator catalog and used
as components, links and policies for virtual applications.
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
SmartCloud 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 SmartCloud 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
Chapter 6. Managing and deploying virtual patterns 673
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 SmartCloud 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 SmartCloud
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 on page 675.
Related tasks:
Installing the Plug-in Development Kit on page 673
To get started using the Plug-in Development Kit, first download and install the
kit.
Setting up the plug-in development environment on page 675
Set up the environment to develop custom plug-ins that are used in SmartCloud
Orchestrator
Developing plug-ins on page 666
Plug-ins define the components, links, and policies that you use in the Virtual
Application 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.
Working with virtual application pattern plug-ins on page 605
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
674 IBM SmartCloud Orchestrator 2.3: User's Guide
plug-ins.
Related reference:
Plug-in development guide on page 676
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.
Plug-in Development Kit on page 671
The Plug-in Development Kit (PDK) is designed to help you build plug-ins for
SmartCloud Orchestrator. The custom plug-ins can be added to the SmartCloud
Orchestrator catalog where they are used to add components, links, and policies to
virtual applications.
Samples on page 723
Use these samples to help you learn how to develop custom plug-ins. The plug-ins
that you develop can be added to the SmartCloud Orchestrator catalog and used
as components, links and policies for virtual applications.
Setting up the plug-in development environment:
Set up the environment to develop custom plug-ins that are used in SmartCloud
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.
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 SmartCloud Orchestrator.
6. Import the pattern type .tgz and use the plug-in from the SmartCloud
Orchestrator catalog.
Chapter 6. Managing and deploying virtual patterns 675
Related tasks:
Developing plug-ins on page 666
Plug-ins define the components, links, and policies that you use in the Virtual
Application 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.
Working with virtual application pattern plug-ins on page 605
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.
Related reference:
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.
Plug-in Development Kit on page 671
The Plug-in Development Kit (PDK) is designed to help you build plug-ins for
SmartCloud Orchestrator. The custom plug-ins can be added to the SmartCloud
Orchestrator catalog where they are used to add components, links, and policies to
virtual applications.
Samples on page 723
Use these samples to help you learn how to develop custom plug-ins. The plug-ins
that you develop can be added to the SmartCloud Orchestrator catalog and used
as components, links and policies for virtual applications.
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 on page 677
Transformers: TopologyProvider services
Enhance template transforms with Java code
Plug-in components available as OSGi Declarative Services
v Deployment on page 682
Activation
Nodeparts
Parts
Roles
Set repeatable task
Recovery: Reboot or replace?
Virtual Application Console
v Other reference on page 697
v Application model and topology document examples on page 697
676 IBM SmartCloud Orchestrator 2.3: User's Guide
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
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).
SmartCloud 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"
}
Chapter 6. Managing and deploying virtual patterns 677
]
}
]
}
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: target.template == vm-template
## that holds the target role; target.role == role
## String argument is the type of the target role.
#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} )",
678 IBM SmartCloud Orchestrator 2.3: User's Guide
## 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"
}
]
}
]
}
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:
Chapter 6. Managing and deploying virtual patterns 679
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
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.
680 IBM SmartCloud Orchestrator 2.3: User's Guide
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.
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
SmartCloud Orchestrator provides limited support for OSGi services within
plug-ins. Specifically, plug-ins can provide implementations of specific SmartCloud
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
Chapter 6. Managing and deploying virtual patterns 681
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.
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.
682 IBM SmartCloud Orchestrator 2.3: User's Guide
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. Setup 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 files
and script files to augment the operating system. Review the following information
about nodeparts:
v Conventions
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:
Chapter 6. Managing and deploying virtual patterns 683
"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 json
import os
import subprocess
import sys
import maestro
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@"
}
}
]
}
]
}
}
684 IBM SmartCloud Orchestrator 2.3: User's Guide
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
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 lifecycle 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}.
Chapter 6. Managing and deploying virtual patterns 685
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
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>]
686 IBM SmartCloud Orchestrator 2.3: User's Guide
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
<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
Chapter 6. Managing and deploying virtual patterns 687
Parts are installed by the workload agent and generally contain binary files and
lifecycle 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:
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 lifecycle 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:{
688 IBM SmartCloud Orchestrator 2.3: User's Guide
"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",
"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 lifecycle scripts started:
Table 62. Role state and status
Role state script Transition Update status Set role status
Initial Initial =>
INSTALLED
on entry INITIAL
INSTALLED
{role}/install.py then all
{role}/{dep}/install.py
{role}/configure/py then
all {role}/{dep}/
configure.py
{role}/start.py
INSTALLED
=>
RUNNING
during INSTALLING
CONFIGURING
STARTING (role status by
script)
RUNNING
{role}/start.py
on entry
on changed
role_status (set by script)
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
Chapter 6. Managing and deploying virtual patterns 689
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".
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 SmartCloud 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.
690 IBM SmartCloud Orchestrator 2.3: User's Guide
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
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)
Chapter 6. Managing and deploying virtual patterns 691
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.
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",
692 IBM SmartCloud Orchestrator 2.3: User's Guide
"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",
"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
Chapter 6. Managing and deploying virtual patterns 693
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:
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 lifecycle 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
694 IBM SmartCloud Orchestrator 2.3: User's Guide
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
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.
Chapter 6. Managing and deploying virtual patterns 695
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"
]
}
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);
696 IBM SmartCloud Orchestrator 2.3: User's Guide
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",
"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 SmartCloud
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
Chapter 6. Managing and deploying virtual patterns 697
The appmodel.json file represents the serialization of the model that is defined in
the Virtual Application 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"
},
{
"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"
698 IBM SmartCloud Orchestrator 2.3: User's Guide
},
{
"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,
"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",
Chapter 6. Managing and deploying virtual patterns 699
"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
}
}
],
"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"
700 IBM SmartCloud Orchestrator 2.3: User's Guide
}
]
},
"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":[
"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 tasks:
Working with virtual application pattern plug-ins on page 605
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.
Related information:
JSON Formatter and Validator
JSONLint: The JSON Validator
Python documentation: Subprocess management
Chapter 6. Managing and deploying virtual patterns 701
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 SmartCloud
Orchestrator development environment.
1. Import the com.ibm.maestro.plugin.debug plug-in.
2. Restart SmartCloud 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.
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://172.16.33.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 Images & Patterns > Virtual Application Patterns.
702 IBM SmartCloud Orchestrator 2.3: User's Guide
2. Select a virtual_application_pattern.
3. Click Edit the virtual application icon located in the upper right corner of the
Virtual Application 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 Virtual Application
Builder canvas. The properties panel for the database component displays to
the right of the Virtual Application 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 Virtual
Application 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 Configuration > System plug-ins. Select Foundation Pattern Type from
the Select a pattern type drop-down 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.
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 SmartCloud 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.
Chapter 6. Managing and deploying virtual patterns 703
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 SmartCloud Orchestrator.
3. Delete the existing plug-in version from the SmartCloud 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.
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
SmartCloud Orchestrator.
704 IBM SmartCloud Orchestrator 2.3: User's Guide
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 SmartCloud 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.
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
Virtual Application 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
Chapter 6. Managing and deploying virtual patterns 705
script exports the values that are specified in xDB2 component on the Virtual
Application 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
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
706 IBM SmartCloud Orchestrator 2.3: User's Guide
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.
Related tasks:
Developing plug-ins on page 666
Plug-ins define the components, links, and policies that you use in the Virtual
Application 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.
Related reference:
Plug-in development guide on page 676
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.
Troubleshooting service for plug-ins:
Plug-ins provide troubleshooting operations that generate information that is
logged in the Logging Service and returned immediately to the end user.
This document discusses how the Troubleshooting Service provides a consistent
framework and helper methods for plug-ins to create a simplified and pleasant
user experience. The troubleshooting service is a guide to help map the
recommended design for a plug-in to create troubleshooting operations. Each
plug-in contains the list of troubleshooting operations for the specific role. You can
access the troubleshooting operations though the IBM Workload Deployer user
inferface deployment inlet on the Operations tab. The troubleshooting service uses
the deployment inlet operation capabilities with a recommended structure to
provide consistency and reduce the work required by the plug-in to add
troubleshooting operations. The troubleshooting operation is managed by python
life cycle scripts that the deployment inlet operation starts as the entry and exit
point of the operation. The troubleshooting python life cycle script can start other
scripts that the plug-in needs, but it must be clear that the scripts were successful
or not and provide the compressed file that is expected from the action. The
troubleshooting python life cycle script can take advantage of helper methods
provided by the troubleshooting service plug-in to make common actions easier.
Examples of the type of actions these methods can provide are mechanisms for
returning the data to the user through the deployment inlet and interacting with
the logging service to store historical troubleshooting information. The following
graphic illustrates a high level overview of how a plug-in integrates with the
troubleshooting service.
Related tasks:
Working with virtual application pattern plug-ins on page 605
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
Chapter 6. Managing and deploying virtual patterns 707
plug-ins.
Developing plug-ins on page 666
Plug-ins define the components, links, and policies that you use in the Virtual
Application 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.
Related reference:
Plug-in development guide on page 676
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.
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 theSmartCloud 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:
v High-level design of the log service
v Plug-in interaction with the log service on page 711
v Create a log service implementation on page 712
High-level design of the log service
The logging service is automatically included on all virtual machines that have the
SmartCloud 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
708 IBM SmartCloud Orchestrator 2.3: User's Guide
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 63. 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:
Table 64. 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
the logtype
False
format Specifies either binary or
text. The default is text.
False
Chapter 6. Managing and deploying virtual patterns 709
Table 64. Custom logtypes (continued). List of custom logtypes and details
Metadata field ID Value Required
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)
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.
710 IBM SmartCloud Orchestrator 2.3: User's Guide
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.
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
Chapter 6. Managing and deploying virtual patterns 711
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.
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.
712 IBM SmartCloud Orchestrator 2.3: User's Guide
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.
Related tasks:
Working with virtual application pattern plug-ins on page 605
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.
Developing plug-ins on page 666
Plug-ins define the components, links, and policies that you use in the Virtual
Application 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.
Related reference:
Chapter 6. Managing and deploying virtual patterns 713
Plug-in development guide on page 676
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.
Troubleshooting service for plug-ins on page 707
Plug-ins provide troubleshooting operations that generate information that is
logged in the Logging Service and returned immediately to the end user.
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 SmartCloud 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
SmartCloud 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);
SmartCloud Orchestrator monitoring has three types of collectors that are
described in the following table.
Table 65. 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.
714 IBM SmartCloud Orchestrator 2.3: User's Guide
Table 65. Monitoring collector types. (continued). Description of the monitoring collector types available for plug-ins.
Collector Property Usage
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 SmartCloud 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.
Registration
To use SmartCloud Orchestrator monitoring collectors, you must register the
collectors with the plug-in configuration, providing the node, role, metrics, and
collector facilities information.
SmartCloud 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 66. 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>",
}
Chapter 6. Managing and deploying virtual patterns 715
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 >} }')
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>
} ,
...... ......
]
}
716 IBM SmartCloud Orchestrator 2.3: User's Guide
},
...... ......
]
}
User interface presentation
Plug-in metrics are displayed in SmartCloud 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.
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 67. 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 68. Chart types. Chart types that are available to define metric data in plug-ins.
Chart types (chartType) Presentation
Lines
StackArea
StackColumn
Chapter 6. Managing and deploying virtual patterns 717
Table 68. Chart types (continued). Chart types that are available to define metric data in
plug-ins.
Chart types (chartType) Presentation
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.
SmartCloud 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 SmartCloud
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 SmartCloud Orchestrators Virtual Application 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
718 IBM SmartCloud Orchestrator 2.3: User's Guide
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
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 Virtual Application Builder.
You can customize your components and policies, including the auto scaling policy,
in the Virtual Application 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 SmartCloud 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>: [
Chapter 6. Managing and deploying virtual patterns 719
< 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>
],
}
},
{
......
}
]
}
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.
SmartCloud 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.
720 IBM SmartCloud Orchestrator 2.3: User's Guide
SmartCloud 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
topology document. The Trigger Event, Trigger Time, and Instance Number Scope
autoscaling elements correspond to "triggerEvents", "triggerTime", and "min"&"
max".
Related tasks:
Working with virtual application pattern plug-ins on page 605
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.
Developing plug-ins on page 666
Plug-ins define the components, links, and policies that you use in the Virtual
Application 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.
Related reference:
Plug-in development guide on page 676
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.
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 SmartCloud 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:
Chapter 6. Managing and deploying virtual patterns 721
{
"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"
}
]
},
"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"
}
]
}
]
}
}
722 IBM SmartCloud Orchestrator 2.3: User's Guide
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 SmartCloud 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
SmartCloud 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.
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
Chapter 6. Managing and deploying virtual patterns 723
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.
Related tasks:
Working with virtual application pattern plug-ins on page 605
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.
Developing plug-ins on page 666
Plug-ins define the components, links, and policies that you use in the Virtual
Application 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.
Sample: Setting up the plug-in development environment on page 725
Set up the environment for the plug-in Samples.
Sample: Developing a plug-in and pattern type with the Eclipse Framework on
page 727
This topic is an example of how to create a plug-in and pattern type using the
Eclipse Framework.
Sample: Creating an application with the patterntypetest.hello plug-in on page
730
In this Samples topic, you use the patterntypetest.hello plug-in to create an
application that is deployed to SmartCloud Orchestrator.
724 IBM SmartCloud Orchestrator 2.3: User's Guide
Sample: Building a single plug-in and pattern type with the command-line tools
on page 734
This topic is an example of how to create a plug-in and pattern type using
command-line tools.
Sample: Creating a plug-in project from the command line on page 732
This topic is an example of how to create a plug-in project using command-line
tools.
Related reference:
Plug-in development guide on page 676
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.
Plug-in Development Kit on page 671
The Plug-in Development Kit (PDK) is designed to help you build plug-ins for
SmartCloud Orchestrator. The custom plug-ins can be added to the SmartCloud
Orchestrator catalog where they are used to add components, links, and policies to
virtual applications.
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
Chapter 6. Managing and deploying virtual patterns 725
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.
Related tasks:
Developing plug-ins on page 666
Plug-ins define the components, links, and policies that you use in the Virtual
Application 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.
Working with virtual application pattern plug-ins on page 605
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.
Sample: Developing a plug-in and pattern type with the Eclipse Framework on
page 727
This topic is an example of how to create a plug-in and pattern type using the
Eclipse Framework.
Sample: Creating an application with the patterntypetest.hello plug-in on page
730
In this Samples topic, you use the patterntypetest.hello plug-in to create an
application that is deployed to SmartCloud Orchestrator.
Sample: Building a single plug-in and pattern type with the command-line tools
on page 734
This topic is an example of how to create a plug-in and pattern type using
command-line tools.
Sample: Creating a plug-in project from the command line on page 732
This topic is an example of how to create a plug-in project using command-line
tools.
Related reference:
Plug-in development guide on page 676
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.
Plug-in Development Kit on page 671
The Plug-in Development Kit (PDK) is designed to help you build plug-ins for
SmartCloud Orchestrator. The custom plug-ins can be added to the SmartCloud
Orchestrator catalog where they are used to add components, links, and policies to
virtual applications.
726 IBM SmartCloud Orchestrator 2.3: User's Guide
Samples on page 723
Use these samples to help you learn how to develop custom plug-ins. The plug-ins
that you develop can be added to the SmartCloud Orchestrator catalog and used
as components, links and policies for virtual applications.
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.
Chapter 6. Managing and deploying virtual patterns 727
Results
You have created a plug-in that can be imported into the SmartCloud Orchestrator
catalog.
What to do next
Import the plug-in into SmartCloud Orchestrator.
Related tasks:
Developing plug-ins on page 666
Plug-ins define the components, links, and policies that you use in the Virtual
Application 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.
Working with virtual application pattern plug-ins on page 605
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.
Sample: Setting up the plug-in development environment on page 725
Set up the environment for the plug-in Samples.
Sample: Building a single plug-in and pattern type with the command-line tools
on page 734
This topic is an example of how to create a plug-in and pattern type using
command-line tools.
Sample: Import a plug-in and pattern type into SmartCloud Orchestrator on
page 729
This topic is an example of how to import your sample plug-in into SmartCloud
Orchestrator
Related reference:
Plug-in development guide on page 676
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.
Plug-in Development Kit on page 671
The Plug-in Development Kit (PDK) is designed to help you build plug-ins for
SmartCloud Orchestrator. The custom plug-ins can be added to the SmartCloud
Orchestrator catalog where they are used to add components, links, and policies to
virtual applications.
Samples on page 723
Use these samples to help you learn how to develop custom plug-ins. The plug-ins
that you develop can be added to the SmartCloud Orchestrator catalog and used
as components, links and policies for virtual applications.
728 IBM SmartCloud Orchestrator 2.3: User's Guide
Sample: Import a plug-in and pattern type into SmartCloud Orchestrator:
This topic is an example of how to import your sample plug-in into SmartCloud
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
SmartCloud Orchestrator.
1. Import pattern type patterntypetest.hello.
a. Log in into SmartCloud Orchestrator as administrator or as a user with
permission to create a new pattern type.
b. Click 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 SmartCloud Orchestrator
catalog.
What to do next
Create an application that can be deployed to SmartCloud Orchestrator.
Related tasks:
Developing plug-ins on page 666
Plug-ins define the components, links, and policies that you use in the Virtual
Application 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.
Working with virtual application pattern plug-ins on page 605
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.
Chapter 6. Managing and deploying virtual patterns 729
Sample: Setting up the plug-in development environment on page 725
Set up the environment for the plug-in Samples.
Sample: Developing a plug-in and pattern type with the Eclipse Framework on
page 727
This topic is an example of how to create a plug-in and pattern type using the
Eclipse Framework.
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 SmartCloud Orchestrator.
Sample: Building a single plug-in and pattern type with the command-line tools
on page 734
This topic is an example of how to create a plug-in and pattern type using
command-line tools.
Related reference:
Plug-in development guide on page 676
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.
Plug-in Development Kit on page 671
The Plug-in Development Kit (PDK) is designed to help you build plug-ins for
SmartCloud Orchestrator. The custom plug-ins can be added to the SmartCloud
Orchestrator catalog where they are used to add components, links, and policies to
virtual applications.
Samples on page 723
Use these samples to help you learn how to develop custom plug-ins. The plug-ins
that you develop can be added to the SmartCloud Orchestrator catalog and used
as components, links and policies for virtual applications.
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 SmartCloud Orchestrator.
Before you begin
Set up your development environment and develop a plug-in and pattern type.
About this task
To create an application with the plug-ins, complete the following steps:
Procedure
1. Click Images & Patterns > 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 Virtual Application Builder displays in a new
window.
6. Select the Diagram tab.
730 IBM SmartCloud Orchestrator 2.3: User's Guide
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.
The application displays in the list located on the left.
16. 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.
17. To view the deployed application, click Instances > Virtual Application
Instances. The Virtual Application Instances window displays.
18. Select the virtual_application_instance. The details view displays to the right.
19. Find the row of Hello_Plugin-HVM-XXXX, where XXXX is a set of digits in the
virtual machine list.
20. 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_Plugin-
HVM.XXXX.hello" > console.log.
The following information is provided:
[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 SmartCloud Orchestrator.
What to do next
Monitor the virtual application instance.
Related tasks:
Developing plug-ins on page 666
Plug-ins define the components, links, and policies that you use in the Virtual
Application 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
Chapter 6. Managing and deploying virtual patterns 731
enhance and customize the operation of their virtual applications.
Working with virtual application pattern plug-ins on page 605
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.
Sample: Setting up the plug-in development environment on page 725
Set up the environment for the plug-in Samples.
Sample: Developing a plug-in and pattern type with the Eclipse Framework on
page 727
This topic is an example of how to create a plug-in and pattern type using the
Eclipse Framework.
Sample: Import a plug-in and pattern type into SmartCloud Orchestrator on
page 729
This topic is an example of how to import your sample plug-in into SmartCloud
Orchestrator
Sample: Building a single plug-in and pattern type with the command-line tools
on page 734
This topic is an example of how to create a plug-in and pattern type using
command-line tools.
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.
Related reference:
Plug-in development guide on page 676
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.
Plug-in Development Kit on page 671
The Plug-in Development Kit (PDK) is designed to help you build plug-ins for
SmartCloud Orchestrator. The custom plug-ins can be added to the SmartCloud
Orchestrator catalog where they are used to add components, links, and policies to
virtual applications.
Samples on page 723
Use these samples to help you learn how to develop custom plug-ins. The plug-ins
that you develop can be added to the SmartCloud Orchestrator catalog and used
as components, links and policies for virtual applications.
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
732 IBM SmartCloud Orchestrator 2.3: User's Guide
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
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.
Related tasks:
Developing plug-ins on page 666
Plug-ins define the components, links, and policies that you use in the Virtual
Application 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.
Working with virtual application pattern plug-ins on page 605
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.
Sample: Setting up the plug-in development environment on page 725
Set up the environment for the plug-in Samples.
Related reference:
Plug-in development guide on page 676
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.
Chapter 6. Managing and deploying virtual patterns 733
Plug-in Development Kit on page 671
The Plug-in Development Kit (PDK) is designed to help you build plug-ins for
SmartCloud Orchestrator. The custom plug-ins can be added to the SmartCloud
Orchestrator catalog where they are used to add components, links, and policies to
virtual applications.
Samples on page 723
Use these samples to help you learn how to develop custom plug-ins. The plug-ins
that you develop can be added to the SmartCloud Orchestrator catalog and used
as components, links and policies for virtual applications.
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.
Related tasks:
734 IBM SmartCloud Orchestrator 2.3: User's Guide
Developing plug-ins on page 666
Plug-ins define the components, links, and policies that you use in the Virtual
Application 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.
Working with virtual application pattern plug-ins on page 605
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.
Sample: Setting up the plug-in development environment on page 725
Set up the environment for the plug-in Samples.
Related reference:
Plug-in development guide on page 676
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.
Plug-in Development Kit on page 671
The Plug-in Development Kit (PDK) is designed to help you build plug-ins for
SmartCloud Orchestrator. The custom plug-ins can be added to the SmartCloud
Orchestrator catalog where they are used to add components, links, and policies to
virtual applications.
Samples on page 723
Use these samples to help you learn how to develop custom plug-ins. The plug-ins
that you develop can be added to the SmartCloud Orchestrator catalog and used
as components, links and policies for virtual applications.
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
Virtual Application Builder or they might already exist in the pattern.
A deployed virtual application is called a virtual application instance.
Chapter 6. Managing and deploying virtual patterns 735
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. Add the base image into the catalog. For information about adding images, see
Importing a virtual image to the catalog on page 289 and Registering a
virtual image on page 290.
2. Set the base image as the default. Click Configuration > Default Deploy
Settings. The Settings for Default Deploy window is displayed.
3. Click Change and select an image.
4. Click Update to save your changes.
Note: You can also specify a default base image for a specific cloud group in the
Default image field in the Cloud Groups window. You must define a default base
image for each cloud group if you have a multiple region environment with
different types of hypervisor and you cannot use the same base image for all the
regions. For more information, see Administering cloud groups on page 184.
Create a virtual application.
About this task
When a virtual application is deployed, the Virtual Application 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
736 IBM SmartCloud Orchestrator 2.3: User's Guide
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 Images & Patterns > 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.
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 Virtual Application Builder
confirming that the virtual application is in the deployment process. You can
also check the status of the deployment from this message.
Chapter 6. Managing and deploying virtual patterns 737
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, the virtual application instance is
listed under the Instances section of the SmartCloud Orchestrator. To view the
virtual instance, click Instances > Virtual Application Patterns. 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 Creating new flavors in OpenStack on page 560.
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 69. 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.
738 IBM SmartCloud Orchestrator 2.3: User's Guide
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 Virtual Application
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 751.
Related tasks:
Monitoring virtual application instances on page 751
Use reports and charting to monitor the status and performance of your deployed
virtual application instances and machines.
Terminating virtual machines and reclaiming IP addresses on page 740
A virtual machine that is part of an application deployment can go into Stopped
state. In Stopped state, the IP address that is allocated to that virtual machine
remains "in use" and cannot be allocated to other virtual machines. This is
problematic if the stopped virtual machine is not wanted.
Chapter 6. Managing and deploying virtual patterns 739
Terminating virtual machines and reclaiming IP addresses:
A virtual machine that is part of an application deployment can go into Stopped
state. In Stopped state, the IP address that is allocated to that virtual machine
remains "in use" and cannot be allocated to other virtual machines. This is
problematic if the stopped virtual machine is not wanted.
About this task
IP addresses are listed on the Virtual Application Instances, IP Groups and
Hypervisors product user interface pages.
You can terminate unwanted virtual machines so that the IP address is put back
into the pool of available IP addresses.
To view these user interface pages, click Instances > Virtual application instances
for virtual application instances; Configuration > Hypervisors for hypervisors; and
Configuration > IP Groups for the IP groups.
When a virtual machine is stopped, the IP address is not released. On the IP
Groups page the IP address for the stopped virtual machine is displayed as
Active. This status remains true until the virtual machine is terminated.
To terminate an unwanted virtual machine:
Procedure
1. Click Configuration > Hypervisors > hypervisor. The hypervisor details
display in the user interface.
2. Expand the Virtual machines section on the details page.
3. Locate the stopped virtual machine.
4. Select the Group Actions check box.
5. Click the Group Actions link.
6. Click the Delete icon to terminate the virtual machine.
Results
When the virtual machine is terminated, the IP address associated with the virtual
machine is available for use by other virtual machines. Terminating a virtual
machine causes the SmartCloud Orchestrator recovery rules to take effect. This can
result in the IP address immediately being allocated to a new running virtual
machine.
Related tasks:
Deploying virtual application patterns on page 736
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.
740 IBM SmartCloud Orchestrator 2.3: User's Guide
Deploying virtual application templates
You can directly deploy a virtual application template from the SmartCloud
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 Virtual Application Builder to allocates necessary components,
links and policies to application template.
To deploy a virtual application template:
Procedure
1. Click Components > 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
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
Chapter 6. Managing and deploying virtual patterns 741
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 Virtual Application 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, the virtual application instance is
listed under the Instances section of the SmartCloud Orchestrator. To view the
virtual instance, click Instances > Virtual Application Patterns. 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 70. 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.
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.
742 IBM SmartCloud Orchestrator 2.3: User's Guide
To redeploy a virtual application, select the virtual application from the Virtual
Application Patterns palette, and click the Deploy icon in the Virtual Application
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 751.
Related tasks:
Monitoring virtual application instances on page 751
Use reports and charting to monitor the status and performance of your deployed
virtual application instances and machines.
Terminating virtual machines and reclaiming IP addresses on page 740
A virtual machine that is part of an application deployment can go into Stopped
state. In Stopped state, the IP address that is allocated to that virtual machine
remains "in use" and cannot be allocated to other virtual machines. This is
problematic if the stopped virtual machine is not wanted.
Deploying virtual application patterns on page 736
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.
Chapter 6. Managing and deploying virtual patterns 743
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 SmartCloud Orchestrator on page 151. 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 747.
v LTPA keys.
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).
SmartCloud 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 SmartCloud 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 Instances > Virtual Application Patterns. The Virtual 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
744 IBM SmartCloud Orchestrator 2.3: User's Guide
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.
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: SmartCloud 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 SmartCloud 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
Chapter 6. Managing and deploying virtual patterns 745
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.
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
746 IBM SmartCloud Orchestrator 2.3: User's Guide
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.
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 Virtual Application 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.
Related concepts:
Working with shared services on page 754
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.
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 SmartCloud 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.
Chapter 6. Managing and deploying virtual patterns 747
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 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.
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 Instances > Virtual Application Patterns. The Virtual 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.
748 IBM SmartCloud Orchestrator 2.3: User's Guide
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.
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 SmartCloud Orchestrator to the cloud
environment.
About this task
To manage a virtual application instance:
Procedure
1. Click Instances > All 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
Instances > All 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 71. 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.
Chapter 6. Managing and deploying virtual patterns 749
Table 71. Possible status values for a deployed virtual application (continued)
Status Deployment description Virtual machine description
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.
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 752.
7. Click Manage in the upper 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 upper right. For more
information about monitoring, see Monitoring virtual application instances
on page 751.
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 Virtual Application
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>
750 IBM SmartCloud Orchestrator 2.3: User's Guide
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.
Related tasks:
Monitoring virtual application instances
Use reports and charting to monitor the status and performance of your deployed
virtual application instances and machines.
Viewing virtual application instance logs on page 752
You can view logs of the virtual application instances.
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 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.
Chapter 6. Managing and deploying virtual patterns 751
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 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 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.
752 IBM SmartCloud Orchestrator 2.3: User's Guide
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
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.
Using the command-line interface for applications
You can use the command-line interface to manage your virtual application
patterns, pattern types, virtual application instances and plug-ins.
About this task
See the following sections:
v Pattern type command-line interface
v Virtual application pattern command-line interface
v Virtual application instance command-line interface
Chapter 6. Managing and deploying virtual patterns 753
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 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 SmartCloud Orchestrator user interface to deploy and manage shared
services.
Before you begin
To view shared services, you must be assigned the admin role.
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.
You can use either the user interface or the command-line interface to manage
your shared services.
To learn more about using the command-line interface see Using the
command-line interface for applications on page 753.
To deploy a shared service, complete the following steps:
Procedure
1. Click 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.
754 IBM SmartCloud Orchestrator 2.3: User's Guide
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 Virtual Application window is displayed.
6. Complete the following fields to deploy the application as a shared service:
v 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.
v Target environment profile: Provides information related to 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.
v SSH Key: If you want to upload a public key so that you can connect to the
deployed virtual machines using SSH, select the Advanced check box 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
Click here to download the file containing the private key and you can
save the private key to your local system.
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 SmartCloud Orchestrator user interface to monitor the shared service
instances that you deployed in your environment.
Complete the following steps:
1. Click Instances > Shared Services.
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.
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.
Chapter 6. Managing and deploying virtual patterns 755
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 Configuration > Shared Services.
2. In the left pane of the Shared Services window, select the Monitoring-
Application 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 environment profile.
7. Expand the Advanced section 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.
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.
756 IBM SmartCloud Orchestrator 2.3: User's Guide
Enabling TOSCA support for SmartCloud Orchestrator
SmartCloud 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
TOSCA support can be enabled by installing and enabling a pattern type TOSCA
Foundation Pattern Type. By default, this pattern type is installed in SmartCloud
Orchestrator but it is disabled. To enable TOSCA support in your environment, you
must first enable this pattern type.
Procedure
1. Log on to SmartCloud Orchestrator user interface as administrator.
2. Click Configuration > Pattern Types.
3. Find the TOSCA Foundation Pattern Type entry in the list on the left. This
entry is disabled by default.
4. Click the entry and select Enable from the Status field.
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 > Virtual Applications, or as Virtual Application Templates by navigating
to Catalog > Virtual Application Templates.
Remember: In SmartCloud 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, remember that you must perform the basic configuration for virtual
application patterns, such as configuration of cloud groups or import of base
images.
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
The configuration of an RPM repository is necessary because virtual machines
deployed into private clouds typically do not have 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 which you can use to specify all the parameters of an RPM repository.
Chapter 6. Managing and deploying virtual patterns 757
Procedure
1. Log on to SmartCloud Orchestrator user interface as administrator.
2. Click Configuration > System Plug-ins.
3. From the dropdown box on the left, select TOSCA Foundation Pattern Type
1.0.0.0 to define the pattern type.
4. From the list on the left, select the tosca.rpmrepository 1.0.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 one of 3 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 on page 757.
Procedure
1. From the Repository Type drop-down box, select the option ISO Image on
NFS.
2. Provide the following parameters:
Repository Name
This parameter specifies the name of the repository that will be configured
in the operating system of deployed virtual machines, for example
RHEL_6.2_Repo.
Mount point for ISO Image
This parameter specifies a mount point that will be 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.
758 IBM SmartCloud Orchestrator 2.3: User's Guide
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 757.
Procedure
1. From the Repository Type drop-down box, select the option FTP.
2. Provide the following parameters:
Repository Name
This parameter specifies the name of the repository that will be 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 757.
Procedure
1. From the Repository Type drop-down box, select the option HTTP.
2. Provide the following parameters:
Repository Name
This parameter specifies the name of the repository that will be 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 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.
Chapter 6. Managing and deploying virtual patterns 759
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 757.
2. From the Repository Type drop-down box, 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
This topic describes how to configure the use of Chef automation in context of
TOSCA patterns. The TOSCA Chef support inside SmartCloud Orchestrator is a
plug-in as part of the TOSCA Foundation Pattern Type.
About this task
For providing a maximum of flexibility, a Chef client can be configured for use
with the TOSCA Chef plug-in, in the required version. Out of the box there is no
Chef client shipped with SmartCloud Orchestrator. For configuring the chef client
for use with virtual application patterns, perform this procedure.
Procedure
1. Upload the required Chef client RPM to a repository:
For using Chef with virtual application patterns, an RPM containing a Chef
client must be uploaded. The Chef client RPM can be retrieved from Opscode.
In this version of SmartCloud Orchestrator only the use of Chef RPM packages
is supported. When TOSCA service templates, imported as virtual application
patterns using Chef, are deployed, the Chef RPM is downloaded from a
repository using wget.
As a default the http server on the Central Server 1 can be used. For uploading
the client RPM, login to your Central Server 1 using SSH:
a. Create a subdirectory in /data/repos/scp/, for example chefRpm by running
the mkdir /data/repos/scp/chefRpm command.
The path /data/repos/scp is the path for the default http server. You can
choose the name of the chefRpm subdirectory according to requirements.
b. Copy the Chef RPM, that you retrieved from Opscode before, to the
/data/repos/scp/chefRpm directory on the Central Server 1 virtual machine
that you created in the previous step.
760 IBM SmartCloud Orchestrator 2.3: User's Guide
Using a different http server than the default http server on the Central Server
1 works as well, as long as there is a working connection between the deployed
virtual machines and the http server.
The uploaded RPM is used during the deployment of virtual application
patterns imported from TOSCA services templates for installing the Chef client
on virtual machines so that Chef recipes can be run.
2. Configure the TOSCA Chef Plug-in repository:
To configure the path to the http repository, containing the Chef client RPM,
log on to the SmartCloud Orchestrator UI:
v Go to Configuration > System Plugins and choose the tosca.chef plug-in.
v Click the Configure button in the upper right corner. The configuration
options for the TOSCA Chef plug-in appears.
v Choose Chef Deployment Mode: Chef Solo, as TOSCA service templates,
imported as virtual application patterns, are using Chef Solo deployments.
v Enter the full URL of the Chef client RPM in the Chef Client HTTP Address
field. For example:
http://<Central Server 1>/scp/chefRpm/chef-11.6.0-1.el6.x86_64.rpm
where <Central Server 1> is the IP address or hostname of the SmartCloud
Orchestrator Central Server 1. The TOSCA service template, imported as
virtual application pattern, will use this address for downloading the RPM
from the repository when installing.
Chapter 6. Managing and deploying virtual patterns 761
762 IBM SmartCloud Orchestrator 2.3: User's Guide
Chapter 7. Managing orchestration workflows
Create custom orchestration workflows in the Business Process Manager user
interface and run them in your SmartCloud Orchestrator environment.
Orchestration workflows
You can use three types of orchestration workflows:
v Self-service offerings on page 764: 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 User actions on page 764: These workflows are used to define additional
actions that cloud users can run on a given running instance. You can initiate
these actions with the More Actions menu available in Instance view in the
SmartCloud Orchestrator user interface.
v Event-triggered actions on page 765: These workflows are called during the
deployment cycle at various points (such as, before and after virtual systems are
started) so that the deployment process can be customized, enhanced or
overridden in some way.
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. The service can be started either by
events triggered by SmartCloud Orchestrator management actions or by user
actions in the SmartCloud 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 a SmartCloud
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
Copyright IBM Corp. 2013, 2014 763
v Virtual application ID
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 SmartCloud
Orchestrator Content Development Guide.
Workflows can throw error events or post-status messages, which are then shown
in the SmartCloud Orchestrator user interface. For more information about errors,
see the SmartCloud 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 SmartCloud Orchestrator. You
can develop these extensions using Business Process Manager Process Designer
and then add them as offerings in SmartCloud Orchestrator Configuration tab. 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 panel, where they are grouped into
categories.
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.
You can view the list of all available user actions in the Instance Details View
panel in Images & Patterns > Virtual Systems Patterns.
Note: The list of predefined actions that you can perform does not include system
backup. You can implement this functionality as a user action.
764 IBM SmartCloud Orchestrator 2.3: User's Guide
Event-triggered actions
Event-triggered actions are Business Process Manager business processes that are
triggered by a specified event during a predefined management action.
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
Samples and standard extensions for orchestration workflows
SmartCloud 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
SmartCloud 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 SmartCloud Orchestrator.
The Sample_Support_vSys_ProcessApp process application is a sample that
demonstrates how to deploy and delete virtual system patterns.
You can also search for additional samples in the IBM Cloud Marketplace at
https://www-304.ibm.com/software/brandcatalog/ismlibrary/cloudmarketplace.
Cloud Marketplace is a platform and one-stop-shop for IBM SmartCloud
customers, partners, and IBMers, where developers, partners, and IBM Service
teams continuously share content among one another.
Chapter 7. Managing orchestration workflows 765
Scripts and web services
If the available pre-built automation routines do not meet your needs, you can also
use your own scripts within the workflow, or invoke a web service API.
The SCOrchestrator_Scripting_Utilities_Toolkit provides toolkit services that
you can drag and drop during process creation. You can simply drag the execute
script from that toolkit into your flow, and then specify the script, and any other
required parameters.
The SmartCloud Orchestrator IaaS support toolkit provides an essential Java REST
client API and samples that show how to use the API in business processes. You
can invoke a web service API directly. In this way, you can access to a wide variety
of tools and services within your company or those that are available in the
Internet.
Advanced programming
If you want to create much more sophisticated automation, involving using richer
programming languages, refer to the IBM SmartCloud Orchestrator Content
Development Guide.
Working with Business Process Manager
You can use Business Process Manager processes to extend the capabilities of
SmartCloud Orchestrator.
About this task
Business Process Manager provides two user interfaces with which you can work
to extend the capabilities of SmartCloud 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 SmartCloud
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 SmartCloud Orchestrator. Pre-built sample artifacts are
provided in Business Process Manager to make process creation quick and easy.
For detailed information on IBM Business Process Manager, refer to the
information center at http://pic.dhe.ibm.com/infocenter/dmndhelp/v8r5m0/
topic/com.ibm.wbpm.main.doc/ic-homepage-bpm.html.
Setting up IBM Process Designer
Install, configure and log in to IBM Process Designer.
IBM Process Designer is a stand-alone, local application that you install on a
Windows computer.
1. In a web browser, log on to SmartCloud Orchestrator as user admin and with
the password set for admin during installation.
766 IBM SmartCloud Orchestrator 2.3: User's Guide
2. Click Administration > Process Center. The Process Center web application
opens in a new tab.
3. Install Process Designer on a Windows machine on which you will 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.
4. Click Start > IBM Process Designer Edition > Process Designer and log on as
user admin with password passw0rd.
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, you 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 SmartCloud Orchestrator user to be able to use Process
Designer, you must grant it access to the Process Center repository.
1. Open Business Process Manager Process Designer or Process Center.
2. Go to Admin > Manage Users.
3. Click Add Users/Groups on the right side of the panel. A dialog box opens.
4. In the Search for Name box, enter the user name.
5. Select your user in the Results box and click Add selected.
Creating a process application in Process Designer
Create a process application and search through artifacts.
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.
Chapter 7. Managing orchestration workflows 767
SmartCloud 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 SmartCloud 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.
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.
Tip: In the Toolkits tab, notice SCOrchestrator_Toolkit.
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: Once the process application is created, do not change its
acronym, as it is used to reference the processes in self-service offerings.
c. Click Create.
Tip: Steps 2a-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.
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
drop-down list to 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.
768 IBM SmartCloud Orchestrator 2.3: User's Guide
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.
In this task an example of the process application created in Creating a process
application in Process Designer on page 767 is used.
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.
When you open your process application, the Template_HumanService is now
available on the list.
Editing process applications and toolkits
You must be the author of a process application or a toolkit, if you want to edit
them.
Table 72. 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.
In this task, you will create a sample process called "Hello World". You can modify
this procedure to suit your needs.
1. In the Designer view, click the newly created process application and then
click the plus icon next to Processes to open the Create new menu.
2. From the menu, select Business Process Definition.
Chapter 7. Managing orchestration workflows 769
3. In the window that is displayed, 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 as well.
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 and waits for the
user to click OK.
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 will be used to trigger the
transition to the end event.
14. Click Save to save the new human service.
15. From the drop-down 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 that opens, 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.
770 IBM SmartCloud Orchestrator 2.3: User's Guide
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 My Inbox panel in SmartCloud 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 tasks
To approve or reject a selected task, 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
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
SmartCloud Orchestrator.
1. In Business Process Manager, expose the process to make it available in the
SmartCloud 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 SmartCloud 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 SmartCloud Orchestrator, create an offering that is based on the process, and
a category for it:
a. Log on to SmartCloud Orchestrator. You must be assigned the catalogeditor
role or the admin role.
Chapter 7. Managing orchestration workflows 771
If no categories other than All Uncategorized Offerings exist for self-service
offerings, you need to create at least one category. Offerings by default
belong to All Uncategorized Offerings and they cannot be accessed in the
Self-Service panel unless they are moved to another category.
b. Click Configuration > Self-Service Categories.
c. Click the green plus icon to create a category. A new dialog opens where
you can specify its details.
d. Click OK to create the category.
e. Click Configuration > Self-Service Offerings.
f. Click the green plus icon to create an entry. A new dialog opens.
g. Provide a name, and a description for the offering.
h. Select an icon for the offering.
i. Select a category from the list.
j. From the Process drop-down list, select your process.
k. If the selected process requires user interaction, specify a user interface by
selecting the related Human Service.
l. Click OK to create the offering.
m. To allow other users to access the new offering, select the offering and add
the project to which the users belong to the Access granted to field.
The user can now access the offering in the Self-Service panel, and request it.
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.
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 Instances 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.
1. In Business Process Manager, expose the process to make it available in the
SmartCloud 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 SmartCloud Orchestrator.
Tip: A similar procedure must be performed to make a user interface (human
service) visible in SmartCloud 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.
772 IBM SmartCloud Orchestrator 2.3: User's Guide
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 SmartCloud Orchestrator, create an orchestration action based on the process:
a. Log on to SmartCloud Orchestrator. You must be assigned the catalogeditor
role or the admin role.
b. Click Configuration > Orchestration Actions.
c. Click the green plus icon to create a new entry. A new dialog opens.
d. Provide a name and, optionally, a description for the action.
e. From the Action type list, select Event-triggered action or User action.
f. For event-triggered action, specify the event at which the action is to start
automatically.
g. Select one or more virtual system patterns to which the action is applied.
h. Select the process that you exposed in step 1.
i. If the selected process requires user interaction, specify a user interface by
selecting the related Human Service.
j. 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.
k. Click OK to create the action.
l. 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.
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. User action can now be started in the Instances view. If user
interaction is required for the configured action to complete, the user receives a
new assignment in My Inbox panel.
Upgrading a process on a development system or production
system
SmartCloud Orchestrator enables you to distinguish between development mode
and production mode. You can define different upgrade methods for a process,
depending on whether SmartCloud Orchestrator is configured as a development
system or as a production system.
Development mode
When SmartCloud 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 774.
Chapter 7. Managing orchestration workflows 773
Production mode
When SmartCloud 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.
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.
To change SmartCloud Orchestrator from a production system to a development
system, complete the following steps:
1. Log on to the Business Process Manager WebSphere Application Server console
as an administrator user:
https://$central-server-4:9043/ibm/console/logon.jsp
where $central-server-4 is the IP address of Central Server 4.
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.
SmartCloud Orchestrator is now configured as a development system.
Configuring production mode
To configure production mode, SmartCloud Orchestrator must be manually
configured to use a snapshot instead of the latest version of code.
774 IBM SmartCloud Orchestrator 2.3: User's Guide
To configure SmartCloud Orchestrator as a production system, create a property in
Business Process Manager to define the operational mode, as follows:
1. Log on to the Business Process Manager WebSphere Application Server console
as an administrator user:
https://$central-server-4:9043/ibm/console/logon.jsp
where $central-server-4 is the IP address of Central Server 4.
2. In the console navigation tree, click Servers > Server Types > WebSphere
application servers > server_name > Process definition > Java Virtual
Machine > Custom properties.
3. Click New to create a new variable called ORCHESTRATOR_DEVELOPMENT_MODE.
4. To specify production mode, set the value of the
ORCHESTRATOR_DEVELOPMENT_MODE variable to false.
5. Set the description of the ORCHESTRATOR_DEVELOPMENT_MODE variable to Activate
Production Mode.
6. Restart the Business Process Manager server.
Optional: To specify a default snapshot for a process application, complete the
following steps:
7. 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.
8. 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.
SmartCloud 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.
Chapter 7. Managing orchestration workflows 775
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.
AA The SmartCloud Orchestrator release that is prerequisite for the toolkit
or process application, for example. 23 for SmartCloud Orchestrator 2.3
BB Counting up the version of the toolkit, for example. 00 for the first
release, and 01 for the second release
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 SmartCloud 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 SmartCloud 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.
776 IBM SmartCloud Orchestrator 2.3: User's Guide
Guidelines to structure your solution
v In general, an extension content solution for SmartCloud 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.
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
A 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 SmartCloud 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:
Chapter 7. Managing orchestration workflows 777
http://www.scribd.com/doc/92505753/IBM-Impact-2011-Five-Guidelines-to-
Better-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
778 IBM SmartCloud Orchestrator 2.3: User's Guide
Chapter 8. Working with self-service
SmartCloud Orchestrator provides an intuitive Self-Service panel, which allows
users to quickly request self-service offerings and monitor their requests. You can
populate the catalog with your offerings and categorize them to meet the needs of
cloud users.
Managing self-service offerings
Create self-service offerings and use them to customize your SmartCloud
Orchestrator environment.
Adding offerings
After you define a new self-service offering in Business Process Manager, you can
add it to SmartCloud Orchestrator.
Before you begin
You must be assigned the catalogeditor role or the admin role.
Procedure
1. Click Self-Service. Navigate to the category Service Composition.
2. Click the self-service offering Create Offering.
3. Specify the name of the new offering.
4. Optional: Provide a description.
5. Optional: Select an icon for your offering. The icon is displayed for this offering
in the Self-Service panel.
6. Select a self-service category.
7. Optional: Select a process application or toolkit to filter the list of processes in
step 8.
8. From the list, select a defined Business Process Manager process that
implements the custom offering.
9. Optional: Select a defined Business Process Manager human service that
implements the graphical user interface for the custom offering. The list
includes only those human services that can be associated with the selected
process.
Categorizing self-service offerings
You can organize the self-service offerings into groups called categories, so that the
users can easily navigate the Self-Service panel.
Before you begin
You must be assigned the catalogeditor role or the admin role.
About this task
Categories are groups of offerings which are logically related or which are related
based on users' needs.
Copyright IBM Corp. 2013, 2014 779
Procedure
1. Click Self-Service. Navigate to the category Service Composition.
2. Click the self-service offering Create Category.
3. Assign a name, description and select a graphical icon for the category.
4. Add offerings to your new category:
a. Click Configuration > Self-Service Offerings.
b. Select the offering that you want to add.
c. In the Category field, select the newly created category from the list.
d. Repeat these steps for all the offerings that you want to add.
Results
New category is now available in the Self-Service panel, and the specified offerings
are grouped in this category.
Modifying self-service offerings
You can modify certain fields of the existing self-service offering in the
Configuration menu of SmartCloud Orchestrator.
Procedure
1. In SmartCloud Orchestrator, click Configuration > Self-Service Offerings.
2. Select the offering that you want to modify. Offering details are displayed on
the right side of the screen. You can change them in this view.
3. Modify the properties as required:
v Offering name: Click the name of the offering and a text field is displayed.
v Description: Click the description of the offering and a text field is
displayed.
v Offering icon: Open the drop-down list and select the icon of your choice.
4. In the Access granted to field, grant or remove the access to the selected
self-service offering to a user by adding or removing the project to which the
user belongs.
Using self-service
In the Self-Service panel of SmartCloud Orchestrator, you can quickly request
offerings, monitor the status of your requests, and perform additional tasks related
to a request.
Navigating the Self-Service panel
You can access the available offerings in the Self-Service panel. The offerings are
grouped in categories. You can also review your requests and view any pending
tasks that you must complete to fulfill the request.
1. Log on to the SmartCloud Orchestrator application.
2. To access the list of offerings, click the Self-Service tab. The list of service
categories is displayed. You can click any category to view the requests in this
category. You can also use the Search field to look up a specific offering.
3. To review the list of your submitted requests, click the My Requests tab. The
list of requests and their statuses is displayed on the left. You can click any of
the items to view details.
780 IBM SmartCloud Orchestrator 2.3: User's Guide
4. To view any pending tasks that need to be completed to resolve the request,
click the My Inbox tab. Select a task from the list on the left to open it. Use the
action buttons on the toolbar to process the task.
Tip: You can also use the box on the right side of the Self-Service panel to
access My Requests and My Inbox.
Submitting a self-service request
Use SmartCloud Orchestrator to easily submit a self-service request.
Procedure
1. Log on to SmartCloud Orchestrator and click the Self-Service 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 its 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 request status in My Requests tab.
Viewing the status of your requests
You can review the status of the request that you submitted in the My Requests
panel.
About this task
Users can view the progress of all actions they submitted from the Self-Service
panel. Administrators are able to view all the requests they submitted, as well as
the requests from the users they administer.
Note: The My Requests panel shows only those requests that were submitted in
the Self-Service panel. Completed requests are automatically removed from the
view after two weeks.
Procedure
1. Click My Requests tab. All requests that you have access to are displayed on
the left side of the page.
2. Click on any request to view its details.
Results
The following details are displayed for a request:
v Request ID: Unique identifier of the request.
v Submitted on: The date when the request was submitted.
v Submitted by: ID of the user who submitted the request.
v Detailed information: This is a description of the request.
v Status: The processing status of the request. The request can have one of the
following statuses: New, Pending, Queued, Suspended, Running, Completing,
Completed, Failing, Failed, Canceling, Canceled.
Chapter 8. Working with self-service 781
v Status message: A message completing the status to provide more information to
the user.
Completing an assignment in My Inbox
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 on to SmartCloud Orchestrator and click the My Inbox tab. A list of
assignments that require user interaction are displayed. There are the following
types of assignments:
v Approval task
v General task
You can click on the assignment icon to see details about it.
2. The assignment can be in 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 task, click Accept or Reject. You can
optionally enter a reason.
A completion message is displayed and the assignment is deleted from the My
Inbox window.
782 IBM SmartCloud Orchestrator 2.3: User's Guide
Chapter 9. Integrating
Learn how to integrate SmartCloud Orchestrator with the following IBM products.
Integrating with IBM Tivoli Monitoring
To integrate SmartCloud 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
SmartCloud Orchestrator environment.
Preparing a base operating system
IBM Tivoli Monitoring 6.3.0 supports several operating systems, but the
SmartCloud Orchestrator solution is based on Red Hat Enterprise Linux (RHEL)
6.3, 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, 2014 783
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 DB2 10.1 Installation Guide.
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
784 IBM SmartCloud Orchestrator 2.3: User's Guide
Dashboard and JazzSM are new components of Tivoli Monitoring 6.3.0.1
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. All of its
components can also be installed in silent mode.
The following packages are required to install IBM Tivoli Monitoring 6.3.0.1:
v CIL2AEN - IBM Tivoli Monitoring V6.3.0.1 Base, Linux (64-bit Env.), English
v CIL2HML - IBM Tivoli Monitoring V6.3.0.1 Dashboards for Servers and
Authorization Policy Components Assembly Multiplatform, Multilingual
v CIGL8ML - IBM Tivoli Monitoring V6.3.0.1 Language Support
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
v Summarization and Pruning Agent: modify the sy_silent_config.txt file with
the following information:
Chapter 9. Integrating 785
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.
3. On local DB2 on which ITM is installed, catalog a remote data warehouse.
786 IBM SmartCloud Orchestrator 2.3: User's Guide
Monitoring Agent for Linux
To monitor the whole SmartCloud Orchestrator environment, you must 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 CIGM1EN - IBM Tivoli Monitoring V6.3.0 Agents, Multiplatform, English
If you want to use silent mode for installing and configuring 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 TEMS server, you must 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 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 CIGN0EN - IBM Tivoli Monitoring for Virtual Environments V7.2 VMware VI,
KVM, NetApp Storage and NMA Agents and Support files (TMVE), Windows
and Linux, English, Multiplatform
v CIGN2ML - IBM Tivoli Monitoring for Virtual Environments V7.2 Agent
Language Pack (TMVE), 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:
INSTALL_PRODUCT=v1
INSTALL_PRODUCT_TMS=all
INSTALL_PRODUCT_TPS=all
Chapter 9. Integrating 787
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.
Installing Image Construction and Composition Tool bundle to
deploy Tivoli Monitoring agents
You can use the IBM Image Construction and Composition Tool bundle to install
and configure the Tivoli Monitoring agents that help you monitor the performance
and availability of distributed operating systems and applications.
Before you begin
Install the following packages for the Linux operating system:
v libstdc++
v libgcc
v compat-libstdc++
v libXp
Install the following libraries:
v compat-libstdc++-296.2.96.i386
v compat-libgcc-296.2.96.i386
v compat-libstdc++-33.3.2.3.x86_64
v compat-libstdc++-33.3.2.3.i386
v libXpm-3.5.5-3
788 IBM SmartCloud Orchestrator 2.3: User's Guide
Install the following packages that are required to run the software bundle
successfully:
v KornShell (KSH)
v Network File System (NFS)
v libstdc++-33-3.2.3-69.el6.i686
v libstdc++-4.4.6-4.el6.i686
Note: After you have applied the RPMs, check the prerequisites of your image as
described in the Prerequisites for KVM or VMware images topic.
Procedure
1. Download the ICCT Bundle to deploy IBM Tivoli Monitoring Agent for Linux
OS v6.X.
2. Download IBM Tivoli Monitoring and put the extracted files in the NFS
repository.
3. Prepare a SUSE Linux Enterprise Server (SLES) base image.
4. Import the software bundle to Image Construction and Composition Tool:
a. Go to Images and bundles > Build and manage software bundles.
b. Click the import icon and specify the file location.
5. In the Install tab of the mountSoftwarebinaries bundle, provide your NFS
repository information.
6. In the Install tab of the IBM Tivoli Monitoring agent bundle, provide the
details for itm_install_cfg, itm_network_mount, and itm_rel_path. These
values are specific to your environment.
7. Depending on the ports that you intend to use for IBM Tivoli Monitoring,
ensure that you create an entry for those ports in the Firewall tab of the
bundle.
8. Add the software bundle to the extended image:
a. Go to Images and bundles > Build and manage images.
b. Select the image to extend and click the pencil icon to edit the image.
c. Expand Software Bundles and click Add bundle.
d. Select the bundle to add from the list of all bundles in Image Construction
and Composition Tool.
Restriction: Make sure that the mountSoftwarebinaries bundle is first in the
selection list because the IBM Tivoli Monitoring agent bundle depends on it.
e. Finish editing and save the image.
9. Synchronize the image and capture it from Image Construction and
Composition Tool.
Related concepts:
Working with IBM Image Construction and Composition Tool
Use the Image Construction and Composition Tool to build virtual images for
deployment into cloud environments. Experts build particular software bundles for
reuse by others. This simplifies the complexity of image creation and reduces
errors. You can reuse and manage images and software in a cloud environment
and build and share images that are self-descriptive, customizable, and
manageable.
Chapter 9. Integrating 789
Integrating with IBM Endpoint Manager
To integrate SmartCloud 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 SmartCloud 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 SmartCloud Orchestrator.
Note: Install and set up IBM DB2 Enterprise Server Edition V10.1 to support
SmartCloud Orchestrator. If you subsequently install IBM Endpoint Manager, do
not install the IBM DB2 Workgroup Server Edition V10.1 that is included with IBM
Endpoint Manager. Continue to use the IBM DB2 Enterprise Server Edition V10.1,
because IBM Endpoint Manager will be used in the context of SmartCloud
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/TEMAgentDeployment-1.0.282-
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 SmartCloud 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 SmartCloud 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
790 IBM SmartCloud Orchestrator 2.3: User's Guide
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 SmartCloud Orchestrator.
Endpoint Manager install agent script package
A script package is a .zip file that contains the executable file and all associated
files for the script package. The .zip 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
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 will configure and run the Endpoint
Management agent installer file:
Chapter 9. Integrating 791
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>".
This will group 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, it will also configure an environment variable which will be 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 hostname 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
792 IBM SmartCloud Orchestrator 2.3: User's Guide
# 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
/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.0-
rhe5.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"
}
]
}
]
Chapter 9. Integrating 793
v The script package name should 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.
BESAgent-8.5.6666.0-rhe5.x86_64.rpm - the agent installer for Red Hat Linux.
install.sh.
cbscript.json.
v Import the script package zip file into SmartCloud Orchestrator and keep the
default setting Executes at virtual system creation.
v Create a pattern containing a Red Hat Linux 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 that
the agent is installed correctly review the log files.
v Once the agent has registered with the Endpoint Manager server the computer
system information will be displayed in the Endpoint Manager console.
v If a group has been configured and set, the computer will also be displayed
under the specific group heading in the Endpoint Manager console.
v Patch management can now be performed.
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, it will also configure an environment variable which will be
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 hostname 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
794 IBM SmartCloud Orchestrator 2.3: User's Guide
# 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)
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 the name specified in the file below
matches the script package zip name, for example, IEM_8.2.1175.0-
sle11.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 should 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.
Chapter 9. Integrating 795
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 SmartCloud 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 Once the agent has registered with the Endpoint Manager server the computer
system information will be displayed in the Endpoint Manager console.
v If a group has been configured and set, the computer will also be displayed
under the specific group heading in the Endpoint Manager console.
v Patch management can now be performed.
Example script package to install an Endpoint Manager agent on
Windows
This script package installs an Endpoint Manager agent on a Windows system, it
will also configure an environment variable which will be 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 installation folder. The file is named setup.exe:
C:\Program Files (x86)\BigFix Enterprise\BES Console\BESClientDeploy\BigFixInstallSource\ClientInstaller.
v Create the install.bat script as follows, replacing the <SERVER IP> and
<SERVER HOSTNAME> placeholders with the correct IP and hostname 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
796 IBM SmartCloud Orchestrator 2.3: User's Guide
: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 the name specified in the file below
matches the script package zip name, for example, IEM_8.2.1175.0-
windows_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":
[
{
"scriptkey": "_BESCLIENT_GROUP_NAME",
"scriptvalue": "",
"scriptdefaultvalue": "none"
}
]
}
]
v The script package name should 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 SmartCloud 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 will run 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 will be displayed in the Endpoint Manager console.
Chapter 9. Integrating 797
v If a group has been configured and set, the computer will also be displayed
under the specific group heading in the Endpoint Manager console.
v Patch management can now be performed.
Troubleshooting
If the Endpoint Manager agent fails to register with the Endpoint Manager server,
check the following:
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.
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 hostname resolves to the correct IP address, verify the values in
the hosts file.
798 IBM SmartCloud Orchestrator 2.3: User's Guide
Chapter 10. Reporting
SmartCloud Orchestrator provides a diverse set of reports that provide specific
data you can use for planning purposes.
Before you begin
You must be assigned the admin role to complete these steps.
About this task
You can view reports on virtual machine activity for your SmartCloud
Orchestrator.
Procedure
1. Generate reports. From the menu, click Reports and choose an option.
2. Choose one of the following options:
Machine Activity
Provides system usage reports to track the resources being used in the
cloud. See Machine activity reporting on page 800 for more
information.
User Activity
Provides reports to track the user activity in the clouds that are
managed by SmartCloud Orchestrator. See User activity reporting on
page 801 for more information.
Results
After completing these steps, you have reviewed the available reports.
What to do next
To see additional information about your system activity, review the audit data
available for your SmartCloud Orchestrator. See Retrieving audit data with the
user interface on page 278 for more information about auditing.
Related tasks:
Chapter 12, Troubleshooting, on page 1077
Troubleshooting tools have been collected for ease of use when attempting to
debug an issue.
Copyright IBM Corp. 2013, 2014 799
Machine activity reporting
System usage reports, to track the resources being used in the cloud, are provided
by SmartCloud Orchestrator. A diverse set of reports is available to provide specific
data you can use for planning purposes. Your system usage reports are generated
to track both physical and virtual resource utilization.
Before you begin
You must be assigned the admin role to complete these steps.
About this task
You can view reports on virtual machine activity for your product.
Procedure
1. Open the Machine Activity page. From the menu, click Reports > Machine
Activity. A list of the available reports is displayed in the left pane of user
interface.
2. Click the <report_name> to generate and view a specific report. After clicking
the <report_name> to select the report, the report is generated with the default
settings. The default setting is to include one month's data to the current date
for each hypervisor or virtual machine. You can view the following reports:
CPU Usage by Hypervisor
This report provides information about the percent of the processor that
is being used for each hypervisor. The following information is listed
for each report and charts are also used to visually represent this
information:
v Name
v Average
v Maximum
The default chart shows the average processor usage. Click Maximum
to see the chart representing maximum processor usage.
Memory Usage by Hypervisor
The Memory Usage by Hypervisor report provides information about
the percent of the memory that is being used for each hypervisor. The
following fields and charts visually represent this information for each
report:
v Name
v Average
v Maximum
The default chart displays the average memory usage. Click to
Maximum to display the chart representing maximum memory usage.
Storage Usage by Device
The Storage Usage by Device report provides information about the
percent of storage that is being used. Storage is defined for each
hypervisor. The following fields and charts visually represent this
information for each report:
v Name
v Average
v Maximum
800 IBM SmartCloud Orchestrator 2.3: User's Guide
The format of the name is <storage device name> (<hypervisor id>).
The default chart displays the average storage usage. Click to
Maximum to display the chart representing maximum storage usage.
IP Usage in the Cloud
The IP Usage in the Cloud report provides information about the
percent of the IP address that are being used. The following fields and
charts visually represent this information for each report:
v Name
v Average
v Maximum
The default chart displays the average IP usage. Click to Maximum to
display the chart representing maximum IP usage.
3. Optional: To generate the report for a specific time range, adjust the date range
in the From and To fields and click Update.
Results
After completing these steps, you have reviewed the available reports for your
product.
What to do next
To see additional information about your system activity, review the audit data
available for your product. See Retrieving audit data with the user interface on
page 278 for more information about auditing.
Related tasks:
Chapter 12, Troubleshooting, on page 1077
Troubleshooting tools have been collected for ease of use when attempting to
debug an issue.
User activity reporting
You can access reports to track the user activity in the clouds that are managed by
SmartCloud Orchestrator.
Before you begin
You must be assigned the admin role to complete these steps.
About this task
Use the steps in this article to view a report on user activity in the clouds managed
by your SmartCloud Orchestrator. The usage activity report displays the high
water mark of physical and virtual usage broken down for a given time period.
Procedure
1. Open the User Activity page. From the menu bar, click Reports > User
Activity. A list of the available reports is displayed in the left pane of user
interface.
2. Optional: To generate the report for a specific time range, adjust the date range
in the From and To fields and click Update.
3. Optional: Click the Download filtered data link to download the
user-activity.csv file. This report displays the amount of time each user has had
Chapter 10. Reporting 801
a virtual system instance deployed (virtual system instance hours), and a
virtual machine deployed (Virtual Machine Hours). This report also provides
additional details about system utilization for the selected time period. The
following information is listed for each user.
4. You can sort the data. You can sort the data by the following fields:
v Maximum concurrent active virtual machines
v Maximum concurrent CPUs reserved
v Maximum concurrent memory reserved (MB)
v Maximum concurrent storage reserved (MB)
What to do next
To see additional information about your system activity, review the audit data
available for SmartCloud Orchestrator.
Related tasks:
Machine activity reporting on page 800
System usage reports, to track the resources being used in the cloud, are provided
by SmartCloud Orchestrator. A diverse set of reports is available to provide specific
data you can use for planning purposes. Your system usage reports are generated
to track both physical and virtual resource utilization.
Chapter 12, Troubleshooting, on page 1077
Troubleshooting tools have been collected for ease of use when attempting to
debug an issue.
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.
Installing Jazz for Service Management and Tivoli Common Reporting
Install Jazz for Service Management that is based on the Open Services for
Lifecycle Collaboration (OSLC) open specifications for linking data and other
shared integration services. With Jazz for Service Management installed, you can
install Tivoli Common Reporting to start working with your reports. Before you
start the installation, download the prerequisite packages.
Before you begin
Important: The part numbers of the packages might vary depending on your
operating system. The following packages are for Red Hat Enterprise Linux 6.3.
1. Download Jazz for Service Management and WebSphere Application Server:
v Jazz for Service Management V1.1.0.1 for Linux Multilingual (Launchpad,
PRS, Jazz Repository, TDI) (CIN3EML)
802 IBM SmartCloud Orchestrator 2.3: User's Guide
v IBM WebSphere Application Server V8.5.0.1 for Jazz for Service Management
for Linux Multilingual (CIES6ML)
2. Download the DB2 10.1 installer:
v IBM DB2 Enterprise Server Edition V10.1 for Linux on AMD64 and Intel
EM64T systems (x64) Multilingual (CI6W6ML)
Note: Use IBM DB2 Enterprise Server Edition V10.1 to support SmartCloud
Orchestrator. If you subsequently install IBM Endpoint Manager, do not
install the IBM DB2 Workgroup Server Edition V10.1 that is included with
IBM Endpoint Manager. Continue to use the IBM DB2 Enterprise Server
Edition V10.1, because IBM Endpoint Manager will be used in the context of
SmartCloud Orchestrator.
3. Download Tivoli Common Reporting 3.1.0.1:
v IBM Tivoli Common Reporting V3.1.0.1 for Linux Multilingual (CIN3IML)
Procedure
Installing Jazz for Service Management in the silent mode
The silent installation installs WebSphere Application Server, Security extension for
WebSphere, and the following Jazz for Service Management integration services:
Administration Services, Dashboard Application Services Hub, Registry Services,
and Security Services. The installation uses a response file to automate the
installation process and no user interaction is required.
Before you begin
1. Install DB2 Server 10.1. See DB2 10.1 Installation Guide
Note: Install and set up IBM DB2 Enterprise Server Edition V10.1 to support
SmartCloud Orchestrator. If you subsequently install IBM Endpoint Manager,
do not install the IBM DB2 Workgroup Server Edition V10.1 that is included
with IBM Endpoint Manager. Continue to use the IBM DB2 Enterprise Server
Edition V10.1, because IBM Endpoint Manager will be used in the context of
SmartCloud Orchestrator.
2. Install Installation Manager in the silent mode. See Installing Installation
Manager silently.
3. Edit the response file that is in the <JazzSM_extract_dir>/responsefiles/
directory and specify the values for the parameters that are required for
installation:
v Paths to the Jazz for Service Management and WebSphere Application Server
installers.
v Connection string to DB2: DB_JDBC_HOST_NAME, DB_JDBC_PORT, and
DB_CONN_URL.
v Credentials for the DB2 administrator: DB2_INSTANCE, DB_USER_NAME, and
DB_PASSWORD.
v Credentials for the WebSphere Application Server administrator:
WAS_USER_NAME and WAS_PASSWORD.
The response file requires encrypted password for those users. Run the
following in a command line to generate the encrypted password:
/opt/IBM/InstallationManager/eclipse/tools/imcl encryptString PasswordToEncrypt
For more information about the response file, see Response files for silent
installation.
Chapter 10. Reporting 803
Procedure
1. In the command window, open the eclipse subdirectory that is in directory
where you installed Installation Manager.
2. Run one of the following commands:
v On Windows:
IBMIMc.exe --launcher.ini silent-install.ini -input <response file path and name>
-log <log file path and name>
v On Linux:
./IBMIM --launcher.ini silent-install.ini -input <response file path and name>
-log <log file path and name>
Related information:
Installing Jazz for Service Management in the silent mode
Installing Tivoli Common Reporting in the silent mode
Install Tivoli Common Reporting to start working with your reports. Silent
installation uses a response file to automate the installation process and no user
interaction is required.
Before you begin
Ensure that you start WebSphere Application Server before the installation.
Procedure
1. Run the prerequisite scanner to check the hardware and software requirements.
You can find it in the PrecheckScanner folder of the Jazz for Service
Management extraction directory:
<JazzSM_extract_dir>/PrereqScanner/prereq_checker.sh TCR
2. Create a database for Cognos Content Store in the same DB2 instance that is
used by the Registry Services database. See Creating the Cognos Content Store.
3. Prepare the TCR_sample_response.txt file from the <TCR_extract_dir>/
TCRInstaller directory. Modify the following parameters:
v LICENSE_ACCEPTED=true to accept the software license.
v OSDP_HOME_DIRECTORY. The default Jazz for Service Management installation
directory is /opt/IBM/JazzSM for Linux and C:\Program Files\IBM\JazzSM for
Windows.
v WAS_USER_NAME and WAS_PASSWORD. Enter the password in plain text.
v DB2 information: HOSTNAME, PORT, DATABASE_NAME, LOGIN, and PASSWORD.
4. Run one of the following commands to install Tivoli Common Reporting:
v For Windows:
<TCR_extract_dir>/TCRInstaller/install.bat -f full_path_to_response_file -i silent
v For UNIX:
<TCR_extract_dir>/TCRInstaller/install.sh -f full_path_to_response_file -i silent
5. After the installation, verify if all of the components were installed successfully.
See Verifying the installation.
Related information:
Installing Tivoli Common Reporting in the silent mode
804 IBM SmartCloud Orchestrator 2.3: User's Guide
Chapter 11. Reference
The following topics provide reference information for SmartCloud Orchestrator.
Using the command-line interface
To perform administrative functions for SmartCloud Orchestrator, you can
download the command-line interface from SmartCloud Orchestrator onto a local
machine. You can then run the command-line interface from the local machine.
Before you begin
The command-line interface communicates with SmartCloud Orchestrator enabling
you to manage the product in a scripted, non-graphical environment.
Be sure that you have Java Runtime Environment (JRE), version 6 installed on the
machine on which the command-line interface is to be run. You can download this
JRE for Linux from the following Web address: http://www.ibm.com/
developerworks/java/jdk/linux/download.html. Because the command-line
interface is a scripting language based on Python 2.5.1, using the command-line
interface requires some familiarity with version 2.5.1 of the Python language. For
more Information about using Python, see http://docs.python.org/release/2.5.1/
index.html. See Command-line interface overview on page 806 for information
about the command-line interface.
To configure and administer SmartCloud Orchestrator, you must learn to use the
OpenStack command-line interface. 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.
About this task
This section provides the high-level steps for using the command-line interface
with links to more detailed information about each section.
In the command-line interface examples, >>> denotes the Python command
prompt, meaning the three greater than symbols together in these examples, >>>,
precede code that you enter.
Procedure
1. Download the command-line interface using the instructions provided in
Downloading and configuring the command-line interface on page 909.
2. Invoke the command-line interface using the options provided in Invoking the
command-line interface on page 911.
3. You can get help for command syntax, available commands, and using
interactive mode. See Getting help on the command-line interface on page
913 for more information about the help function.
4. See Command-line interface resource object reference on page 808 for a
listing of the resource objects and links to information about using the
command-line interface with them.
Copyright IBM Corp. 2013, 2014 805
Results
When you have downloaded and initialized the command-line interface, you are
ready to use it to work with SmartCloud Orchestrator resources.
Related information:
Python documentation
Linux Download information
Command-line interface overview
The command-line interface runs Python scripts or individual Python commands.
The SmartCloud Orchestrator command-line interface provides a scripting
environment based on Jython. Jython is the Java-based implementation of Python.
In addition to commands specific to SmartCloud Orchestrator, you can also issue
Python commands at the command prompt. To manage SmartCloud Orchestrator
with the command-line interface, you can download the command-line interface to
any machine and then point to where SmartCloud Orchestrator is running. You can
use the command-line interface on Windows and Linux operating systems.
Using the SmartCloud Orchestrator command-line interface, you can manage a
SmartCloud Orchestrator remotely. The command-line interface communicates with
the SmartCloud 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.
The Jython interpreter included with the SmartCloud Orchestrator command-line
interface implements some of the Python 2.5.1 language. The SmartCloud
Orchestrator command-line interface uses the Jython interpreter to help you
manage your SmartCloud Orchestrator. In addition to the standard Jython libraries,
the SmartCloud Orchestrator command-line interface provides functions and
classes to help you manage your SmartCloud Orchestrator.
The SmartCloud 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 911.
Note: Each of these methods of passing commands to the command-line interface
supports the same Jython scripting language.
For more information about how to invoke the command-line interface, specify the
--help parameter to the deployer or deployer.bat command. For more
information about getting help on the command line, see Getting help on the
command-line interface on page 913.
Related tasks:
Downloading and configuring the command-line interface on page 909
To perform administrative functions for SmartCloud Orchestrator, you can use the
command-line interface. You can download the command-line interface on a local
machine.
Related information:
Jython
806 IBM SmartCloud Orchestrator 2.3: User's Guide
Python documentation
Core functions
You can use this set of basic commands as templates to build more complex
end-to-end scenarios.
Register image:
deployer.virtualimages.link("<cloud_id>", "<image_id>")
Import image:
deployer.virtualimages.create("<url_path_to_ova_file>")
Create pattern:
deployer.patterns.create({"name":"<pattern_name>","description":"[example description]"})
Create pattern part:
<part_object> = deployer.virtualimages["<virtualimage_name>"][0].parts["<part_name>"][0]
deployer.patterns["<pattern_name>"][0].parts.create(<part_object>)
Create environment profile
deployer.environmentprofiles.create({"platform":"OpenStack",
"environment":deployer.environmentprofile.ALL_ENVIRONMENT,"name":"<environment_profile_name>"})
Deploy image
Define the CLI objects:
v <cloud_object> = deployer.clouds["<cloud_name>"][0]
v <ipgroup_object> = deployer.ipgroups["<ipgroup_name>"][0]
v <pattern_object> = deployer.patterns["<pattern_name>"][0]
v <envprof_object> =
deployer.environmentprofiles["<environment_profile_name>"][0]
v <flavor_id> = <cloud_object>.flavors["<flavor_name>"][0].id
Run the deployment:
deployer.virtualsystems.create({"name": "<virtualsystem_name>",
"part-<part_id>.cloud": <cloud_object>,
"part-<part_id>.vm-<vm_id>.nic-<nic_id>.ipgroup": <ipgroup_object>,
"pattern": <pattern_object>, "environmentprofile": <envprof_object>,
"part-<part_id>.OpenStackConfig.flavorid": "<flavor_id>",
"*.ConfigPWD_ROOT.password": "<root_password>",
"*.ConfigPWD_USER.password": "<user_password>"})
For example:
cloud = deployer.clouds["cloud_example"][0]
ipgroup = deployer.ipgroups["ipgroup_example"][0]
pattern = deployer.patterns["pattern_example"][0]
envprof = deployer.environmentprofiles["environment_profile_example"][0]
flavor_id = cloud.flavors["m1.tiny"][0].id
deployer.virtualsystems.create({"name": "vsys_example", "part-1.cloud": cloud,
"part-1.vm-1.nic-1.ipgroup": ipgroup , "pattern": pattern,
"environmentprofile": envprof, "part-1.OpenStackConfig.flavorid": flavor_id,
"*.ConfigPWD_ROOT.password": "root_example" ,
"*.ConfigPWD_USER.password": "password_example"})
Accept license
deployer.virtualimages["<virtualimage_name>"][0].acceptLicense()
For additional help on any of these functions, refer to the help utility.
Chapter 11. Reference 807
Command-line interface resource object reference
Anything that can be managed in SmartCloud Orchestrator is a resource object on
the command-line interface. The SmartCloud Orchestrator command-line interface
manages different types of resources, for example hypervisors, patterns, virtual
images, and virtual system instances.
The following objects, listed alphabetically, are available and documented in the
specified locations in the information center:
AddOn For information about working with the AddOn and AddOns objects, see
AddOn command-line interface reference on page 810.
ACL For information about working with the ACL object, see ACL object on
page 935.
Cloud For information about working with the Cloud and Clouds objects, see
Cloud group command-line interface reference on page 815.
DNS For information about working with the dns.server and dns.servers
objects, see Domain Name System (DNS) server command-line interface
reference on page 817.
EnvironmentProfile
For information about working with the following objects, see
Environment profiles command-line interface reference on page 819:
EnvironmentProfile and EnvironmentProfiles
See Environment profiles on the command-line interface on page
820.
EnvironmentProfileCloud and EnvironmentProfileClouds
See Environment profile clouds on the command-line interface
on page 824.
EnvironmentProfileCloudIPGroup and EnvironmentProfileCloudIPGroups
See Environment profile cloud IP groups on the command-line
interface on page 827,
Hypervisor
For information about working with the Hypervisor and Hypervisors
objects, see Hypervisor command-line interface reference on page 830.
IP For information about working with the IP and IPs objects, see IP
command-line interface reference on page 834.
IPgroup
For information about working with the IPgroup and IPgroups objects, see
IP group command-line interface reference on page 838.
MailDelivery
For information about working with the MailDelivery object, see Mail
delivery command-line interface reference on page 841.
Maintenance
For information about working with Maintenance and Maintenances objects,
see Maintenance command-line interface reference on page 841
Network
For information about working with the Network and Networks objects, see
Network command-line interface reference on page 843.
808 IBM SmartCloud Orchestrator 2.3: User's Guide
Patterns
For information about working with patterns on the command-line
interface, see Pattern command-line interface reference on page 844 and
the following references:
Pattern, Patterns
See Patterns on the command-line interface on page 848.
Advancedoptions
See Advancedoptions object on page 852.
Pattern_part and Pattern_parts
See Pattern parts on the command-line interface on page 855.
Pattern_script and Pattern_scripts
See Pattern scripts on the command-line interface on page 861.
Part and Parts
See Parts on the command-line interface on page 867.
Problem determination
For information about working with the Diagnostics, Trace and Errors
objects, see Problem determination command-line interface reference on
page 874.
Script packages
For information about working with the Script, Scripts, and
script.archive objects, see Script package command-line interface
reference on page 876.
Storage
For information about working with the Storage and Storages objects, see
Storage command-line interface reference on page 882.
VirtualImage
For information about working with the Virtualimage and Virtualimages
objects, see Virtual images command-line interface reference on page 893.
VirtualSystem
For information about working with the VirtualSystem, VirtualSystems,
and VirtualMachines objects, see Virtual system instances command-line
interface reference on page 902.
PatternType
For information about working with the PatternType and PatternTypes
objects, see Pattern type command-line interface on page 870.
ApplicationPattern
For information about working with the ApplicationPattern and
ApplicationPatterns objects, see Virtual application pattern
command-line interface reference on page 886.
VirtualApplication
For information about working with the VirtualApplication and
VirtualApplications objects, see Virtual application instance
command-line interface reference on page 883.
Plugin For information about working with the Plugin and Plugins objects, see
Plug-in command-line interface reference on page 872.
Related concepts:
Chapter 11. Reference 809
Resources on the command line on page 916
Any SmartCloud 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 SmartCloud Orchestrator command-line
interface manages different types of resources, for example hypervisors, patterns,
virtual images, and virtual system instances.
Related information:
Jython
Python documentation
AddOn command-line interface reference
You can administer additions in the catalog using the SmartCloud Orchestrator
command-line interface.
For information about working with the command-line interface, see the Using
the command-line interface on page 805 section.
AddOns object
An AddOns object represents the collection of add-ons defined to SmartCloud
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)
AddOn object
An AddOn object represents a particular add-on defined in SmartCloud 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 812.
command
The command to be run for this add-on.
810 IBM SmartCloud Orchestrator 2.3: User's Guide
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",
"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 812 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.
Chapter 11. Reference 811
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)
__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
set 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:
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.
812 IBM SmartCloud Orchestrator 2.3: User's Guide
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.
clone 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 914
SmartCloud Orchestrator manages different types of resources, for example
hypervisors, 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
Audit logging command-line interface reference
This topic provides a reference for collecting your audit reports using the
command-line interface tool.
For information about working with the command-line interface, see the Using
the command-line interface on page 805 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 SmartCloud 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 916.
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.
Chapter 11. Reference 813
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)
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-events-
checksum.
Related tasks:
Using the command-line interface on page 805
To perform administrative functions for SmartCloud Orchestrator, you can
download the command-line interface from SmartCloud Orchestrator onto a local
machine. You can then run the command-line interface from the local machine.
Related information:
Jython
Python documentation
814 IBM SmartCloud Orchestrator 2.3: User's Guide
Cloud group command-line interface reference
You can work with cloud groups using the SmartCloud Orchestrator command-line
interface.
For information about working with the command-line interface, see Using the
command-line interface on page 805.
Clouds object
A clouds object represents a collection of cloud groups that are defined to
SmartCloud Orchestrator. Objects of this type are used to delete, iterate over, list
and search for cloud groups on SmartCloud 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 914.
Cloud object
A cloud object represents a particular cloud group that is defined in SmartCloud
Orchestrator. Use the cloud object to query and manipulate the cloud group
definition in the product. Attributes of the cloud group, and relationships between
the cloud group and other resources on SmartCloud Orchestrator, are represented
as Jython attributes on cloud objects. Manipulate these Jython attributes using
standard Jython mechanisms to change the corresponding data on the SmartCloud
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.
Chapter 11. Reference 815
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
SmartCloud 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 The ID of the cloud group. This field is read-only.
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 914.
Cloud methods
The cloud object has the following methods associated with it:
discover()
Forces SmartCloud 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
F Opt-out discovered network and storage
816 IBM SmartCloud Orchestrator 2.3: User's Guide
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 914
SmartCloud Orchestrator manages different types of resources, for example
hypervisors, 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:
Building the cloud with topology resources on page 183
You can build clouds using your existing resources, for example hypervisors,
networks and storage, with SmartCloud Orchestrator. SmartCloud Orchestrator
manages these resources in the cloud.
Related information:
Jython
Python documentation
Domain Name System (DNS) server command-line interface
reference
You can administer the Domain Name System (DNS) servers used by your
SmartCloud Orchestrator using the command-line interface.
Server object
A Server object represents a DNS server defined to the SmartCloud Orchestrator.
Help is available on the command-line interface for the Server object. To get help,
pass the Server object as an argument to the help() function, as shown in the
following example:
>>> help(deployer.dns.server)
Server Attributes
The Server object has the following attribute:
ipaddress
The IP address of the DNS server as a string in dotted decimal notation,
for example 172.16.3.4.
Servers object
The Servers object represents the list of DNS servers currently defined to the
SmartCloud Orchestrator. The Servers object acts as a list of Server objects. Help is
available on the command-line interface for the Servers object. To get help, pass
the Servers object as an argument to the help() function, as shown in the
following example:
>>> help(deployer.dns.servers)
Chapter 11. Reference 817
Servers methods
The Servers object supports the same methods as a Python list object. DNS server
information can be supplied to these methods in one of the following ways:
v As a Server object
v As a Python dict object containing the Server object attributes as keys
Supplying DNS server information to the methods is shown in the following
example:
>>> deployer.dns.servers
[{
"ipaddress": "172.16.1.2"
}]
>>> deployer.dns.servers.append({ipaddress: 1.2.3.4})
>>> deployer.dns.servers
[{
"ipaddress": "172.16.1.2"
}, {
"ipaddress": "1.2.3.4"
}]
>>> deleteme = deployer.dns.servers[1]
>>> deployer.dns.servers.remove(deleteme)
>>> deployer.dns.servers
[{
"ipaddress": "172.16.1.2"
}]
For more information about working with resource objects, see the Resources,
resource collections, and methods on page 914 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 935 information.
Related tasks:
Using the command-line interface on page 805
To perform administrative functions for SmartCloud Orchestrator, you can
download the command-line interface from SmartCloud Orchestrator onto a local
machine. You can then run the command-line interface from the local machine.
Related reference:
Domain Name System (DNS) server command-line interface reference on page
817
You can administer the Domain Name System (DNS) servers used by your
SmartCloud Orchestrator using the command-line interface.
Related information:
Jython
Python documentation
818 IBM SmartCloud Orchestrator 2.3: User's Guide
Environment profiles command-line interface reference
You can work with environment profiles on the SmartCloud Orchestrator
command-line interface.
For general information about working with the command-line interface, see
Using the command-line interface on page 805.
You can use the following resources to work with environment profiles:
EnvironmentProfiles
Represents the collection of environment profiles defined to SmartCloud
Orchestrator. For more information, see Environment profiles on the
command-line interface on page 820.
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 824.
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 827.
User A user can own environment profiles.
Related concepts:
Resources, resource collections, and methods on page 914
SmartCloud Orchestrator manages different types of resources, for example
hypervisors, 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 220
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 805
To perform administrative functions for SmartCloud Orchestrator, you can
download the command-line interface from SmartCloud Orchestrator onto a local
machine. You can then run the command-line interface from the local machine.
Related reference:
Environment profiles on the command-line interface on page 820
You can work with the environment profiles on the SmartCloud Orchestrator
command-line interface.
Environment profile clouds on the command-line interface on page 824
You can work with environment profile clouds on the SmartCloud Orchestrator
command-line interface.
Environment profile cloud IP groups on the command-line interface on page 827
You can work with the environment profile cloud IP group objects on the
SmartCloud Orchestrator command-line interface.
Related information:
Jython
Chapter 11. Reference 819
Python documentation
Environment profiles on the command-line interface:
You can work with the environment profiles on the SmartCloud Orchestrator
command-line interface.
For general information about working with the command-line interface, see
Using the command-line interface on page 805.
EnvironmentProfiles object
An EnvironmentProfiles object represents the collection of environment profiles
defined to SmartCloud Orchestrator. Objects of this type are used to create, delete,
iterate over, list and search for environment profiles in SmartCloud 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 914.
EnvironmentProfile object
An EnvironmentProfile object represents a particular environment profile defined
to SmartCloud Orchestrator. Use the EnvironmentProfile object to query and
manipulate the environment profile definition in the product. Attributes of the
EnvironmentProfile object on the SmartCloud 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
SmartCloud 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 914.
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 935 or enter the following
command:
>>> help(deployer.acl)
clouds An object that manipulates the clouds and IP groups associated with an
820 IBM SmartCloud Orchestrator 2.3: User's Guide
environment profile. For additional help on using this object, see
Environment profile clouds on the command-line interface on page 824
or enter the following command:
>>> help(deployer.environmentprofileclouds)
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 deployer.environmentprofile.PERFORMANCE_ENVIRONMENT
v deployer.environmentprofile.RESEARCH_ENVIRONMENT
v deployer.environmentprofile.PRODUCTION_ENVIRONMENT
v deployer.environmentprofile.PRE_PRODUCTION_ENVIRONMENT
id 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
SmartCloud 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 SmartCloud 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.
Chapter 11. Reference 821
memory_reserved
The amount of memory that deployers are using in this environment
profile. This field is read only.
name The name of the environment profile.
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.
822 IBM SmartCloud Orchestrator 2.3: User's Guide
${n-counter}
Replaced with a counter of n digits. The n variable in this string is
a placeholder for the number you supply.
${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:
clone 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 914
SmartCloud Orchestrator manages different types of resources, for example
hypervisors, 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 220
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 805
To perform administrative functions for SmartCloud Orchestrator, you can
download the command-line interface from SmartCloud Orchestrator onto a local
machine. You can then run the command-line interface from the local machine.
Related reference:
Environment profiles command-line interface reference on page 819
You can work with environment profiles on the SmartCloud Orchestrator
command-line interface.
Related information:
Jython
Python documentation
Chapter 11. Reference 823
Environment profile clouds on the command-line interface:
You can work with environment profile clouds on the SmartCloud Orchestrator
command-line interface.
For general information about working with the command-line interface, see
Using the command-line interface on page 805.
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 for more
information. References to these objects can be obtained using the clouds attributes
of EnvironmentProfile objects.
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.
824 IBM SmartCloud Orchestrator 2.3: User's Guide
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.
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 826 for additional information about individual attributes and methods.
EnvironmentProfileCloud methods
The EnvironmentProfileCloud object has the following methods:
Chapter 11. Reference 825
__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.
__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 914
SmartCloud Orchestrator manages different types of resources, for example
hypervisors, 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 220
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 805
To perform administrative functions for SmartCloud Orchestrator, you can
download the command-line interface from SmartCloud Orchestrator onto a local
machine. You can then run the command-line interface from the local machine.
Related reference:
Environment profiles command-line interface reference on page 819
You can work with environment profiles on the SmartCloud Orchestrator
command-line interface.
Related information:
Jython
Python documentation
826 IBM SmartCloud Orchestrator 2.3: User's Guide
Environment profile cloud IP groups on the command-line interface:
You can work with the environment profile cloud IP group objects on the
SmartCloud Orchestrator command-line interface.
For general information about working with the command-line interface, see
Using the command-line interface on page 805.
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 for
additional information about methods. References to these objects can be obtained
with the ipgroups attributes of EnvironmentProfileCloud objects.
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
Chapter 11. Reference 827
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.
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
828 IBM SmartCloud Orchestrator 2.3: User's Guide
environment profile. See EnvironmentProfileCloudIPGroup methods and
EnvironmentProfileCloudIPGroup attributes 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.
__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:
alias 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 914
SmartCloud Orchestrator manages different types of resources, for example
hypervisors, 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 220
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 805
To perform administrative functions for SmartCloud Orchestrator, you can
download the command-line interface from SmartCloud Orchestrator onto a local
machine. You can then run the command-line interface from the local machine.
Related reference:
Environment profiles command-line interface reference on page 819
You can work with environment profiles on the SmartCloud Orchestrator
command-line interface.
Chapter 11. Reference 829
Related information:
Jython
Python documentation
Hypervisor command-line interface reference
You can work with hypervisors on the SmartCloud Orchestrator command-line
interface.
For information about working with the command-line interface, see Using the
command-line interface on page 805.
Hypervisors object
A hypervisors object represents the collection of hypervisors defined to
SmartCloud Orchestrator. Objects of this type are used to delete, iterate over, list
and search for hypervisors on SmartCloud Orchestrator.
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 914.
Hypervisor object
A hypervisor object represents a particular hypervisor defined in SmartCloud
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 SmartCloud 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 SmartCloud
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 914.
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,
830 IBM SmartCloud Orchestrator 2.3: User's Guide
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.
desiredstatus
Indicates the status in which you want the hypervisor. Setting this value
causes SmartCloud 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".
Chapter 11. Reference 831
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 914.
Hypervisor methods
The following methods are provided for hypervisor objects:
discover()
Forces SmartCloud 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
F 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 SmartCloud 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 SmartCloud
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 914
SmartCloud Orchestrator manages different types of resources, for example
hypervisors, 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.
832 IBM SmartCloud Orchestrator 2.3: User's Guide
Related information:
Jython
Python documentation
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 805.
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 914.
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 914.
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:
Chapter 11. Reference 833
>>> help(deployer.cloud)
description
The description of the image.
hypervisor
The hypervisor of the image.
id The image 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.
IP command-line interface reference
You can work with IP addresses, using the IPs and IP objects on the SmartCloud
Orchestrator command-line interface.
For general information about working with the command-line interface, see
Using the command-line interface on page 805.
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 SmartCloud 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)
834 IBM SmartCloud Orchestrator 2.3: User's Guide
For more information about working with resource objects, see Resources,
resource collections, and methods on page 914.
IP object
An IP object represents a particular IP address defined in SmartCloud 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 SmartCloud Orchestrator are represented as Jython attributes on the
IP object. Manipulate these Jython attributes using standard Jython mechanisms to
change the corresponding data in SmartCloud 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,
Chapter 11. Reference 835
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.
For more information about working with resource objects, see Resources,
resource collections, and methods on page 914.
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 SmartCloud 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 SmartCloud 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 933 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 SmartCloud 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)
836 IBM SmartCloud Orchestrator 2.3: User's Guide
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.
This method raises exceptions to indicate problems deleting resources.
There is no return value.
Related concepts:
Resources, resource collections, and methods on page 914
SmartCloud Orchestrator manages different types of resources, for example
hypervisors, 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:
Building the cloud with topology resources on page 183
You can build clouds using your existing resources, for example hypervisors,
networks and storage, with SmartCloud Orchestrator. SmartCloud Orchestrator
manages these resources in the cloud.
Creating an IP group on page 211
You can create an IP group and specify a range of IP addresses, using the
SmartCloud Orchestrator user interface.
Adding IP addresses and IP groups on page 214
You can add ranges of IP addresses to an IP group that obtains IP addresses from
an IP address pool, or add an IP group to a hypervisor. You can use the
SmartCloud Orchestrator user interface to add IP addresses or IP groups.
Deleting IP addresses and IP groups on page 215
You can delete IP addresses from an IP group that obtains IP addresses from an IP
address pool, delete an IP group, or remove an IP group from a hypervisor. You
can use the SmartCloud Orchestrator user interface to delete IP addresses or IP
groups.
Administering hypervisors on page 187
You can use the SmartCloud Orchestrator user interface to work with the
hypervisors.
Related reference:
IP group command-line interface reference on page 838
You can work with IP groups on the SmartCloud Orchestrator command-line
interface using the IPgroups and IPgroup objects and attributes.
IP groups REST API on page 977
You can use the representational state transfer (REST) application programming
interface (API) to manage IP groups.
IP addresses REST API on page 973
You can use the representational state transfer (REST) application programming
interface (API) to manage IP addresses.
Related information:
Jython
Python documentation
Chapter 11. Reference 837
IP group command-line interface reference
You can work with IP groups on the SmartCloud 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 805.
IPgroups object
An IPgroups object represents the collection of IP groups defined to the
SmartCloud Orchestrator. Objects of this type are used to create, delete, iterate
over, list and search for IP groups on the SmartCloud 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 914.
IPgroup object
An IPgroup object represents a particular IP group defined in SmartCloud
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 SmartCloud 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 SmartCloud 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:
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:
838 IBM SmartCloud Orchestrator 2.3: User's Guide
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.
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.
Chapter 11. Reference 839
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 914.
Related concepts:
Resources, resource collections, and methods on page 914
SmartCloud Orchestrator manages different types of resources, for example
hypervisors, 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:
Building the cloud with topology resources on page 183
You can build clouds using your existing resources, for example hypervisors,
networks and storage, with SmartCloud Orchestrator. SmartCloud Orchestrator
manages these resources in the cloud.
Creating an IP group on page 211
You can create an IP group and specify a range of IP addresses, using the
SmartCloud Orchestrator user interface.
Adding IP addresses and IP groups on page 214
You can add ranges of IP addresses to an IP group that obtains IP addresses from
an IP address pool, or add an IP group to a hypervisor. You can use the
SmartCloud Orchestrator user interface to add IP addresses or IP groups.
Deleting IP addresses and IP groups on page 215
You can delete IP addresses from an IP group that obtains IP addresses from an IP
address pool, delete an IP group, or remove an IP group from a hypervisor. You
can use the SmartCloud Orchestrator user interface to delete IP addresses or IP
groups.
Administering hypervisors on page 187
You can use the SmartCloud Orchestrator user interface to work with the
hypervisors.
Related reference:
840 IBM SmartCloud Orchestrator 2.3: User's Guide
IP command-line interface reference on page 834
You can work with IP addresses, using the IPs and IP objects on the SmartCloud
Orchestrator command-line interface.
IP groups REST API on page 977
You can use the representational state transfer (REST) application programming
interface (API) to manage IP groups.
IP addresses REST API on page 973
You can use the representational state transfer (REST) application programming
interface (API) to manage IP addresses.
Related information:
Jython
Python documentation
Mail delivery command-line interface reference
You can administer the mail delivery settings of SmartCloud 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 SmartCloud 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 805
To perform administrative functions for SmartCloud Orchestrator, you can
download the command-line interface from SmartCloud Orchestrator onto a local
machine. You can then run the command-line interface from the local machine.
Related information:
Jython
Python documentation
Maintenance command-line interface reference
You can administer maintenance in the catalog using the SmartCloud Orchestrator
command-line interface.
For information about working with the command-line interface, see the Using
the command-line interface on page 805 section.
Maintenances object
A Maintenances object represents the collection of maintenance defined to
SmartCloud Orchestrator that is applicable to a virtual system instance. Objects of
this type are used to create, delete, iterate over, list and search for Maintenances
resources on the SmartCloud Orchestrator.
Chapter 11. Reference 841
You can work with the Maintenances object on the command-line interface and
help is available. To get help for the Maintenances object, pass it as an argument to
the help() function, as shown in the following example:
>>> help(deployer.maintenance)
Maintenance object
A Maintenance object represents a particular maintenance defined to SmartCloud
Orchestrator. Use the Maintenance object to query and manipulate the maintenance
definition on the product. Attributes of the Maintenance resource are represented as
Jython attributes on the Maintenance object. Relationships between the Maintenance
resource and other resources in SmartCloud Orchestrator are also represented as
Jython attributes on the Maintenance object. Manipulate these Jython attributes
using standard Jython mechanisms to change the corresponding data on the
SmartCloud Orchestrator.
You can work with the Maintenance object on the command-line interface and help
is available. To get help for the Maintenance object, pass it as an argument to the
help() function, as shown in the following example:
>>> help(deployer.maintenance)
Maintenance attributes
The Maintenance object has the following attributes:
currentstatus
The current status of the Maintenance object. This field contains an eight
character string value that is generated by the product. This attribute is
read-only.
currentstatus_text
This field is a string representation of currentstatus in the preferred
language of the requester. This string is automatically generated by the
product. This attribute is read-only.
fixes A list of the fixes to be applied as part of the maintenance request.
id The ID of the Maintenance object. This attribute is an integer value. This
attribute is read-only.
starttime
The time at which the maintenance activity is to be started, expressed as
number of seconds since midnight, January 1, 1970 UTC.
Related concepts:
Resources, resource collections, and methods on page 914
SmartCloud Orchestrator manages different types of resources, for example
hypervisors, 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
842 IBM SmartCloud Orchestrator 2.3: User's Guide
Network command-line interface reference
You can work with the network resource objects on the SmartCloud Orchestrator
command-line interface.
For information about working with the command-line interface, see the Using
the command-line interface on page 805 section.
Networks object
A networks object represents the collection of networks defined to SmartCloud
Orchestrator. Objects of this type are used to delete, iterate over, list and search for
networks on SmartCloud Orchestrator.
Note: Networks objects are automatically created by SmartCloud 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 914 section.
Network object
A network object represents a particular network defined in SmartCloud
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 SmartCloud Orchestrator are also represented as Jython
attributes on the network object. Manipulate these Jython attributes using standard
Jython mechanisms to change the corresponding data on the SmartCloud
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.
Chapter 11. Reference 843
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.
vlan 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 tasks:
Building the cloud with topology resources on page 183
You can build clouds using your existing resources, for example hypervisors,
networks and storage, with SmartCloud Orchestrator. SmartCloud Orchestrator
manages these resources in the cloud.
Related information:
Jython
Python documentation
Pattern command-line interface reference
You can work with the pattern and patterns objects on the SmartCloud
Orchestrator command-line interface.
For information about working with the command-line interface, see Using the
command-line interface on page 805.
You can use the following resource objects to work with virtual system patterns:
ACL You can control the access control list for virtual system patterns with the
ACL object. For more information about the ACL object, see ACL object on
page 935.
844 IBM SmartCloud Orchestrator 2.3: User's Guide
Advancedoptions
You can 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 more information about the Advancedoptions object, see
Advancedoptions object on page 852.
Parts Represents the parts and collection of parts defined to SmartCloud
Orchestrator. For more information about parts objects, see Parts on the
command-line interface on page 867.
Pattern_parts
Represents the virtual system pattern parts and collection of virtual system
pattern parts defined within a particular virtual system pattern on
SmartCloud Orchestrator. For more information about virtual system
pattern parts, see Pattern parts on the command-line interface on page
855.
Pattern_scripts
Represents the scripts and collections of scripts defined within a particular
virtual system pattern part on SmartCloud Orchestrator. For more
information about the virtual system pattern script parts, see Pattern
scripts on the command-line interface on page 861.
Patterns
Represents the virtual system patterns and collection of virtual system
patterns defined to SmartCloud Orchestrator. For more information about
patterns, see Patterns on the command-line interface on page 848.
User A user can own virtual system patterns.
Related concepts:
Resources, resource collections, and methods on page 914
SmartCloud Orchestrator manages different types of resources, for example
hypervisors, 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:
Working with virtual system patterns on page 511
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.
Using the command-line interface on page 805
To perform administrative functions for SmartCloud Orchestrator, you can
download the command-line interface from SmartCloud Orchestrator onto a local
machine. You can then run the command-line interface from the local machine.
Related information:
Jython
Python documentation
Chapter 11. Reference 845
Importing and exporting virtual system patterns:
SmartCloud Orchestrator virtual system patterns 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 SmartCloud Orchestrator
than the one on which it was created.
Before you begin
Before you can copy virtual system patterns from one SmartCloud Orchestrator
environment to another SmartCloud Orchestrator environment, you must first have
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 SmartCloud Orchestrator environments.
About this task
You can export virtual system patterns from one SmartCloud Orchestrator
environment and import them to another SmartCloud Orchestrator environment
using the patternToPython.py script. This command-line interface (CLI) script
examines a virtual system pattern defined on SmartCloud Orchestrator and
generates another CLI script. When run, this generated CLI script reconstructs the
original virtual system pattern on another SmartCloud 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
846 IBM SmartCloud Orchestrator 2.3: User's Guide
See Invoking the command-line interface on page 911 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
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
SmartCloud Orchestrator environment. Use the standard CLI parameters to
specify the host name, user ID, and password of SmartCloud 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 911 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 SmartCloud 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 read-only on page 546
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 on page 547
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 529
When you have edited the topology of a virtual system pattern, you can configure
advanced function for the virtual system pattern.
Chapter 11. Reference 847
Related reference:
Virtual system pattern editing views and parts on page 522
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.
Patterns on the command-line interface:
You can work with virtual system patterns by working with Pattern and Patterns
objects on the SmartCloud Orchestrator command-line interface.
For information about working with the command-line interface, see Using the
command-line interface on page 805.
Patterns object
The Patterns object represents the collection of virtual system patterns defined to
SmartCloud Orchestrator. Use objects of this type to create, delete, iterate over, list,
and search for virtual system patterns in SmartCloud 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 914.
Pattern object
A Pattern object represents a particular SmartCloud 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 SmartCloud Orchestrator resources are
represented as Jython attributes on the Pattern object. Manipulate these Jython
attributes using standard Jython mechanisms to change the corresponding
SmartCloud 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 935.
848 IBM SmartCloud Orchestrator 2.3: User's Guide
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 852
section.
created
The creation time of the virtual system pattern, as the 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.
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 SmartCloud 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.
Chapter 11. Reference 849
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)
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
850 IBM SmartCloud Orchestrator 2.3: User's Guide
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)
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
command-line interface reference on page 902 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 command-line
interface reference on page 902. 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 command-line interface reference on
page 902.
v The environment profile configuration information. For more
information, see the create method in Virtual system instances
command-line interface reference on page 902.
Chapter 11. Reference 851
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 SmartCloud
Orchestrator. To use the generated script, the machine on which the virtual
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
852 IBM SmartCloud Orchestrator 2.3: User's Guide
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
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.
Chapter 11. Reference 853
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.
v 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 914.
Related concepts:
Resources, resource collections, and methods on page 914
SmartCloud Orchestrator manages different types of resources, for example
hypervisors, 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:
Working with virtual system patterns on page 511
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.
Using the command-line interface on page 805
To perform administrative functions for SmartCloud Orchestrator, you can
download the command-line interface from SmartCloud Orchestrator onto a local
machine. You can then run the command-line interface from the local machine.
Related information:
Jython
Python documentation
854 IBM SmartCloud Orchestrator 2.3: User's Guide
Pattern parts on the command-line interface:
You can work with virtual system patterns by working with virtual system pattern
parts on the SmartCloud Orchestrator command-line interface.
For information about working with the command-line interface, see Using the
command-line interface on page 805.
Pparts object
A pattern_parts object represents the collection of parts defined within a
particular virtual system pattern on the SmartCloud Orchestrator. Objects of this
type are used to create, delete, iterate over, list and search for parts within a virtual
system pattern on the SmartCloud 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:
>>> 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 933.
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
SmartCloud 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 SmartCloud Orchestrator are represented as Jython
Chapter 11. Reference 855
attributes on the pattern_part object. Modify these Jython attributes using
standard Jython mechanisms to change the corresponding data in SmartCloud
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
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.
856 IBM SmartCloud Orchestrator 2.3: User's Guide
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 858.
startuporder
The startup order of this part relative to other parts in the same virtual
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 SmartCloud
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)
Chapter 11. Reference 857
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 The key of the property to be retrieved. This parameter is required.
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
858 IBM SmartCloud Orchestrator 2.3: User's Guide
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
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.
Chapter 11. Reference 859
__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.
__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 914.
Related concepts:
860 IBM SmartCloud Orchestrator 2.3: User's Guide
Resources, resource collections, and methods on page 914
SmartCloud Orchestrator manages different types of resources, for example
hypervisors, 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:
Using the command-line interface on page 805
To perform administrative functions for SmartCloud Orchestrator, you can
download the command-line interface from SmartCloud Orchestrator onto a local
machine. You can then run the command-line interface from the local machine.
Working with virtual system patterns on page 511
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
Pattern scripts on the command-line interface:
You can work with pattern_script and pattern_scripts objects on the
SmartCloud Orchestrator command-line interface.
For information about working with the command-line interface, see Using the
command-line interface on page 805.
Pscripts object
A pattern_scripts object represents the collection of scripts defined within a
particular virtual system pattern part in SmartCloud Orchestrator. Objects of this
type are used to create, delete, iterate over, list, and search for scripts within a
pattern part in SmartCloud 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
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:
Chapter 11. Reference 861
>>> 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 933 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 914.
For more information about the script package object, see Script package
command-line interface reference on page 876.
Pscript object
A virtual system pattern script object represents a script that has been added to a
part in a virtual system pattern in SmartCloud 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
SmartCloud 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 SmartCloud Orchestrator.
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 914.
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
862 IBM SmartCloud Orchestrator 2.3: User's Guide
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 858.
type The type of this script. This attribute is read-only.
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:
Chapter 11. Reference 863
>>> 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
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:
864 IBM SmartCloud Orchestrator 2.3: User's Guide
>>> 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)
__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.
Chapter 11. Reference 865
__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 914.
Related concepts:
Resources, resource collections, and methods on page 914
SmartCloud Orchestrator manages different types of resources, for example
hypervisors, 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:
Using the command-line interface on page 805
To perform administrative functions for SmartCloud Orchestrator, you can
download the command-line interface from SmartCloud Orchestrator onto a local
machine. You can then run the command-line interface from the local machine.
Working with virtual system patterns on page 511
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
866 IBM SmartCloud Orchestrator 2.3: User's Guide
Parts on the command-line interface:
You can work with the Part and Parts objects on the SmartCloud Orchestrator
command-line interface.
For information about working with the command-line interface, see Using the
command-line interface on page 805.
Parts object
A Parts object represents the collection of parts defined to SmartCloud
Orchestrator. Objects of this type are used to delete, iterate over, list and search for
SmartCloud Orchestrator parts. Parts cannot be manually created. Parts are created
automatically by SmartCloud 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.
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 SmartCloud 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 SmartCloud 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 SmartCloud 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 867
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 893.
868 IBM SmartCloud Orchestrator 2.3: 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 914.
Related concepts:
Resources, resource collections, and methods on page 914
SmartCloud Orchestrator manages different types of resources, for example
hypervisors, 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 11. Reference 869
Working with virtual system patterns on page 511
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.
Using the command-line interface on page 805
To perform administrative functions for SmartCloud Orchestrator, you can
download the command-line interface from SmartCloud Orchestrator onto a local
machine. You can then run the command-line interface from the local machine.
Related information:
Jython
Python documentation
Pattern type command-line interface
You can administer pattern types using the SmartCloud Orchestrator
command-line interface.
For information about working with the command-line interface, see the topic,
Using command-line interface.
PatternType object
A PatternType object represents a particular pattern type defined on SmartCloud
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 SmartCloud Orchestrator are represented as Jython
attributes on the PatternType object. Manipulate these Jython attributes using
standard\nJython mechanisms to make changes to the corresponding data on
SmartCloud 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
SmartCloud Orchestrator. Objects of this type are used to create, delete, iterate
over, list and search for pattern types on SmartCloud 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:
v shortname
The short name of the pattern type.
v name
The name of the pattern type.
v version
The version of the pattern type.
v description
The description of the pattern type.
v status
870 IBM SmartCloud Orchestrator 2.3: User's Guide
The status of the pattern type.
v required
The prerequisites of the pattern type.
PatternTypes methods
The PatternTypes and PatternType object have the following methods:
acceptLicense
Accept the license of a given pattern type
deployer.patterntypes.get(<shortname>, <version>).acceptLicense()
Here the version should be in "vrmf" format, for example, "2.0.0.1".
For example, >>> deployer.patterntypes.get('webapp','2.0.0.1').acceptLicense()
list
List all pattern types 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 shortname 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:\\dbaas-2.0.0.1.tgz')
delete
Delete a pattern type
deployer.patterntypes.delete(<shortname>, <version>)
Here the version should be in "vrmf" format.
For example, >>> deployer.patterntypes.delete('dbaas','2.0.0.1')
Chapter 11. Reference 871
enable
Enable a pattern type
deployer.patterntypes.get(<shortname>, <version>).enable()
Here, the version should in in "vrmf" format, for example, "2.0.0.1"
For example, >>> deployer.patterntypes.get('dbaas','2.0.0.1').enable()
disable
Disable a pattern type
deployer.patterntypes.get(<shortname>, <version>).disable()
Here, the version should in in "vrmf" format, for example, "2.0.0.1"
For example, >>> deployer.patterntypes.get('dbaas','2.0.0.1').disable()
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 the Using the
command-line interface section.
Plugin object
A Plugin object represents a particular plug-in defined in SmartCloud 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
SmartCloud 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.
872 IBM SmartCloud Orchestrator 2.3: User's Guide
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 and Plugin object has the following methods:
list
List all plugins
deployer.plugins or deployer.plugins.list
For example, >>>deployer.plugins
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>)
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:\\testplugin-1.0.0.0.tgz")
delete
Delete a plug-in
deployer.plugins.delete(<plugin_name>)
For example, >>> deployer.plugins.delete("firewall")
Chapter 11. Reference 873
Problem determination command-line interface reference
You can work with SmartCloud 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 805 section.
Diagnostics object
Returns the Diagnostics object representing the diagnostics package for the
SmartCloud 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 SmartCloud 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:
v OFF
v SEVERE
v WARNING
v CONFIG
v 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)
874 IBM SmartCloud Orchestrator 2.3: User's Guide
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 SmartCloud
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 SmartCloud 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:
>>> 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 805 section. For more information about working
with resources on the command-line interface, see the Resource collections on the
command line on page 920 section.
Chapter 11. Reference 875
Related tasks:
Using the command-line interface on page 805
To perform administrative functions for SmartCloud Orchestrator, you can
download the command-line interface from SmartCloud Orchestrator onto a local
machine. You can then run the command-line interface from the local machine.
Related information:
Jython
Python documentation
Script package command-line interface reference
You can administer script packages using the SmartCloud Orchestrator
command-line interface.
For information about working with the command-line interface, see Using the
command-line interface on page 805.
Scripts object
A Scripts object represents the collection of script packages defined to SmartCloud
Orchestrator. Objects of this type are used to create, delete, iterate over, list and
search for script packages on the SmartCloud 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 914.
Script object
A Script object represents a particular script defined in SmartCloud 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
SmartCloud Orchestrator are represented as Jython attributes on the Script object.
Manipulate these Jython attributes using standard Jython mechanisms to change
the corresponding data in SmartCloud Orchestrator.
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 935 or enter the
following command:
>>> help(deployer.acl)
876 IBM SmartCloud Orchestrator 2.3: User's Guide
archive
The script archive object associated with this script. For more information,
see Script.Archive object on page 879. 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"
}
>>> 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:
Chapter 11. Reference 877
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.
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.
878 IBM SmartCloud Orchestrator 2.3: User's Guide
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 SmartCloud 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
__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.
Chapter 11. Reference 879
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 914.
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 935 topic.
Related concepts:
Resources, resource collections, and methods on page 914
SmartCloud Orchestrator manages different types of resources, for example
hypervisors, 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 935
You can use the access control list (ACL) object to set and control user access for
other SmartCloud Orchestrator resources.
Related information:
Jython
Python documentation
Snapshots on the command-line interface
This topic provides a reference for administering snapshots of virtual system
instances using the SmartCloud Orchestrator command-line interface.
For general information about working with the command-line interface, see the
Using the command-line interface on page 805 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 SmartCloud Orchestrator
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)
880 IBM SmartCloud Orchestrator 2.3: User's Guide
Snapshot object
A Snapshot object represents a particular snapshot defined on the SmartCloud
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 SmartCloud 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 SmartCloud
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 805 section. For more information about working
with resources on the command-line interface, see the Resources, resource
collections, and methods on page 914 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 935 topic.
Related tasks:
Using the command-line interface on page 805
To perform administrative functions for SmartCloud Orchestrator, you can
download the command-line interface from SmartCloud Orchestrator onto a local
machine. You can then run the command-line interface from the local machine.
Related information:
Jython
Python documentation
Chapter 11. Reference 881
Storage command-line interface reference
You can administer storage resource objects using the SmartCloud Orchestrator
command-line interface.
Note: Hypervisor storage cannot be manually defined to SmartCloud 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 805 section.
Storages object
A storages object represents the collection of hypervisor storage defined to the
SmartCloud Orchestrator. Objects of this type are used to delete, iterate over, list
and search for storage devices on SmartCloud 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 SmartCloud
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 SmartCloud 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 SmartCloud 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.
882 IBM SmartCloud Orchestrator 2.3: User's Guide
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 tasks:
Building the cloud with topology resources on page 183
You can build clouds using your existing resources, for example hypervisors,
networks and storage, with SmartCloud Orchestrator. SmartCloud Orchestrator
manages these resources in the cloud.
Related information:
Jython
Python documentation
Virtual application instance command-line interface reference
You can administer virtual application instance using the SmartCloud Orchestrator
command-line interface.
For information about working with the command-line interface, see the Using the
command-line interface section.
VirtualApplication object
A VirtualApplication object represents a particular virtual application instance
defined on SmartCloud 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 SmartCloud 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 SmartCloud
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 SmartCloud Orchestrator. Objects of this type are used to
create, delete, iterate over, list and search for virtual application instances on
SmartCloud 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
Chapter 11. Reference 883
For example, >>> deployer.virtualapplications
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'})
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-20db-4d65-958b-36f54fa1e462")
vminstances
Show vm instance details of a virtual application instance
deployer.virtualapplications.vminstances(<depl_id>)
For example,
>>> deployer.virtualapplications.get("d-2e0c8abb-373f-46fc-a05f-
a255af3d3120").vminstances
terminate
Terminate a virtual application instance
deployer.virtualapplications.terminate(<depl_id>)
For example,
>>> deployer.virtualapplications.terminate("d-0d1ede95-f0cf-4d71-9b2e-
ffa3bf80871c")
delete
Delete a virtual application instance
deployer.virtualapplications.delete(<depl_id>)
For example,
884 IBM SmartCloud Orchestrator 2.3: User's Guide
>>> deployer.virtualapplications.delete("d-0d1ede95-f0cf-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-f0cf-4d71-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-f0cf-4d71-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-8e85-42f0-b975-
db75e84b1dd7').startvm('database-db2.11304523030092')
stopvm
Stop a virtual machine
deployer.virtualapplications.get(<depl_id>)startvm(<node_id>)
For example,
>>>deployer.virtualapplications.get('d-86148d3c-8e85-42f0-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-9e6e-453c-b6bc-fce578fc5873').
refresh()
Chapter 11. Reference 885
maintain
Put a virtual application instance in maintenance mode
deployer.virtualapplications.get(<depl_id>).maintain()
For example,
>>>deployer.virtualapplications.get('d-12bbc2a0-9e6e-453c-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-453c-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-9e6e-453c-b6bc-fce578fc5873').
upgrade()
Virtual application pattern command-line interface reference
You can administer virtual application pattern using the SmartCloud Orchestrator
command-line interface.
ApplicationPattern object
For information about working with the command-line interface, see the Using the
command-line interface section.
An ApplicationPattern object represents a particular virtual application pattern
defined on SmartCloud 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 SmartCloud 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 SmartCloud
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)
886 IBM SmartCloud Orchestrator 2.3: User's Guide
ApplicationPatterns object
An ApplicationPatterns object represents the collection of virtual application
patterns defined to SmartCloud Orchestrator. Objects of this type are used to
create, delete, iterate over, list and search for virtual application patterns on
SmartCloud 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.
Chapter 11. Reference 887
ApplicationPattern methods
The ApplicationPattern and ApplicationPatterns object have the following methods:
List
List all applications patterns
deployer.applications
For example, >>> 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
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,
(1) Use specific attributes
>>> deployer.applications.create({'name':'demoApp'})
(2). Use .zip file or JSON file
>>> deployer.applications.create("C:\\sample.json")
delete
Delete an application pattern
deployer.applications.delete(<app_ID>)
For example,
>>> deployer.applications.delete("a-6aa5bf17-0c1e-457c-b135-7c8d19401109")
update
Update an application pattern
deployer.application.get(<app_ID>).update(<local file path>")
888 IBM SmartCloud Orchestrator 2.3: User's Guide
For example,
>>> deployer.applications.get("a-514a4175-a771-4b3f-8761-
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>)
app_type is an optional parameter, the default is "application"
For example,
>>> deployer.applications.get("a-7dd50b00-c74c-4c63-ab70-
abd7dff7fcdf").clone("clonedTest")
deploy
Deploy an application pattern
deployer.applcations.get(<app_ID>).deploy(<depl_name>, <cloud object or env dict>,
<certFile>(optional), <params>(optional))
For the second parameter, it could be a Cloud object or a dictionary to describe the
environment profile. The env dictonary 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 (http://www.laubenheimer.net/ssh-keys.shtml ) to
generate SSH keys and save the public key in a file.
The format for <params> is:
{ node_link_id.attributeId: attributeValue,
groups:{node_link_id.groupId: True/False} (optional) }.
Need to specify groups if there is group definition in the plug-in metadata.
Example:
deployer.applcations.get(<app_id>).deploy(<depl_name>, <cloud object or env dict>,
<certFile>(optional), <params>(optional))
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)
Chapter 11. Reference 889
refresh
Call this method before getting status of the instance
deployer.virtualapplications.get(<depl_id>).refresh()
For example,
>>> deployer.virtualapplications.get('d-12bbc2a0-9e6e-453-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-9e6e-453c-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-453c-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-9e6e-453c-b6bc-fce578fc5873').
upgrade()
monitoring
Get all monitoring data (both servers and roles) for the given virtual application.
deployer.virtualapplications.get(<id>).monitoring
or
890 IBM SmartCloud Orchestrator 2.3: User's Guide
deployer.virtualapplications[<index>].monitoring
For example,
deployer.virtualapplications[<index>].monitoring
Sample output:
>>> deployer.virtualapplications[0].monitoring
{
"roles": (nested object),
"servers": (nested object),
}
get metrics
Get the metrics data of a server.
deployer.virtualapplications[0].monitoring.servers[<index>].getMetrics(<metricType>(optional))
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
Chapter 11. Reference 891
Get monitoring metrics data of a role
deployer.virtualapplications[0].monitoring.roles[<index>].getMetrics(<metricType>(optional))
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"
},
"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
}
}
get logs
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]}
892 IBM SmartCloud Orchestrator 2.3: User's Guide
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")
>>>
Virtual images command-line interface reference
You can manage virtual images in the catalog using the SmartCloud 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 805 section.
VirtualImages object
A VirtualImages object represents the collection of virtual images defined to
SmartCloud Orchestrator. Objects of this type are used to create, delete, iterate
over, list and search for virtual images on the SmartCloud 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 SmartCloud 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 SmartCloud Orchestrator, as shown in the following
example:
>>> deployer.virtualimages.create(/path/to/foo.ova)
Chapter 11. Reference 893
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://... })
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 933.
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 SmartCloud
Orchestrator before this method returns. Otherwise, this method queues
the operation on the SmartCloud Orchestrator and returns immediately.
The returned VirtualImage objects can be used to track the status of the
import process on the SmartCloud 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 SmartCloud 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 914 section.
894 IBM SmartCloud Orchestrator 2.3: User's Guide
VirtualImage object
A VirtualImage object represents a particular virtual image defined to SmartCloud
Orchestrator. Use the VirtualImage object to query and manipulate the virtual
image definition in SmartCloud Orchestrator. Attributes of the virtual image
resource and relationships between the virtual image and other resources in
SmartCloud 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 SmartCloud 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)
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
Chapter 11. Reference 895
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.
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. SmartCloud 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:
'T' The virtual image license has been accepted.
'F' The virtual image license has not been accepted.
name 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 867. You can also get help for
deployer.parts, as shown in the following example:
896 IBM SmartCloud Orchestrator 2.3: User's Guide
>>> 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.
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
SmartCloud 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.
Chapter 11. Reference 897
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.
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 914 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 935 information.
Related concepts:
Resources, resource collections, and methods on page 914
SmartCloud Orchestrator manages different types of resources, for example
hypervisors, 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 5, Managing virtual images, on page 287
Virtual images provide the operating system and product binary files that are
required to create a virtual system instance.
Related reference:
ACL object on page 935
You can use the access control list (ACL) object to set and control user access for
other SmartCloud Orchestrator resources.
Virtual images REST API on page 1019
You can use the representational state transfer (REST) application programming
interface (API) to manage virtual images.
Related information:
Jython
Python documentation
898 IBM SmartCloud Orchestrator 2.3: User's Guide
Virtual machines on the command-line interface
This topic provides a reference for administering virtual machines using the
SmartCloud Orchestrator command-line interface.
For general information about working with the command-line interface, see the
Using the command-line interface on page 805 section.
VirtualMachines object
A VirtualMachines object represents the collection of virtual machines within a
virtual system instance on SmartCloud Orchestrator. Objects of this type are used
to create, delete, iterate over, list and search for virtual machines within a virtual
system instance on SmartCloud 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
SmartCloud 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 SmartCloud 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 SmartCloud Orchestrator.
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 815 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.
Chapter 11. Reference 899
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 SmartCloud Orchestrator.
Therefore, updates have no effect on the virtual machine.
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 SmartCloud 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.
900 IBM SmartCloud Orchestrator 2.3: User's Guide
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 834 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 834 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.
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 893 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 command-line interface reference on page 902 or enter the
following command:
Chapter 11. Reference 901
>>> 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 805 section. For more information about working
with resources on the command-line interface, see the Resources, resource
collections, and methods on page 914 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 935 topic.
Related tasks:
Using the command-line interface on page 805
To perform administrative functions for SmartCloud Orchestrator, you can
download the command-line interface from SmartCloud Orchestrator onto a local
machine. You can then run the command-line interface from the local machine.
Related information:
Jython
Python documentation
Virtual system instances command-line interface reference
This topic provides a reference for administering virtual system instances using the
SmartCloud Orchestrator command-line interface.
For general information about working with the command-line interface, see the
Using the command-line interface on page 805 section.
VirtualSystems object
A VirtualSystems object represents the collection of virtual system instances
defined to the SmartCloud Orchestrator. Objects of this type are used to create,
delete, iterate over, list and search for virtual system instances on the SmartCloud
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:
902 IBM SmartCloud Orchestrator 2.3: User's Guide
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 819 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 Pattern command-line interface reference on page
844 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:
>>> # 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 SmartCloud
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:
Chapter 11. Reference 903
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 part-
1.ConfigPWD_ROOT.password, the dict keys are considered in the
following order:
1. part-1.ConfigPWD_ROOT.password
2. *.ConfigPWD_ROOT.password
3. part-1.*.password
4. *.*.password
5. part-1.ConfigPWD_ROOT.*
6. *.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
904 IBM SmartCloud Orchestrator 2.3: User's Guide
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.
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.
Chapter 11. Reference 905
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 933 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:
>>> deployer.virtualsystems.create([vs1, {name:foo,...}])
VirtualSystem object
A VirtualSystem object represents a particular virtual system instance defined on
SmartCloud Orchestrator. Use the VirtualSystem object to query and manipulate
the virtual system instance definition on the SmartCloud Orchestrator. Attributes of
the virtual system instance and relationships between the virtual system instance
and other resources on the SmartCloud 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 SmartCloud
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)
906 IBM SmartCloud Orchestrator 2.3: User's Guide
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 SmartCloud Orchestrator to initiate the steps to
get the virtual system instance to this state.
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 819 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
Chapter 11. Reference 907
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 Pattern command-line interface
reference on page 844 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 880 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 on the
command-line interface on page 899 or enter the following command:
>>> help(deployer.virtualmachines)
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
908 IBM SmartCloud Orchestrator 2.3: User's Guide
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 805 section. For more information about working
with resources on the command-line interface, see the Resources, resource
collections, and methods on page 914 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 935 topic.
Related tasks:
Using the command-line interface on page 805
To perform administrative functions for SmartCloud Orchestrator, you can
download the command-line interface from SmartCloud Orchestrator onto a local
machine. You can then run the command-line interface from the local machine.
Related information:
Jython
Python documentation
Downloading and configuring the command-line interface
To perform administrative functions for SmartCloud Orchestrator, you can use the
command-line interface. You can download the command-line interface on a local
machine.
Before you begin
Be sure that you have Java Runtime Environment (JRE), version 6 installed on the
machine on which the command-line interface is to be run. You can download this
version for Linux from the following Web address: http://www.ibm.com/
developerworks/java/jdk/linux/download.html.
About this task
The SmartCloud Orchestrator command-line interface is currently supported on
Windows and Linux systems.
Chapter 11. Reference 909
Procedure
1. Required: Download the command-line interface. From the SmartCloud
Orchestrator web user interface Home page, click the Download command-line
tools link.
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
Results
You have installed the SmartCloud 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
You can now initialize the command-line interface using the Invoking the
command-line interface on page 911 information.
Related tasks:
Invoking the command-line interface on page 911
To perform administrative functions for SmartCloud 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.
Related information:
http://www.ibm.com/developerworks/java/jdk/linux/download.html
910 IBM SmartCloud Orchestrator 2.3: User's Guide
Invoking the command-line interface
To perform administrative functions for SmartCloud 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 909. If you recently upgraded your SmartCloud 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 SmartCloud 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 SmartCloud
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
SmartCloud 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.
-p <password> or
--password
This optional parameter specifies the password used to authenticate to
SmartCloud 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
Chapter 11. Reference 911
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 SmartCloud 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 SmartCloud
Orchestrator command to execute your Jython scripts. If the SmartCloud
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:
#!/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 on page
913
912 IBM SmartCloud Orchestrator 2.3: User's Guide
913 For a list of the available objects to be used in the command-line interface, see
Command-line interface resource object reference on page 808. A set of sample
scripts that demonstrate some of the command-line interface function are located
in the <cli_install_dir>\samples directory.
Using the command-line interface for applications
You can use the command-line interface to manage your virtual application
patterns, pattern types, virtual application instances and plug-ins.
About this task
See the following sections:
v Pattern type command-line interface
v Virtual application pattern command-line interface
v Virtual application instance command-line interface
Getting help on the command-line interface
As you perform administrative functions for SmartCloud 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 909 and Invoking the command-line interface on page 911.
About this task
You can get help for any SmartCloud 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 911), 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 SmartCloud Orchestrator command-line interface.
In interactive mode, you can invoke deployer.help without the package prefix,
as shown in the following example:
>>> help
Chapter 11. Reference 913
v Invoke help for the package. Help is available for the SmartCloud Orchestrator
package.
To get help for the SmartCloud 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 SmartCloud 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.
Resources, resource collections, and methods
SmartCloud Orchestrator manages different types of resources, for example
hypervisors, 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 SmartCloud Orchestrator is represented in the
command-line interface by a Jython object. This object has the same attributes as
the SmartCloud 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
SmartCloud 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 SmartCloud Orchestrator. When you call one of these methods
within the command-line interface tool, the request is sent over HTTPS to the
914 IBM SmartCloud Orchestrator 2.3: User's Guide
SmartCloud 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
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, resource collections, and methods are explained more thoroughly in the
following information:
Resources
Resources on the command line on page 916
Resource collections
Resource collections on the command line on page 920
Methods for resources
Resource methods on the command-line interface on page 921
Methods for resource collections
Resource collections methods on the command-line interface on page 927
Chapter 11. Reference 915
Available resources
Command-line interface resource object reference on page 808
Resources on the command line
Any SmartCloud 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 SmartCloud Orchestrator command-line
interface manages different types of resources, for example hypervisors, patterns,
virtual images, and virtual system instances.
The SmartCloud Orchestrator command-line interface uses resources to represent
discrete objects managed by the SmartCloud 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)
}
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 currentstatus_text
v email
v fullname
v id
v 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
916 IBM SmartCloud Orchestrator 2.3: User's Guide
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
SmartCloud Orchestrator.
The SmartCloud 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
Some errors are detected by the SmartCloud Orchestrator command-line interface
and others are detected by the SmartCloud Orchestrator.
If you need more information about a particular resource, you can pass the
resource to the SmartCloud 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 SmartCloud Orchestrator automatically track the time
and date they were created and last modified. Within the SmartCloud 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 SmartCloud Orchestrator to seconds. The
Chapter 11. Reference 917
SmartCloud 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 SmartCloud Orchestrator resources also have status attributes that
reflect the current and intended status of the resource. The SmartCloud
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
SmartCloud 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 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,
918 IBM SmartCloud Orchestrator 2.3: User's Guide
"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,
"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
}
Chapter 11. Reference 919
Resource collections on the command line
SmartCloud 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 SmartCloud
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 SmartCloud
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 SmartCloud Orchestrator. These are the resource types you can select directly
when using the SmartCloud Orchestrator user interface. These types of resource
collections are accessed directly with objects defined in the SmartCloud
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 SmartCloud Orchestrator that did not exist previously. Similarly,
delete completely erases a resource from SmartCloud 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.
These resource collections are available as attributes on the SmartCloud
Orchestrator package, as shown in the following example:
>>> 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",
920 IBM SmartCloud Orchestrator 2.3: User's Guide
"secondarydns": "10.0.0.3",
"subnetaddress": "10.0.0.0",
"updated": May 13, 2009 3:46:15 PM
},
{
"created": May 13, 2009 4:51:02 PM,
"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
}
]
The SmartCloud Orchestrator package defines one of these types of resource
collections for each type of resource that SmartCloud 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 SmartCloud Orchestrator resources share methods that can be used to work
with resource objects.
Purpose
This topic describes the methods shared by all SmartCloud Orchestrator resources.
For more information about resources, see Resources on the command line on
page 916.
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:
>>> 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:
Chapter 11. Reference 921
>>> 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 SmartCloud 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 808 also provides a
listing of resources and resource collections with links to more information about
them.
Methods
SmartCloud 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:
922 IBM SmartCloud Orchestrator 2.3: User's Guide
>>> address in ipg
1
>>> foo in ipg
0
__delattr__(name)
Removes an attribute for this resource in SmartCloud 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 SmartCloud 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
SmartCloud Orchestrator. It does not check for a match between the cached
attributes of the two objects.
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
Chapter 11. Reference 923
__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 SmartCloud 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 SmartCloud
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 SmartCloud Orchestrator, as shown in the
following example:
>>> ipg.gateway
10.0.0.1
(change ipgroup gateway from a different CLI or GUI)
>>> 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),
924 IBM SmartCloud Orchestrator 2.3: User's Guide
"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
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
Chapter 11. Reference 925
"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 SmartCloud 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 916
Any SmartCloud 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 SmartCloud Orchestrator command-line
interface manages different types of resources, for example hypervisors, patterns,
virtual images, and virtual system instances.
Related information:
Jython
Python documentation
926 IBM SmartCloud Orchestrator 2.3: User's Guide
Resource collections methods on the command-line interface
All SmartCloud Orchestrator resource collections share methods that you can use
to work with these objects.
Purpose
This topic describes the methods shared by all SmartCloud Orchestrator resource
collections. For more information about resource collections, see Resource
collections on the command line on page 920. 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)
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
Chapter 11. Reference 927
__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 933 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 SmartCloud 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)
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
928 IBM SmartCloud Orchestrator 2.3: User's Guide
__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 SmartCloud 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).
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,
Chapter 11. Reference 929
"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:
>>> len(deployer.ipgroups)
2
>>> if deployer.ipgroups:
... print true
... else:
... print false
...
true
>>> len(deployer.hypervisors)
930 IBM SmartCloud Orchestrator 2.3: User's Guide
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 SmartCloud 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 SmartCloud 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:
>>> 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",
Chapter 11. Reference 931
"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 2:13:59 PM,
"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
}
]
__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 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 2:13:59 PM,
"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
}
]
__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)
932 IBM SmartCloud Orchestrator 2.3: User's Guide
Related concepts:
Resources on the command line on page 916
Any SmartCloud 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 SmartCloud 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
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
Chapter 11. Reference 933
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 920
SmartCloud 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.
Resources on the command line on page 916
Any SmartCloud 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 SmartCloud Orchestrator command-line
interface manages different types of resources, for example hypervisors, patterns,
virtual images, and virtual system instances.
934 IBM SmartCloud Orchestrator 2.3: User's Guide
Related information:
Jython
Python documentation
ACL object
You can use the access control list (ACL) object to set and control user access for
other SmartCloud 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 810.
Clouds For more information about clouds, see Cloud group command-line
interface reference on page 815.
EnvironmentProfiles
For more information about environment profiles, see Environment
profiles on the command-line interface on page 820.
Hypervisors
For more information about hypervisors, see Hypervisor command-line
interface reference on page 830.
Patterns
For more information about patterns, see Pattern command-line interface
reference on page 844.
Scripts
For more information about scripts, see Script package command-line
interface reference on page 876.
Virtual images
For more information about virtual images, see Virtual images
command-line interface reference on page 893.
Virtual systems
For more information about virtual systems, see Virtual system instances
command-line interface reference on page 902.
ACL object
The ACL object represents the ACL associated with a SmartCloud Orchestrator
resource. The SmartCloud Orchestrator manages access to resources with a
hierarchical set of permissions. These permissions are represented by constants in
the SmartCloud Orchestrator package. From the least access to greatest access,
these permissions are:
NO_PERMISSIONS
The user cannot access the resource.
READ_PERMISSION
The user can view the resource and use it in a read-only manner, but
cannot alter the resource.
Chapter 11. Reference 935
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 SmartCloud 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
__len__()
Returns the number of permissions explicitly set for this resource, as
shown in the following example:
>>> len(deployer.scripts[0].acl)
936 IBM SmartCloud Orchestrator 2.3: User's Guide
refresh()
Refreshes the cached ACL entries with current data from the SmartCloud
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 deployer.NO_PERMISSIONS
v deployer.READ_PERMISSION
v deployer.UPDATE_PERMISSION
v deployer.CREATE_PERMISSION
v 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 914 section.
Related concepts:
Resources on the command line on page 916
Any SmartCloud 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 SmartCloud Orchestrator command-line
interface manages different types of resources, for example hypervisors, patterns,
virtual images, and virtual system instances.
Related information:
Jython
Chapter 11. Reference 937
Python documentation
Additional command-line interface utilities
The SmartCloud 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 SmartCloud 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 SmartCloud 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 SmartCloud 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 SmartCloud
Orchestrator command-line interface session. In interactive mode, enter the
following command:
>>> exit
In batch mode, enter the following command:
>>> deployer.exit
938 IBM SmartCloud Orchestrator 2.3: User's Guide
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 SmartCloud 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
SmartCloud 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.
The deployer.waitFor returns the value obtained the last time the condition was
evaluated.
Chapter 11. Reference 939
For more information about working with resource objects, see the Resources,
resource collections, and methods on page 914 section.
Related concepts:
Resources on the command line on page 916
Any SmartCloud 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 SmartCloud 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 SmartCloud Orchestrator.
Before you begin
The product exposes a subset of its function using a REST API. If you require
function beyond what is available in the REST API described here, then you can
consider using the product command-line interface instead. The REST API and the
command-line interface share many paradigms for managing the product, but the
command-line interface provides a richer scripting environment and more
complete set of function. For more information about the command-line interface,
see Using the command-line interface on page 805.
Each product exposes a REST API as there are no special configuration settings to
enable or disable this interface. The SmartCloud 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.
When generating HTTP requests to the SmartCloud 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
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
940 IBM SmartCloud Orchestrator 2.3: User's Guide
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-Workload-
Deployer-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.
Related tasks:
Using the command-line interface on page 805
To perform administrative functions for SmartCloud Orchestrator, you can
download the command-line interface from SmartCloud Orchestrator onto a local
machine. You can then run the command-line interface from the local machine.
REST API frameworks
This topic describes the REST API frameworks used in an SmartCloud Orchestrator
environment for REST calls (client and server).
They are:
v org.apache.wink 1.1.3: used by Workload Deployer and SmartCloud
Orchestrator.
v javax.net.ssl.HttpsURLConnection: used by the genericREST implemented by
SmartCloud Orchestrator that makes Rest calls from Business Process Manager
to SmartCloud Orchestrator.
v org.apache.http: used by Business Process Manager to connect to OpenStack.
For customized REST calls that are implemented outside of SmartCloud
Orchestrator, make sure that the compatible REST API framework is used. For
example, if you implement a script that makes REST calls against SmartCloud
Orchestrator, you must use the org.apache.wink 1.1.3 framework or any other
compatible REST API framework.
Chapter 11. Reference 941
Note: For non compatible REST API framework you will get 'incompatible with
....... ' errors.
Application patterns REST API
You can use the REST API to manage your virtual application patterns.
The following tasks can be completed using the REST API.
List all application patterns
GET /resources/applicationPatterns/
Table 73. List all application patterns.
Example URL https://localhost/resources/applicationPatterns/
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": "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"
},
...
]
Create an application pattern with specific attributes
POST /resources/applicationPatterns/
Different kinds of attributes can be combined. A unique ID is generated for the
application.
Table 74. Create an application pattern with specific attributes details.
Example URL https://localhost/resources/applicationPatterns/
Request body
Content-type
Content-Type - application/json (appmodel json file)
Content-Type - application/zip file (zip file including
application model and artifacts files)
Request body example JSON Application model
Response content-type application/json
942 IBM SmartCloud Orchestrator 2.3: User's Guide
Table 74. Create an application pattern with specific attributes details. (continued)
Response header location https://localhost/resources/applicationPatterns/a-4e21f6e9-
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
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/applicationPatterns/?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)
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 75. Create an application pattern from an existing application or template (clone)
details.
Example URL https://localhost/resources/applicationPatterns/?source=a-
679a68f4-6798-424f-8039-1f682f949f45&app_name=testApp
Create an application name "testApp" from application with
id " a-679a68f4-6798-424f-8039-1f682f949f45"
Response content-type application/json
Response header location https://localhost/resources/applicationPatterns/a-fb70796e-
1b13-467a-babe-b8b700bd563b
Chapter 11. Reference 943
Table 75. Create an application pattern from an existing application or template (clone)
details. (continued)
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"
}
List the application patterns with various filters
GET /resources/applicationPatterns/?<filter>=<filterString>
v Filter "app_name": Filter application pattern with application name.
v Filter "app_type": Filter application pattern with application type. filterString can
be application, template or service (for shared service). If filterString is null or
empty, all application pattern are returned.
Important: The result lists only the application with R access for the request.
v v Filter patterntype and version: Filter application patterns with versioned
pattern type, for example, ?patterntype=webapp&version=1.0
Table 76. List application pattern with various filters details.
Example URL https://localhost/resources/applicationPatterns/
?app_name=web%20application&app_type=template
Retrieve all application templates whose name contains
string "web application".
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
944 IBM SmartCloud Orchestrator 2.3: User's Guide
Response example:
[
{
"content_type": "application/json",
"last_modifier": "cbadmin",
"create_time": 2011-02-24T05:41:34Z,
"last_modified": 2011-02-24T05:41:34Z,
"access_rights": {
"AllUsers": "R"
},
"content_md5": "2565A57FC11492698869ADCF7C48154E",
"app_type": "template",
"app_id": "a-14057bbd-9651-461a-a597-5df8957110fc",
"app_name": "web application",
"creator": "cbadmin"
},
...
]
Update application pattern
PUT /resources/applicationPatterns/{app_id}
Table 77. Update application pattern details.
Example URL https://localhost/resources/applicationPatterns/a-cdaac959-
672c-4df7-a648-b333a3843422
Response content-type and
body
Content-Type - application/json (body is the application
model json file)
Content-Type - application/zip (body is zip file, including
the application model and artifacts files)
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 specified by
{appID} is not found.
412 Invalid parameter supplied,
for example, the json file is
invalid.
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"
}
Chapter 11. Reference 945
Return detailed information about the application pattern
GET /resources/applicationPatterns/{app_id}
Table 78. Return detailed information about the application pattern.
Example URL https://localhost/resources/applicationPatterns/a-679a68f4-
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 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",
"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 Directory Service, and DB2. Access HitCount via
http://[IP]:9080/hitcount, where [IP] is the IP of the deployed WebSphere
Application Server virtual machine."
}
Download the application pattern zip file, including all artifacts
and the json file
GET /resources/applicationPatterns/{app_id}?zip
Table 79. Download the application pattern zip file, including all artifacts and the json file
details.
Example URL https://localhost/resources/applicationPatterns/a-679a68f4-
6798-424f-8039-1f682f949f45?zip
Response content-type application/json
Response body Application zip file
Response code 200 OK
401 The user is not authorized to
perform this action.
403 Access forbidden
404 The application specified by
{appID} is not found.
500 Unexpected error
946 IBM SmartCloud Orchestrator 2.3: User's Guide
Update application pattern access right for the specified user
name or group name
PUT /resources/applicationPatterns/{app_id}/accessRights/{name}?{ user or group }
Table 80. Update application pattern access right details.
Example URL https://localhost/resources/applicationPatterns/a-cdaac959-
672c-4df7-a648-b333a3843422/accessRights/Everyone?group
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 specified by
{appID} is not found.
412 Invalid parameter supplied,
for example, the json file is
invalid.
500 Unexpected error
Response example:
{ "access_rights": "F"}
Delete a specified application pattern
DELETE /resources/applicationPatterns/{app_id}
Table 81. Delete a specified application pattern details.
Example URL https://localhost/resources/applicationPatterns/a-cdaac959-
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
Artifacts REST API
List all artifacts of a given application pattern
GET /resources/applicationPatterns/{app_id}/artifacts/
Table 82. List all artifact of a given application pattern details.
Example URL https://localhost/resources/applicationPatterns/
a-cdaac959-672c-4df7-a648-b333a3843422/artifacts/
Response content-type application/json
Chapter 11. Reference 947
Table 82. List all artifact of a given application pattern details. (continued)
Response code 200 OK
401 The user is not authorized to
perform this action.
403 Access forbidden
404 Application specified by
{appID} is not found.
500 Unexpected error
Response example:
[
{
"content_type": "application/octet-stream",
"last_modifier": "tester",
"create_time": 2011-02-24T05:41:34Z,
"last_modified": 2011-02-24T05:41:34Z,
"access_rights": {
"tester": "F"
},
"content_md5": "64C79B6A807A13B028E5E43E950E09BD",
"name": "CounterDB.sql",
"creator": "tester"
},
...
]
Upload an artifact file
PUT /resources/applicationPatterns/{app_id}/artifacts/{filename}
The file is overwritten if the file already exists.
Table 83. Upload an artifact file details.
Example URL https://localhost/resources/applicationPatterns/792f2265-
2a1d-411a-b5d6-c40d658539a1/artifacts/test.war
Request content-type application/octet-stream
Request body Artifact file
Response content-type application/json
Response code 200 OK
401 The user is not authorized to
perform this action.
403 Access forbidden
404 Application specified by
{appID} is not found.
500 Unexpected error
Response example:
{
"file": "artifacts/test.war"
}
Download an artifact file
GET /resources/applicationPatterns/{app_id}/artifacts/{filename}?download
948 IBM SmartCloud Orchestrator 2.3: User's Guide
Table 84. Download an artifact file details.
Example URL https://localhost/resources/applicationPatterns/792f2265-
2a1d-411a-b5d6-c40d658539a1/artifacts/test.war?download
Response content-type application/octet-stream
Response body Artifact file
Response code 200 OK
401 The user is not authorized to
perform this action.
403 Access forbidden
404 Application specified by
{appID} is not found.
500 Unexpected error
Get the detail of the artifact
GET /resources/applicationPatterns/{app_id}/artifacts/{filename}
Table 85. Get the detail of the artifact.
Example URL https://localhost/resources/applicationPatterns/792f2265-
2a1d-411a-b5d6-c40d658539a1/artifacts/test.ddl
Response content-type application/json
Response code 200 OK
401 The user is not authorized to
perform this action.
403 Access forbidden
404 Application specified by
{appID} is not found.
500 Unexpected error
Response example:
{
"content_type": "application/octet-stream",
"last_modifier": "cbadmin",
"create_time": "2011-05-14T06:04:36Z",
"last_modified": "2011-05-14T06:04:36Z",
"access_rights": {
"cbadmin": "F",
"_group_:Everyone": "R"
},
"content_md5": "68C84965B52D8BC66D5DCB7CD0E2B774",
"creator": "cbadmin"}
Delete an artifact file
DELETE /resources/applicationPatterns/{app_id}/artifacts/{filename}
Table 86. Delete an artifact file details.
Example URL https://localhost/resources/applicationPatterns/792f2265-
2a1d-411a-b5d6-c40d658539a1/artifacts/test.war
Response content-type application/json
Chapter 11. Reference 949
Table 86. Delete an artifact file details. (continued)
Response code 200 OK
Note: If the application
specified by {app_id} or the
artifact specified by
{filename} 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
404 Application specified by
{appID} is not found.
500 Unexpected error
Auditing REST API
You can use the representational state transfer (REST) application programming
interface (API) to download and delete audit data, in the form of event records,
from the SmartCloud Orchestrator event log. These event records document user
activity, security events, and configuration changes in the product and in the cloud.
Available HTTP Methods
Following this reference table are two examples that demonstrate how to construct
HTTP requests to use the REST API auditing resources. These examples show any
requisite attributes for the requests.
Table 87. REST API for working with audit event records
HTTP
Methods URI Pattern Data Format Success Codes Error Codes
GET /audit/
archiver/events
You must specify a .zip file for
downloading the event records.
You can write your own scripts to
do this, or use sample scripts that
SmartCloud Orchestrator provides.
These scripts authenticate you as
an auditor with the REST API,
download the audit event records
to a .zip file, and unzip the file.
See Retrieving audit data with
the REST API on page 279 for
details.
200 Returns
OK
403 This code is returned if
the requester does not
have the admin role.
500 This code is returned if
the SmartCloud
Orchestrator
encountered an internal
error while processing
the request.
GET /audit/
archiver/
filteredEvents
As described previously, you must
specify a .zip file for the
downloading process. You can
write your own scripts to do this,
or use sample scripts that
SmartCloud Orchestrator provides.
See Retrieving audit data with
the REST API on page 279 for
details.
200 Returns
OK
403 This code is returned if
the requester does not
have the admin role.
500 This code is returned if
the SmartCloud
Orchestrator
encountered an internal
error while processing
the request.
950 IBM SmartCloud Orchestrator 2.3: User's Guide
Table 87. REST API for working with audit event records (continued)
HTTP
Methods URI Pattern Data Format Success Codes Error Codes
POST /audit/
archiver/events
application/json
204 The
event
records
have
been
deleted.
403 This code is returned if
the requester does not
have the admin role.
500 This code is returned if
the SmartCloud
Orchestrator
encountered an internal
error while processing
the request.
GET /audit/archiver/events example
When you make a request for the events resource, you must specify a maximum
number of records to download with the size attribute. 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.
Use the following URL as a model for your HTTP request:
https://example.com:9444/audit/archiver/events?size=X
GET /audit/archiver/filteredEvents example
To specify a time frame for the event records that you want to download, construct
a request for filteredEvents with the following three attributes:
size As stated previously, your value for this attribute specifies a maximum
number of records 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 writes that number of records to the .zip file.
startTime
Specifies an Epoch timestamp as the beginning of the time frame. (Use the
time conversion tool of your choice to convert your desired date and times
into Epoch timestamps.)
endTime
Specifies an Epoch timestamp as the end of the time frame.
For example:
https://example.com:9444/audit/archiver/filteredEvents?size=X&startTime=long_value
&endTime=long_value
Important: When you use either GET request to retrieve a .zip file of audit
records, the .zip file that you receive contains the following four files:
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
Chapter 11. Reference 951
The last two files contain data that you must send back to the REST API via the
POST method, to delete the event records.
POST /audit/archiver/events
To help safeguard your auditing processes, SmartCloud 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 product machine.
Use the POST method to perform the deletion operation. As part of the HTTP
request, you must specify a JSON object. This object must contain the string values
of the contents of the following two files, which are products of your previous
GET request to download event records: audit-events-record-IDs and
audit-events-signed-record-IDs.
JSON example:
{"eventIDList":"1001,1002,1003,1004...","eventIDListSignature":"ZktVcUM4YXM3YXE5..."}
(The ellipses characters are simply abbreviations to minimize the length of the
example.)
Related tasks:
Retrieving audit data with the REST API on page 279
For retrieving audit event records with the REST API, SmartCloud 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.
Deleting audit data to free storage on page 284
To help safeguard your auditing processes, SmartCloud 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 SmartCloud Orchestrator REST
API.
REST API reference on page 940
The representational state transfer (REST) application programming interface (API)
is provided by SmartCloud Orchestrator.
Certificates REST API
You can use the representational state transfer (REST) application programming
interface (API) to manage certificates.
952 IBM SmartCloud Orchestrator 2.3: User's Guide
Available HTTP Methods
Table 88. REST API for Certificates
HTTP
Method URI Pattern DATA Format Success Codes Error Codes
GET
v For stand-alone hypervisors:
/resources/hypervisors/{id}/
certificate
v For a cloud group:
/resources/clouds/{id}/
certificate
application/
json
200 This code
returns a
formatted
certificate for
the specified
hypervisor. See
the example for
a sample of the
data that is
returned.
403 This code is
returned if the
requester has
not been
assigned the
admin role.
404 This code is
returned if:
v the
hypervisor
does not
return a
certificate.
v no cloud or
hypervisor
with the
specified id
exists
500 This code is
returned if the
SmartCloud
Orchestrator
encountered an
internal error
while
processing the
request.
GET /resources/hypervisors/{id}/certificate example
{
"id": 1,
"certificates": [
"Certificate: 1",
"",
"Version: 3",
"",
"Subject: OID.1.2.840.113549.1.9.2=\"1233003790,564d7761726520496e632e\",
CN=myhypervisor.mycompany.com, OU=VMware ESX Server Certificate,
[email protected], O=\"VMware, Inc.\", L=Palo Alto,
ST=California, C=US",
"",
"Key: ",
" IBMJCE RSA Public Key:",
" modulus:",
" 1339803331059169396205872003875740052553863051674618430116476617574249",
" 5026411738717148849905840700453727318717943418667122434412630187079348",
" 6873813288481494146160025627725751470887183385307527405440695734180966",
" 8462579382022195458840146325997544446223584485323748610456300364783827",
" 68380160577053130037267269337",
" public exponent:",
" 65537",
"",
"Validity: ",
" From: Mon Jan 26 16:03:11 EST 2009",
Chapter 11. Reference 953
" To: Mon Mar 27 17:03:11 EDT 2028",
"",
"Issuer: OID.1.2.840.113549.1.9.2=\"1233003790,564d7761726520496e632e\",
CN=myhypervisor.mycompany.com, OU=VMware ESX Server Certificate,
[email protected], O=\"VMware, Inc.\", L=Palo Alto,
ST=California, C=US",
"",
"Serial Number:",
" 0",
"",
"Signature: ",
" Algorithm: MD5withRSA",
" Algorithm OID: 1.2.840.113549.1.1.4",
"",
" 0000: 53 73 eb f0 f0 bb 4c 48 ea d4 23 0c 20 e1 4f b7 Ss....LH......O.",
" 0010: aa 7d 64 aa 5f cc c7 a4 fa b0 38 73 9c 94 eb 77 ..d.......8s...w",
" 0020: c8 2a 51 bb 34 7c 2f b6 90 c8 25 f1 e3 90 18 ea ..Q.4...........",
" 0030: bb 63 08 a0 2f 66 c4 36 9a d1 98 29 1f 37 d4 0d .c...f.6.....7..",
" 0040: 5e 10 20 ac 1c d3 bc 2f 4e e8 b4 65 3d 3e 90 ed ........N..e....",
" 0050: 90 64 9e f6 d0 f0 a7 31 ba 13 b3 93 69 a3 39 59 .d.....1....i.9Y",
" 0060: 73 c9 f3 4f 22 3c 7e 3d 08 6b 09 6f ac 82 e4 bb s..O.....k.o....",
" 0070: d6 32 0f ba eb 29 47 20 24 78 1c d2 cb ed fb 4b .2....G..x.....K"
]
}
Note: Key-value pairs that are only used by user interface clients are optional.
Related tasks:
REST API reference on page 940
The representational state transfer (REST) application programming interface (API)
is provided by SmartCloud Orchestrator.
Cloud groups REST API
You can use the representational state transfer (REST) application programming
interface (API) to manage cloud groups.
Available HTTP Methods
Table 89. REST API for Clouds
HTTP
Method URI Pattern Data Format Success Codes Error Codes
GET /resources/clouds application/json
200 Returns the list of
cloud groups defined
in the product. See
the example for a
sample of the data
returned.
403 This code is returned
if the requester has
not been assigned the
admin role.
500 This code is returned
if the SmartCloud
Orchestrator
encountered an
internal error while
processing the
request.
954 IBM SmartCloud Orchestrator 2.3: User's Guide
Table 89. REST API for Clouds (continued)
HTTP
Method URI Pattern Data Format Success Codes Error Codes
POST /resources/clouds application/json
201 Returned when the
cloud group has been
created and is
included in the
response body. The
URL of the new
cloud group is
included in the
Location header of
the response.
400 This code is returned
if there are problems
parsing the JSON
data in the request.
403 This code is returned
if the requester has
not been assigned the
admin role.
500 This code is returned
if SmartCloud
Orchestrator
encountered an
internal error while
processing the
request.
GET /resources/clouds/
{id}
application/json
200 Returns information
about a specific
cloud group defined
to SmartCloud
Orchestrator.
403 This code is returned
if the requester has
not been assigned the
admin role.
404 This code is returned
if the requested cloud
group is not defined.
500 This code is returned
if the SmartCloud
Orchestrator
encountered an
internal error while
processing the
request.
PUT /resources/clouds/
{id}
application/json
200 The cloud group was
successfully updated.
The response body
contains a JSON
representation of the
current state of the
cloud group.
400 This code is returned
if there are problems
parsing the JSON
data in the request.
403 This code is returned
if the requester has
not been assigned the
admin role.
404 This code is returned
if the requested cloud
group is not defined.
500 This code is returned
if the SmartCloud
Orchestrator
encountered an
internal error while
processing the
request.
Chapter 11. Reference 955
Table 89. REST API for Clouds (continued)
HTTP
Method URI Pattern Data Format Success Codes Error Codes
DELETE /resources/clouds/
{id}
204 The cloud group has
been deleted.
403 This code is returned
if the requester has
not been assigned the
admin role.
404 This code is returned
if the requested cloud
group is not defined.
500 This code is returned
if the SmartCloud
Orchestrator
encountered an
internal error while
processing the
request.
GET /resources/clouds/
{id}/images
application/json
200 Returns the list of
images of the
selected cloud group.
See the example for a
sample of the data
returned.
500 This code is returned
if SmartCloud
Orchestrator
encountered an
internal error while
processing the
request.
GET /resources/clouds/
{id}/images/
{image_id}
/resources/clouds/
{id}/images/
{image_id}.ovf
application/json
200 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.
500 This code is returned
if SmartCloud
Orchestrator
encountered an
internal error while
processing the
request.
The cloud group has the following attributes:
address
The network address or host name used to communicate with the
hypervisor manager.
certified
Indicates if the SSL certificate from this VMware Virtual Center has been
accepted. Use the Cloud.acceptCertificate() method to accept a certificate.
created
Specifies the creation time of the cloud group, represented as the number
of milliseconds since midnight, January 1, 1970 UTC. This value is numeric
and is automatically generated by the product. This attribute is available
for all cloud groups.
currentstatus
The current status of the Cloud object. This attribute contains an 8
character string value that is generated by the product.
956 IBM SmartCloud Orchestrator 2.3: User's Guide
currentstatus_text
This is a string representation of currentstatus in the preferred language
of the requester and is automatically generated by the product. This
attribute is read-only.
defaultcloud
Specifies if this cloud group is the default cloud group used by
SmartCloud Orchestrator. User created cloud groups will always have this
value set to 'F'. This field expects a string value of 'T' or 'F' with a
maximum of 1 character.
description
Specifies a description of the cloud group. This field expects a string value
with a maximum of 1024 characters.
endpointtype
Specifies the type of endpoints managed by the cloud group. This
read-only value depends on the target endpoints currently added to the
cloud group. The value of the endpoint type can be one of the following:
Hypervisor
The cloud group manages one or more hypervisor endpoints.
Pool The cloud group manages a pool.
Cluster
The cloud group manages a cluster.
None The cloud group does not manage any endpoint.
Mixed The cloud group manages endpoints of multiple types.
hypervisors
Specifies a list of the uniform resource identifiers (URIs) of the hypervisors
that are assigned to the cloud group. The URIs are relative and should be
resolved against the URI of the cloud group that contains them.
id Specifies the ID of the cloud group. This numeric value is automatically
generated by the product.
name Specifies the name associated with this cloud group. This field expects a
string value with a maximum of 64 characters. Each cloud group must
have a unique name.
owner Specifies the user that is the owner of this cloud.
password
Password used to access the hypervisor manager that manages the cloud
group.
type The type of this cloud group. This value is manager.
updated
Specifies the time the cloud group 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.
userid Userid used to access the hypervisor manager that manages the cloud
group.
vendor
Specifies the type of hypervisors that this cloud group will contain. This
field expects a string value with a maximum of 128 characters. This string
value must always be OpenStack.
Chapter 11. Reference 957
GET /resources/clouds example
[
{
"cputhreshold": 100,
"availabilityzone": "nova_smartcloud",
"vendor": "OpenStack",
"name": "RegionVmware_nova_smartcloud",
"ownerid": 40,
"defaultcloud": "F",
"defaultimageid": 0,
"deploymentlimit": 10,
"thinservers": "T",
"id": 22,
"password": "13884987056396",
"useinternalreserveip": "T",
"useinternalplacement": "T",
"userid": "admin",
"certified": "T",
"diskovercommit": 0,
"created": 1388498705611,
"currentstatus": "RM10394",
"pcputhreshold": 100,
"region": "RegionVmware",
"address": "https://regionvmware_nova_smartcloud",
"attachvolumes": null,
"memthreshold": 100,
"type": "manager",
"updated": 1388498705611,
"description": ""
},
{
"cputhreshold": 100,
"availabilityzone": "nova",
"vendor": "OpenStack",
"name": "RegionKvm_nova",
"ownerid": 40,
"defaultcloud": "F",
"defaultimageid": 0,
"deploymentlimit": 10,
"thinservers": "T",
"id": 23,
"password": "138918697987521",
"useinternalreserveip": "T",
"useinternalplacement": "T",
"userid": "admin",
"certified": "T",
"diskovercommit": 0,
"created": 1389186979832,
"currentstatus": "RM10328",
"pcputhreshold": 100,
"region": "RegionKvm",
"address": "https://regionkvm_nova",
"attachvolumes": null,
"memthreshold": 100,
"type": "manager",
"updated": 1389186979832,
"description": ""
}
]
POST /resources/clouds example
Request JSON:
958 IBM SmartCloud Orchestrator 2.3: User's Guide
{
"defaultcloud": "F",
"description": "a test cloud group",
"name": "Test cloud group",
"type": null,
"vendor": "OpenStack"
}
Response JSON:
{
"created": 1255055319725,
"currentstatus": "RM10330",
"currentstatus_text": "No hypervisors in cloud group",
"defaultcloud": "F",
"description": "a test cloud",
"hypervisors": [
],
"id": 18,
"name": "Test cloud",
"owner": "/resources/users/1",
"type": null,
"updated": 1255055319725,
"vendor": "OpenStack"
}
GET /resources/clouds/{id} example
{
"cputhreshold": 100,
"availabilityzone": "nova_smartcloud",
"vendor": "OpenStack",
"name": "RegionVmware_nova_smartcloud",
"ownerid": 40,
"defaultcloud": "F",
"defaultimageid": 0,
"deploymentlimit": 10,
"thinservers": "T",
"id": 22,
"password": "13884987056396",
"useinternalreserveip": "T",
"useinternalplacement": "T",
"userid": "admin",
"certified": "T",
"diskovercommit": 0,
"created": 1388498705611,
"currentstatus": "RM10394",
"pcputhreshold": 100,
"region": "RegionVmware",
"address": "https://regionvmware_nova_smartcloud",
"attachvolumes": null,
"memthreshold": 100,
"type": "manager",
"updated": 1388498705611,
"description": ""
}
PUT /resources/clouds/{id} example
Request JSON:
{
"created": 1254582310617,
"currentstatus": "RM10110",
"currentstatus_text": "All hypervisors available",
"defaultcloud": "T",
"description": "new description for test cloud",
Chapter 11. Reference 959
"hypervisors": [
"/resources/hypervisors/16",
"/resources/hypervisors/27",
],
"id": 14,
"name": "new name for test cloud group",
"owner": "/resources/users/1",
"type": null,
"updated": 1254582310617,
"vendor": "OpenStack"
}
Response JSON:
{
"created": 1254582310617,
"currentstatus": "RM10110",
"currentstatus_text": "All hypervisors available",
"defaultcloud": "T",
"description": "new description for test cloud group",
"hypervisors": [
"/resources/hypervisors/16",
"/resources/hypervisors/27",
],
"id": 14,
"name": "new name for test cloud",
"owner": "/resources/users/1",
"type": null,
"updated": 125458273098,
"vendor": "OpenStack"
}
GET /resources/clouds/{id}/images example
[
{
"architecture": "x86",
"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",
960 IBM SmartCloud Orchestrator 2.3: User's Guide
"name": "JWeMaestroTemplate",
"repository": "S1_1",
"version": "vmx-04",
"linked": "true",
"templateId": 17,
"published": "true"
}
Related tasks:
REST API reference on page 940
The representational state transfer (REST) application programming interface (API)
is provided by SmartCloud Orchestrator.
diagnostics.zip file REST API
You can use the representational state transfer (REST) application programming
interface (API) to manage the diagnostics.zip file.
Available HTTP methods
Table 90. REST API for diagnostics.zip
HTTP
methods URI pattern Data format Success codes Error codes
GET /resources/
diagnostics.zip
application/
zip
200 Returns the
diagnostics.zip
file containing
various diagnostic
information from
the product.
403 This code is
returned if the
requester does not
have permission to
obtain diagnostic
information.
500 This code is
returned if the
SmartCloud
Orchestrator
encountered an
internal error while
processing the
request.
A diagnostics.zip file has the following attributes:
query Specifies the content that is added to the diagnostics.zip file. The value of
latest can be included to only include the latest error and trace files in the
.zip file. This significantly reduces the size of the diagnostics.zip file as
the older error and trace files are not included.
Example:
http://example.com/resources/diagnostics.zip?latest
Related tasks:
REST API reference on page 940
The representational state transfer (REST) application programming interface (API)
is provided by SmartCloud Orchestrator.
Chapter 11. Reference 961
Environment profiles REST API
You can use the representational state transfer (REST) application programming
interface (API) to manage environment profiles.
Available HTTP Methods
Table 91. REST API for environment profiles
HTTP
Method URI Pattern Date Format Success Codes Error Codes
GET /resources/
environmentProfiles
application/json
200 Returns the list of
virtual system
instances that are
visible to the client.
403 This code is returned
if the requester does
not have access to
list virtual system
instances.
500 This code is returned
if the SmartCloud
Orchestrator
encountered an
internal error while
processing the
request.
An environment profile 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.
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 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.
962 IBM SmartCloud Orchestrator 2.3: User's Guide
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.
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 virtual system instance. 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 virtual system instance.
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
pattern. The URI is relative and should be resolved against the URI of the
owner.
platform
Specifies OpenStack as the type of hypervisors this environment profile
supports on deployments.
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.
vmname_pattern
Specifies the pattern used to generate virtual machine names.
GET /resources/environmentProfiles example
[
{
"ipsource": 0,
"memory_inuse": 0,
"vcpu_cap": 0,
"maxpriority": 1,
"name": "AdminEnvProfile",
"pcpu_cap": 0.0,
"ownerid": 40,
"storage_cap": 0,
"pcpu_reserved": 0.0,
"vmname_pattern": "",
"environment": 0,
"memory_cap": 0,
"vcpu_reserved": 3,
"mem_cap_units": 0,
"id": 1,
"clouds": [
{
"alias": "RegionKvm_nova",
"region": "RegionKvm",
Chapter 11. Reference 963
"created": 1389621053307,
"name": "RegionKvm_nova",
"updated": 1389621053307,
"id": 23,
"ip_groups": [
{
"autogenerated": "1",
"domainsuffixes": null,
"domain": null,
"gateway": "9.110.51.1",
"hostnameprefix": null,
"primarydns": "9.110.51.41",
"created": 1389186981865,
"netmask": "255.255.255.0",
"alternategateway": null,
"secondarywins": null,
"name": "RegionKvm_public_9.110.51.0/24",
"ismanagement": 0,
"workgroup": null,
"region": "RegionKvm",
"address": "9.110.51.0",
"ipasuuid": null,
"secondarydns": "9.110.51.41",
"computernameprefix": null,
"protocol": "static",
"version": "IPv4",
"primarywins": null,
"id": 22,
"updated": 1389186981865,
"description": null,
"inuse": 1,
"alias": "RegionKvm_public_9.110.51.0/24"
}
]
}
],
"licenses_limits": [
{
"totalallocation": 0,
"reservedallocation": 0,
"currentallocation": 0,
"productid": "5725-D64",
"type": "PVU",
"name": "5725-D64",
"id": 3
},
{
"totalallocation": 0,
"reservedallocation": 0,
"currentallocation": 0,
"productid": "5725-F60",
"type": "PVU",
"name": "5725-F60",
"id": 22
}
],
"memory_reserved": 1536,
"created": 1388093956223,
"currentstatus": "RM01001",
"storage_reserved": 0,
"currentmessage": "RM25008",
"platform": "OpenStack",
"vcpu_inuse": 0,
"updated": 1394567389530,
"pcpu_inuse": 0.0,
964 IBM SmartCloud Orchestrator 2.3: User's Guide
"description": "",
"storage_inuse": 0
}
]
GET /resourcesenvironmentProfiles/{id} example
{
"ipsource": 0,
"memory_inuse": 0,
"vcpu_cap": 0,
"maxpriority": 1,
"name": "AdminEnvProfile",
"pcpu_cap": 0.0,
"ownerid": 40,
"storage_cap": 0,
"pcpu_reserved": 0.0,
"vmname_pattern": "",
"environment": 0,
"memory_cap": 0,
"vcpu_reserved": 3,
"mem_cap_units": 0,
"id": 1,
"clouds": [
{
"alias": "RegionKvm_nova",
"region": "RegionKvm",
"created": 1389621053307,
"name": "RegionKvm_nova",
"updated": 1389621053307,
"id": 23,
"ip_groups": [
{
"autogenerated": "1",
"domainsuffixes": null,
"domain": null,
"gateway": "9.110.51.1",
"hostnameprefix": null,
"primarydns": "9.110.51.41",
"created": 1389186981865,
"netmask": "255.255.255.0",
"alternategateway": null,
"secondarywins": null,
"name": "RegionKvm_public_9.110.51.0/24",
"ismanagement": 0,
"workgroup": null,
"region": "RegionKvm",
"address": "9.110.51.0",
"ipasuuid": null,
"secondarydns": "9.110.51.41",
"computernameprefix": null,
"protocol": "static",
"version": "IPv4",
"primarywins": null,
"id": 22,
"updated": 1389186981865,
"description": null,
"inuse": 1,
"alias": "RegionKvm_public_9.110.51.0/24"
}
]
}
],
"licenses_limits": [
{
"totalallocation": 0,
"reservedallocation": 0,
Chapter 11. Reference 965
"currentallocation": 0,
"productid": "5725-D64",
"type": "PVU",
"name": "5725-D64",
"id": 3
},
{
"totalallocation": 0,
"reservedallocation": 0,
"currentallocation": 0,
"productid": "5725-F60",
"type": "PVU",
"name": "5725-F60",
"id": 22
}
],
"memory_reserved": 1536,
"created": 1388093956223,
"currentstatus": "RM01001",
"storage_reserved": 0,
"currentmessage": "RM25008",
"platform": "OpenStack",
"vcpu_inuse": 0,
"updated": 1394567389530,
"pcpu_inuse": 0.0,
"description": "",
"storage_inuse": 0
}
Related tasks:
REST API reference on page 940
The representational state transfer (REST) application programming interface (API)
is provided by SmartCloud Orchestrator.
Managing environment profiles on page 220
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.
Related reference:
Environment profiles command-line interface reference on page 819
You can work with environment profiles on the SmartCloud Orchestrator
command-line interface.
Hypervisors REST API
You can use the representational state transfer (REST) application programming
interface (API) to manage hypervisors.
966 IBM SmartCloud Orchestrator 2.3: User's Guide
Available HTTP Methods
Table 92. REST API for hypervisors
HTTP
Method URI Pattern Data Format Success Codes Error Codes
GET /resources/hypervisors application/json
200 Returns the list of
hypervisors
defined in
SmartCloud
Orchestrator. See
the example for a
sample of the data
returned.
403 This code is
returned if the
requester has not
been assigned the
admin role.
500 This code is
returned if the
SmartCloud
Orchestrator
encountered an
internal error
while processing
the request.
POST /resources/hypervisors application/json
201 The hypervisor has
been created and is
included in the
response body. The
URL of the new
hypervisor is
included in the
Location header of
the response.
400 This code is
returned if there
are problems
parsing the JSON
data in the
request.
403 This code is
returned if the
requester has not
been assigned the
admin role.
500 This code is
returned if the
SmartCloud
Orchestrator
encountered an
internal error
while processing
the request.
GET /resources/hypervisors/
{id}
application/json
200 Returns
information about
a hypervisor
defined to the
SmartCloud
Orchestrator.
403 This code is
returned if the
requester has not
been assigned the
admin role.
404 This code is
returned if the
requested
hypervisor is not
defined.
500 This code is
returned if the
SmartCloud
Orchestrator
encountered an
internal error
while processing
the request.
Chapter 11. Reference 967
Table 92. REST API for hypervisors (continued)
HTTP
Method URI Pattern Data Format Success Codes Error Codes
PUT /resources/hypervisors/
{id}
application/json
200 The hypervisor
was successfully
updated. The
response body
contains a JSON
representation of
the hypervisor's
current state.
400 This code is
returned if there
are problems
parsing the JSON
data in the
request.
403 This code is
returned if the
requester has not
been assigned the
admin role.
404 This code is
returned if the
request references
a resource that is
not defined.
500 This code is
returned if the
SmartCloud
Orchestrator
encountered an
internal error
while processing
the request.
DELETE /resources/hypervisors/
{id}
204 The hypervisor has
been deleted.
403 This code is
returned if the
requester has not
been assigned the
admin role.
404 This code is
returned if the
requested
hypervisor is not
defined.
500 This code is
returned if the
SmartCloud
Orchestrator
encountered an
internal error
while processing
the request.
A hypervisor has the following attributes:
address
Specifies the host name or IP address (dotted decimal notation) at which
the hypervisor can be reached. This field expects a string value with a
maximum of 1024 characters.
certified
Specifies if the SSL certificate from this hypervisor has been certified.
968 IBM SmartCloud Orchestrator 2.3: User's Guide
SmartCloud Orchestrator does not deploy patterns to a hypervisor until it
has been certified. Note that the SSL certificate from the hypervisor must
be retrieved before the hypervisor can be certified. The following string
values are valid:
T Hypervisor has been certified.
F Hypervisor is not certified.
I Hypervisor is not certified and resources have not been discovered.
cloud Specifies the uniform resource identifier (URI) of the cloud group to which
this hypervisor has been assigned. The URI is relative and should be
resolved against the URI of the hypervisor.
created
Specifies the creation time of the hypervisor, 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 hypervisor.
For example, it could give more details about the problem that caused the
hypervisor to be placed in an error state. 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. This field has a maximum
of 1024 characters.
currentstatus
Specifies a string constant representing the current status of the hypervisor.
This field is an 8 character string value that is automatically generated by
the product.
currentstatus_text
Specifies a 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 hypervisor. Setting this value will cause
SmartCloud Orchestrator to initiate the steps that are needed to get the
hypervisor to this state. This value is an 8 character string and can only be
set to one of the following values:
RM01025
Maintenance mode
RM01006
Started
desiredstatus_text
Specifies a 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.
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:
Chapter 11. Reference 969
v Hypervisor: The resource is a hypervisor.
v Pool: The resource is a pool.
v Cluster: The resource is a cluster.
id Specifies the id of the hypervisor. This attribute can be a string or a
number. When the attribute is a string, there are practical limits on the
string length due to the way the string is generated: ("PM-" + numeric id).
name Specifies the display name associated with this hypervisor. This field
expects a string value with a maximum of 64 characters and must be
unique among all hypervisors defined to SmartCloud Orchestrator.
networks
Specifies the list of URIs of the networks associated with this hypervisor.
The URIs are relative should be resolved against the URI of the hypervisor
that contains them. This list of networks is automatically generated as part
of the discovery process and cannot be changed.
password
Specifies the password used to log on to the hypervisor. This field expects
a string value with a maximum of 128 characters.
storage
Specifies the list of URIs of the storage associated with this hypervisor. The
URIs are relative should be resolved against the URI of the hypervisor that
contains them. This list of storage is automatically generated as part of the
discovery process and cannot be changed.
type Specifies the type of this hypervisor. This value must be set to OpenStack.
This field expects a string value with a maximum of 128 characters.
updated
Specifies the time the hypervisor 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.
userid
Specifies the user ID used to log on to the hypervisor. This field expects a
string value with a maximum of 128 characters.
UUID The universally unique identifier for the hypervisor. For hypervisors that
do not have a UUID, this value will be "none".
GET /resources/hypervisors example
[
{
"address": "https://172.16.15.250/sdk",
"certified": "T",
"cloud": "/resources/clouds/7",
"created": 1254889411919,
"currentmessage": "RM03103",
"currentmessage_text": "Started (move to maintenance mode to make changes)",
"currentstatus": "RM01006",
"currentstatus_text": "Started",
"desiredstatus": "RM01006",
"desiredstatus_text": "Started",
"id": 16,
"name": "virtualwas",
"networks": [
"/resources/networks/38",
"/resources/networks/39"
],
"password": "125488941166924",
970 IBM SmartCloud Orchestrator 2.3: User's Guide
"storage": [
"/resources/storage/56",
"/resources/storage/57"
],
"type": "OpenStack",
endpointtype": {
"value": "Hypervisor",
"label": "Hypervisor"
},
"updated": 1254889464232,
"userid": "root"
},
{
"address": "172.16.0.5",
"certified": "T",
"cloud": "/resources/clouds/17",
"created": 1255049179858,
"currentmessage": "RM03103",
"currentmessage_text": "Started (move to maintenance mode to make changes)",
"currentstatus": "RM01006",
"currentstatus_text": "Started",
"desiredstatus": "RM01006",
"desiredstatus_text": "Started",
"id": "PM-19",
"name": "IBM 8204 E8A 10BC4A1",
"networks": [
"/resources/networks/40",
"/resources/networks/41"
],
"password": "125504917100029",
"storage": [
"/resources/storage/58",
"/resources/storage/59",
"/resources/storage/60"
],
"type": "OpenStack",
endpointtype": {
"value": "Hypervisor",
"label": "Hypervisor"
},
"updated": 1255049245832,
"userid": "root"
}
]
See the description of GET /resources/hypervisors/{id} for attribute details.
POST /resources/hypervisors example
Request JSON:
{
"address": "anotherhypervisor.mycompany.com",
"name": "another hypervisor",
"password": "thepassword",
"type": "OpenStack",
"userid": "root"
}
Response JSON:
{
"address": "https://anotherhypervisor.mycompany.com/sdk",
"certified": "I",
"cloud": null,
"created": 1245249680477,
"currentmessage": "RM03106",
Chapter 11. Reference 971
"currentmessage_text": "Maintenance mode (must add to a cloud group to start)",
"currentstatus": "RM01025",
"currentstatus_text": "Maintenance mode",
"desiredstatus": "RM01025",
"desiredstatus_text": "Maintenance mode",
"id": 5,
"name": "another hypervisor",
"networks": [
],
"password": "124524968047629",
"storage": [
],
"type": "OpenStack",
"updated": 1245249680477,
"userid": "root"
}
GET /resources/hypervisors/{id} example
{
"address": "172.16.0.5",
"certified": "T",
"cloud": "/resources/clouds/17",
"created": 1255049179858,
"currentmessage": "RM03103",
"currentmessage_text": "Started (move to maintenance mode to make changes)",
"currentstatus": "RM01006",
"currentstatus_text": "Started",
"desiredstatus": "RM01006",
"desiredstatus_text": "Started",
"id": "PM-19",
"name": "IBM 8204 E8A 10BC4A1",
"networks": [
"/resources/networks/40",
"/resources/networks/41"
],
"password": "125504917100029",
"storage": [
"/resources/storage/58",
"/resources/storage/59",
"/resources/storage/60"
],
"type": "OpenStack",
"updated": 1255049245832,
"userid": "root"
}
PUT /resources/hypervisors/{id} example
Request JSON:
{
"address": "https://newname.mycompany.com/sdk",
"certified": "T",
"cloud": "/resources/clouds/1",
"created": 1245249680477,
"currentmessage": "RM03106",
"currentmessage_text": "Maintenance mode (must add to a cloud group to start)",
"currentstatus": "RM01025",
"currentstatus_text": "Maintenance mode",
"desiredstatus": "RM01006",
"desiredstatus_text": "Maintenance mode",
"id": 5,
"name": "new name",
"networks": [
],
"password": "new password",
972 IBM SmartCloud Orchestrator 2.3: User's Guide
"storage": [
],
"type": "OpenStack",
"updated": 1245249680477,
"userid": "newuserid"
}
Response JSON:
{
"address": "https://newname.mycompany.com/sdk",
"certified": "T",
"cloud": "/resources/clouds/1",
"created": 1245249680477,
"currentmessage": "RM03106",
"currentmessage_text": "Maintenance mode (must add to a cloud group to start)",
"currentstatus": "RM01025",
"currentstatus_text": "Maintenance mode",
"desiredstatus": "RM01006",
"desiredstatus_text": "Maintenance mode",
"id": 5,
"name": "new name",
"networks": [
],
"password": "124524969310837",
"storage": [
],
"type": "OpenStack",
"updated": 1245249693109,
"userid": "newuserid"
}
Related tasks:
REST API reference on page 940
The representational state transfer (REST) application programming interface (API)
is provided by SmartCloud Orchestrator.
IP addresses REST API
You can use the representational state transfer (REST) application programming
interface (API) to manage IP addresses.
Available HTTP Methods
Table 93. REST API for IP addresses
HTTP
Method URI Pattern Data Format Success Codes Error Codes
GET /resources/ipGroups/{id}/ips application/json
200 Returns the list
of IP addresses
defined for an IP
group. See the
example for a
sample of the
data returned.
403 This code is
returned if the
requester has
not been
assigned the
admin role.
500 This code is
returned if the
SmartCloud
Orchestrator
encountered an
internal error
while processing
the request.
Chapter 11. Reference 973
Table 93. REST API for IP addresses (continued)
HTTP
Method URI Pattern Data Format Success Codes Error Codes
POST /resources/ipGroups/{id}/ips application/json
201 The IP group has
been created and
is included in the
response body.
The URL of the
new IP group is
included in the
Location header
of the response.
400 This code is
returned if there
are problems
parsing the
JSON data in
the request or if
the IP group is
specified
incorrectly.
403 This code is
returned if the
requester has
not been
assigned the
admin role.
500 This code is
returned if the
SmartCloud
Orchestrator
encountered an
internal error
while processing
the request.
GET /resources/ipGroups/{id}/
ips/{id}
application/json
200 Returns
information
about an IP
address defined
to the
SmartCloud
Orchestrator.
403 This code is
returned if the
requester has
not been
assigned the
admin role.
404 This code is
returned if the
requested IP
address is not
defined.
500 This code is
returned if the
SmartCloud
Orchestrator
encountered an
internal error
while processing
the request.
974 IBM SmartCloud Orchestrator 2.3: User's Guide
Table 93. REST API for IP addresses (continued)
HTTP
Method URI Pattern Data Format Success Codes Error Codes
DELETE /resources/ipGroups/{id}/
ips/{id}
204 The IP address
has been deleted.
403 This code is
returned if the
requester has
not been
assigned the
admin role.
404 This code is
returned if the
requested IP
address is not
defined.
500 This code is
returned if the
SmartCloud
Orchestrator
encountered an
internal error
while processing
the request.
An IP address have the following attributes:
created
Specifies the creation time of the IP address, 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 IP address.
This value of this field is an eight character string that is generated by the
product.
currentmessage_text
Specifies the textual representation of currentmessage. This field is a string
representation of currentmessage in the preferred language of the requester
and is automatically generated by the product.
currentstatus
Specifies the current status of the IP address. A string constant representing
the current status of the IP address. This value of this field is an eight
character string that is generated by the product.
currentstatus_text
Specifies the textual representation of currentstatus. This field is a string
representation of currentstatus in the preferred language of the requester
and is automatically generated by the product.
id Specifies the ID of the IP address. This numeric value is automatically
generated by the product.
ipaddress
Specifies the address associated with this IP addresses. The IP address
must be unique and must belong to the IP group under which this IP is
defined. This value is a string in dotted decimal notation ('10.1.2.3', for
example). The maximum length of this field is 16 characters.
Chapter 11. Reference 975
hostname
Specifies the hostname associated with the ip, If no hostname can be
retrieved, the hostname is populated using the ipaddress to ensure the value
is not null.
updated
Specifies the time the IP address 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.
type Specifies the type of IP address, a string constant representing the type of
IP address. The value of this field is an eight character string that is
generated by the product.
subnetid
Specifies the subnet (IP group) ID of the IP address. This numeric value is
generated automatically by the product.
correlationid
Specifies the correlation ID of the IP address. This numeric value is
generated automatically by the product.
GET /resources/ipGroups/{id}/ips example
[
{
"currentstatus_text": "Inactive",
"hostname": "vs217.rch.kstart.ibm.com",
"created": 1338444282294,
"subnetid": 3,
"type": "RM03429",
"updated": 1338444282294,
"currentstatus": "RM01017",
"id": 7,
"ipaddress": "9.5.48.217",
"correlationid": null,
"currentmessage": null,
"currentmessage_txt": null
},
{
"currentstatus_text": "Inactive",
"hostname": "vs227.rch.kstart.ibm.com",
"created": 1338444297540,
"subnetid": 3,
"type": "RM03429",
"updated": 1338444297540,
"currentstatus": "RM01017",
"id": 8,
"ipaddress": "9.5.48.227",
"correlationid": null,
"currentmessage": null,
"currentmessage_txt": null
}
]
See the description of GET /resources/ipGroups/{id}/ips/{id} for attribute details.
POST /resources/ipGroups/{id}/ips example
Request JSON:
{
"addresses": ["10.1.2.3", "10.1.2.4"]
}
976 IBM SmartCloud Orchestrator 2.3: User's Guide
Response JSON:
[
]
GET /resources/ipGroups/{id}/ips/{id} example
{
"currentstatus_text": "Inactive",
"hostname": "vs217.rch.kstart.ibm.com",
"created": 1338444282294,
"subnetid": 3,
"type": "RM03429",
"updated": 1338444282294,
"currentstatus": "RM01017",
"id": 7,
"ipaddress": "9.5.48.217",
"correlationid": null,
"currentmessage": null,
"currentmessage_txt": null
}
Related tasks:
REST API reference on page 940
The representational state transfer (REST) application programming interface (API)
is provided by SmartCloud Orchestrator.
IP groups REST API
You can use the representational state transfer (REST) application programming
interface (API) to manage IP groups.
Available HTTP Methods
Table 94. REST API for IpGroups
HTTP
Method URI Pattern Data Format Success Codes Error Codes
GET /resources/ipGroups application/json
200 Returns the list of
IP groups defined
to SmartCloud
Orchestrator. See
the example for a
sample of the data
returned.
403 This code is
returned if the
requester has not
been assigned the
admin role.
500 This code is
returned if the
SmartCloud
Orchestrator
encountered an
internal error while
processing the
request.
Chapter 11. Reference 977
Table 94. REST API for IpGroups (continued)
HTTP
Method URI Pattern Data Format Success Codes Error Codes
POST /resources/ipGroups application/json
201 The IP group has
been created and is
included in the
response body. The
URL of the new IP
group is included
in the Location
header of the
response.
400 This code is
returned if there
are problems
parsing the JSON
data in the request.
403 This code is
returned if the
requester has not
been assigned the
admin role.
500 This code is
returned if the
SmartCloud
Orchestrator
encountered an
internal error while
processing the
request.
GET /resources/ipGroups/
{id}
application/json
200 Returns
information about
an IP group
defined to the
SmartCloud
Orchestrator.
403 This code is
returned if the
requester has not
been assigned the
admin role.
404 This code is
returned if the
requested IP group
is not defined.
500 This code is
returned if the
SmartCloud
Orchestrator
encountered an
internal error while
processing the
request.
978 IBM SmartCloud Orchestrator 2.3: User's Guide
Table 94. REST API for IpGroups (continued)
HTTP
Method URI Pattern Data Format Success Codes Error Codes
PUT /resources/ipGroups/
{id}
application/json
200 The IP group was
successfully
updated. The
response body
contains a JSON
representation of
the current state of
the IP group.
400 This code is
returned if there
are problems
parsing the JSON
data in the request.
403 This code is
returned if the
requester has not
been assigned the
admin role.
404 This code is
returned if the
requested IP group
is not defined.
500 This code is
returned if the
SmartCloud
Orchestrator
encountered an
internal error while
processing the
request.
DELETE /resources/ipGroups/
{id}
204 The IP group has
been deleted.
403 This code is
returned if the
requester has not
been assigned the
admin role.
404 This code is
returned if the
requested IP group
is not defined.
500 This code is
returned if the
SmartCloud
Orchestrator
encountered an
internal error while
processing the
request.
An IP group has the following attributes:
alternategateway
(Optional) The alternate gateway IP address to use for the IP group
networking.
created
Specifies the creation time of the IP group, represented as the number of
milliseconds since midnight, January 1, 1970 UTC. This value is numeric
and is automatically generated by the product.
Chapter 11. Reference 979
computernameprefix
(Optional) If specified, it defines the prefix to use for the computer name.
description
(Optional) A basic description of the IP Group. This can be used to provide
more details about the usage or purpose of the 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
Specifies the default gateway associated with the IP group, represented as
a string in dotted decimal notation ('192.168.98.1', for example). This field
contains a string value with a maximum of 16 characters.
hostnameprefix
(Optional) If specified, it is used as the hostname's prefix in the generated
virtual machine hostname.
id Specifies the ID of the IP group. This value is numeric and is automatically
generated by the product.
name Specifies the display name associated with this IP group. This value is a
string. This field contains a string value with a maximum of 64 characters.
netmask
Specifies the network mask associated with the subnet address of the IP
group, represented as a string in dotted decimal notation ('255.255.255.0',
for example). This field contains a string value with a maximum of 16
characters.
networks
Specifies the list of URIs of the networks associated with the IP group. The
URIs are relative should be resolved against the URI of the IP group that
contains them.
primarydns
Specifies the primary DNS server used for the IP group, represented as a
string in dotted decimal notation ('192.168.98.2', for example). This field
contains a string value with a maximum of 16 characters.
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 and the deployments done using this IP Group are
set up using DHCP.
secondarydns
Specifies the secondary DNS server used for the IP group, represented as a
string in dotted decimal notation ('192.168.98.3', for example). This field
contains a string value with a maximum of 16 characters.
secondarydns
Specifies the secondary DNS server used for the IP group, represented as a
980 IBM SmartCloud Orchestrator 2.3: User's Guide
string in dotted decimal notation ('192.168.98.3', for example). This field
contains a string value with a maximum of 16 characters.
secondarywins
(Optional) The secondary WINs address to use for the virtual machine.
Only used for Windows based deployments.
updated
Specifies the time the IP group 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 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.
GET /resources/ipGroups example
[
{
"domainsuffixes": null,
"gateway": "9.110.51.1",
"domain": null,
"networks": [
"/resources/networks/24",
"/resources/networks/75",
"/resources/networks/73"
],
"hostnameprefix": null,
"netmask": "255.255.255.0",
"alternategateway": null,
"name": "RegionVmware_public_9.110.51.0/24",
"secondarywins": null,
"workgroup": null,
"version": "IPv4",
"protocol": "static",
"primarywins": null,
"id": 1,
"primarydns": "9.110.51.40",
"created": 1386252697627,
"region": "RegionVmware",
"secondarydns": "9.110.51.40",
"subnetaddress": "9.110.51.0",
"computernameprefix": null,
"updated": 1386252697627,
"description": null
},
{
"domainsuffixes": null,
"gateway": "10.10.0.1",
"domain": null,
"networks": [
"/resources/networks/25",
"/resources/networks/74",
"/resources/networks/76"
],
"hostnameprefix": null,
"netmask": "255.255.255.0",
Chapter 11. Reference 981
"alternategateway": null,
"name": "RegionVmware_public_10.10.0.0/24",
"secondarywins": null,
"workgroup": null,
"version": "IPv4",
"protocol": "static",
"primarywins": null,
"id": 21,
"primarydns": "9.110.51.40",
"created": 1388073228054,
"region": "RegionVmware",
"secondarydns": "9.110.51.40",
"subnetaddress": "10.10.0.0",
"computernameprefix": null,
"updated": 1388073228054,
"description": null
}
]
POST /resources/ipGroups example
Request JSON:
{
"gateway": "10.0.0.1",
"name": "ten", (optional, defaults to subnetaddress)
"netmask": "255.0.0.0",
"primarydns": "10.0.0.2",
"secondarydns": "10.0.0.3", (optional, no default)
"subnetaddress": "10.0.0.0"
}
Response JSON:
{
"created": 1242243975898,
"gateway": "10.0.0.1",
"id": 2,
"name": "ten",
"netmask": "255.0.0.0",
"networks": [],
"primarydns": "10.0.0.2",
"secondarydns": "10.0.0.3",
"subnetaddress": "10.0.0.0",
"updated": 1242738679669
}
GET /resources/ipGroups/{id} example
{
"domainsuffixes": null,
"gateway": "9.110.51.1",
"domain": null,
"networks": [
"/resources/networks/24",
"/resources/networks/75",
"/resources/networks/73"
],
"hostnameprefix": null,
"netmask": "255.255.255.0",
"alternategateway": null,
"name": "RegionVmware_public_9.110.51.0/24",
"secondarywins": null,
"workgroup": null,
"version": "IPv4",
"protocol": "static",
"primarywins": null,
982 IBM SmartCloud Orchestrator 2.3: User's Guide
"id": 1,
"primarydns": "9.110.51.40",
"created": 1386252697627,
"region": "RegionVmware",
"secondarydns": "9.110.51.40",
"subnetaddress": "9.110.51.0",
"computernameprefix": null,
"updated": 1386252697627,
"description": null
}
PUT /resources/ipGroups/{id} example
Request JSON:
{
"gateway": "10.128.1.2",
"name": "new name",
"netmask": "255.128.0.0",
"networks": [ "/resources/networks/3" ]
"primarydns": "10.128.2.3",
"secondarydns": "10.128.3.4",
"subnetaddress": "10.128.0.0"
}
Response JSON:
{
"created": 1242243975898,
"gateway": "10.128.1.2",
"id": 2,
"name": "new name",
"netmask": "255.128.0.0",
"networks": [ "/resources/networks/3" ]
"primarydns": "10.128.2.3",
"secondarydns": "10.128.3.4",
"subnetaddress": "10.128.0.0",
"updated": 1242738679669
}
Related tasks:
REST API reference on page 940
The representational state transfer (REST) application programming interface (API)
is provided by SmartCloud Orchestrator.
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 983
Available HTTP Methods
Table 95. REST API for LogViewerMgr
HTTP
Method URI Pattern Data Format Success Codes Error Codes
POST /resources/logViewerMgr
200 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
SmartCloud
Orchestrator
encountered an
internal error
while processing
the request.
GET /resources/logViewerMgr/
{id}
application/json
200 This code is
returned if
content from the
log file is
included in the
output.
204 This code is
returned if the
specified
startingPoint and
lineCount do not
include any
content from the
log file.
403 This code is
returned if the
requester has not
been assigned the
admin role.
404 This code is
returned if the
specified log
viewing has not
been initialized
correctly.
500 This code is
returned if the
SmartCloud
Orchestrator
encountered an
internal error
while processing
the request.
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
984 IBM SmartCloud Orchestrator 2.3: 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 940
The representational state transfer (REST) application programming interface (API)
is provided by SmartCloud 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 96. List all the logs on a specific virtual machine
Example URL https://localhost/resources/virtualApplications/d-65d29715-
9063-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/
Chapter 11. Reference 985
Web_Application-was.11319468974926.MONITORING/trace.log",
"/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 97. Get the content of a specific log file
Example URL https://localhost/resources/virtualApplications/d-65d29715-
9063-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] WAS/start.py 47377699650752 pid=23164 INFO WAS: 8.0.0.1
[2011-10-24 16:03:53,757] WAS/start.py 47377699650752 pid=23164 INFO Installing WAR file
simple under context root /simple
[2011-10-24 16:05:53,998] WAS/start.py 47377699650752 pid=23164 INFO set WAS role status
to RUNNING
986 IBM SmartCloud Orchestrator 2.3: User's Guide
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 98. Get the overall monitoring status of a given virtual application
Example URL https://localhost/resources/virtualApplications/d-65d29715-
9063-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":"172.16.71.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":"172.16.64.31",
"availability":"NORMAL",
"public_ip":"172.16.71.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"
},
{
Chapter 11. Reference 987
"roleType":"WAS",
"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":"172.16.71.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 99. Get the virtual machine monitoring status for a given virtual application instance
Example URL https://localhost/resources/virtualApplications/d-65d29715-
9063-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":"172.16.71.208",
"server_name":"Web_Application-was.11319468974926",
"public_hostname":"ipas-vm-071-208.purescale.raleigh.ibm.com",
988 IBM SmartCloud Orchestrator 2.3: User's Guide
"state":"RUNNING",
"time_stamp":1319471278884,
"vm_name":"Web_Application-was.11319468974926",
"deployment_id":"d-65d29715-9063-436d-8593-d5218208f8aa",
"hypervisor_hostname":"172.16.64.31",
"availability":"NORMAL",
"public_ip":"172.16.71.208"
}
]
Get the middleware monitoring status for a given virtual
application instance
GET /resources/virtualApplications/{virtual_application_instance_id}/monitoring/roles
Table 100. Get the middleware monitoring status for a given virtual application instance
Example URL https://localhost/resources/virtualApplications/d-65d29715-
9063-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":"172.16.71.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 101. Get virtual machine level monitoring metrics of a specific virtual machine
Example URL https://localhost/resources/virtualApplications/d-65d29715-
9063-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 989
{
"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 102. Get middleware level monitoring metrics of a specific middleware
Example URL https://localhost/resources/virtualApplications/d-65d29715-
9063-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
},
990 IBM SmartCloud Orchestrator 2.3: User's Guide
"WAS_JVMRuntime":{
"time_stamp":1319538432348,
"jvm_heap_used":51.387638,
"used_memory":77583,
"heap_size":150976
}
}
Networks REST API
You can use the representational state transfer (REST) application programming
interface (API) to manage networks.
Available HTTP Methods
Table 103. REST API for Networks
HHTP
Method URI Pattern Data Format Success Codes Error Codes
GET /resources/networks application/json
200 Returns the list of
networks defined
on the
SmartCloud
Orchestrator. See
the example for a
sample of the data
returned.
403 This code is
returned if the
requester has not
been assigned the
admin role.
500 This code is
returned if the
SmartCloud
Orchestrator
encountered an
internal error
while processing
the request.
GET /resources/networks/
{id}
application/json
200 Returns
information about
a network defined
to the SmartCloud
Orchestrator.
403 This code is
returned if the
requester has not
been assigned the
admin role.
404 This code is
returned if the
requested network
is not defined.
500 This code is
returned if the
SmartCloud
Orchestrator
encountered an
internal error
while processing
the request.
Chapter 11. Reference 991
Table 103. REST API for Networks (continued)
HHTP
Method URI Pattern Data Format Success Codes Error Codes
PUT /resources/networks/
{id}
application/json
200 The network was
successfully
updated. The
response body
contains a JSON
representation of
the network's
current state.
400 This code is
returned if there
are problems
parsing the JSON
data in the
request.
403 This code is
returned if the
requester has not
been assigned the
admin role.
404 This code is
returned if the
request references
a resource that is
not defined.
500 This code is
returned if the
SmartCloud
Orchestrator
encountered an
internal error
while processing
the request.
DELETE /resources/networks/
{id}
204 The network has
been deleted.
403 This code is
returned if the
requester has not
been assigned the
admin role.
404 This code is
returned if the
requested network
is not defined.
500 This code is
returned if the
SmartCloud
Orchestrator
encountered an
internal error
while processing
the request.
A network has the following attributes:
created
Specifies the creation time of the network, 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 network.
This field is an 8 character string value that is generated by the product.
992 IBM SmartCloud Orchestrator 2.3: User's Guide
currentmessage_text
Specifies a 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.
hypervisor
Specifies the uniform resource identifier (URI) of the hypervisor to which
this network belongs. The URI is relative and should be resolved against
the URI of the network.
id Specifies the ID of the network. This value is numeric and is automatically
generated by the product.
ipgroup
Specifies the URI of the IP group to which this network has been assigned.
The URI is relative and should be resolved against the URI of the network.
name Specifies the name of the network, as reported by the hypervisor. This field
expects a string value with a maximum of 64 characters.
updated
Specifies the time the network 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.
vlan Specifies the VLAN associated with this network. This value is an integer
between 0 and 4095, inclusive.
GET /resources/networks example
[
{
"created": 1245009567989,
"currentmessage": null,
"currentmessage_text": null,
"hypervisor": "/resources/hypervisors/1",
"id": 1,
"ipgroup": null,
"name": "Public VM Network",
"updated": 1245009567989,
"vlan": null
},
{
"created": 1245009568100,
"currentmessage": null,
"currentmessage_text": null,
"hypervisor": "/resources/hypervisors/1",
"id": 2,
"ipgroup": "/resources/ipGroups/1",
"name": "VM Network",
"updated": 1245009586180,
"vlan": null
}
]
See the description of GET /resources/networks/{id} for attribute details.
GET /resources/networks/{id} example
{
"created": 1245009568100,
"currentmessage": null,
"currentmessage_text": null,
"hypervisor": "/resources/hypervisors/1",
"id": 2,
Chapter 11. Reference 993
"ipgroup": "/resources/ipGroups/1",
"name": "VM Network",
"updated": 1245009586180,
"vlan": null
}
PUT /resources/networks/{id} example
Request JSON:
{
"created": 1245009568100,
"currentmessage": null,
"currentmessage_text": null,
"hypervisor": "/resources/hypervisors/1",
"id": 2,
"ipgroup": "/resources/ipGroups/1",
"name": "new network name",
"updated": 1245009586180,
"vlan": 17
}
Response JSON:
{
"created": 1245009568100,
"currentmessage": null,
"currentmessage_text": null,
"hypervisor": "/resources/hypervisors/1",
"id": 2,
"ipgroup": "/resources/ipGroups/1",
"name": "new network name",
"updated": 1245009597319,
"vlan": 17
}
Related tasks:
REST API reference on page 940
The representational state transfer (REST) application programming interface (API)
is provided by SmartCloud Orchestrator.
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 104. 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
994 IBM SmartCloud Orchestrator 2.3: User's Guide
Response example:
[
{
"license": {
"type": "PVU",
"pid": "5725E00"
},
"status": "avail",
"licenses": [
"https://172.16.33.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://172.16.33.45:9444/storehouse/admin/patterntypes/dbaas/1.0/"
},
...
]
Create a pattern type
POST /resources/patternTypes
Table 105. 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
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 106. 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",
Chapter 11. Reference 995
"licenses": [
"https://172.16.33.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://172.16.33.45:9444/storehouse/admin/patterntypes/dbaas/1.0/"
}
List plugin list of one pattern type
GET /resources/patternTypes/{patternTypeName}/{version}/plugins
Table 107. 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:
[
"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 108. 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:
Request body:
{
"status": "accepted"
}
Valid status includes accepted, avail, unavail
Response body {
"status": "accepted"
}
Response code 200 OK
401 The user is not authorized to
perform this action.
403 Access forbidden
996 IBM SmartCloud Orchestrator 2.3: User's Guide
Table 108. Accept the license agreement of a pattern type (continued)
500 Unexpected error
Delete a pattern type
DELETE /resources/patternTypes/{patternTypeName}/{version_vrmf}
Table 109. 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
Patterns REST API
You can use the representational state transfer (REST) application programming
interface (API) to manage patterns.
Available HTTP Methods
Table 110. REST API for Patterns
HTTP
Method URI Pattern Date Format Success Codes Error Codes
GET /resources/patterns application/json
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.
403 This code is returned
if the requester does
not have access to
list patterns.
500 This code is returned
if the SmartCloud
Orchestrator
encountered an
internal error while
processing the
request.
Chapter 11. Reference 997
Table 110. REST API for Patterns (continued)
HTTP
Method URI Pattern Date Format Success Codes Error Codes
GET /resources/patterns/
{id}
application/json
200 Returns the pattern
associated with the
given ID.
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 SmartCloud
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.
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.
998 IBM SmartCloud Orchestrator 2.3: 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 999
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": [
1000 IBM SmartCloud Orchestrator 2.3: 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 940
The representational state transfer (REST) application programming interface (API)
is provided by SmartCloud Orchestrator.
Chapter 11. Reference 1001
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 111. 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 112. Create a plug-in details
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
1002 IBM SmartCloud Orchestrator 2.3: User's Guide
Table 112. 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://172.16.33.84:9444/storehouse/admin/plugins/firewall/1.0.0.0/",
"enabled": true,
"plugin": "https://172.16.33.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 113. 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 114. 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 1003
{
"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 115. 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://172.16.65.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://172.16.65.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",
1004 IBM SmartCloud Orchestrator 2.3: 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 116. 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 1005
Storage REST API
You can use the representational state transfer (REST) application programming
interface (API) to manage storage.
Available HTTP Methods
Table 117. REST API for Storage
HTTP
Method URI Pattern Data Format Success Code Error Code
GET /resources/storage application/json
200 Returns the list of
storage defined on
the SmartCloud
Orchestrator. See the
example for a
sample of the data
returned.
403 This code is returned
if the requester has
not been assigned
the admin role.
500 This code is returned
if the SmartCloud
Orchestrator
encountered an
internal error while
processing the
request.
GET /resources/storage/
{id}
application/json
200 Returns information
about storage
defined to the
SmartCloud
Orchestrator.
403 This code is returned
if the requester has
not been assigned
the admin role.
404 This code is returned
if the requested
storage is not
defined.
500 This code is returned
if the SmartCloud
Orchestrator
encountered an
internal error while
processing the
request.
1006 IBM SmartCloud Orchestrator 2.3: User's Guide
Table 117. REST API for Storage (continued)
HTTP
Method URI Pattern Data Format Success Code Error Code
PUT /resources/storage/
{id}
application/json
200 The storage was
successfully
updated. The
response body
contains a JSON
representation of the
storage's current
state.
400 This code is returned
if there are problems
parsing the JSON
data in the request.
403 This code is returned
if the requester has
not been assigned
the admin role.
404 This code is returned
if the request
references a resource
that is not defined.
500 This code is returned
if the SmartCloud
Orchestrator
encountered an
internal error while
processing the
request.
DELETE /resources/storage/
{id}
204 The storage has been
deleted.
403 This code is returned
if the requester has
not been assigned
the admin role.
404 This code is returned
if the requested
storage is not
defined.
500 This code is returned
if the SmartCloud
Orchestrator
encountered an
internal error while
processing the
request.
Storage has the following attributes:
created
Specifies the creation time of the storage, represented as the number of
milliseconds since midnight, January 1, 1970 UTC. This value is numeric
and is automatically generated by the product.
hypervisors
Specifies a list of URIs of the hypervisors associated with this storage. The
URIs are relative should be resolved against the URI of the storage that
contains them.
hypervisorstorageid
Specifies the identifier used by hypervisors to identify this storage,
automatically determined. This field contains a unique string value with a
maximum of 1280 characters.
Chapter 11. Reference 1007
id Specifies the ID of the storage. This value is numeric and is automatically
generated by the product.
name Specifies the name of the storage, as reported by the hypervisor. This field
expects a string value with a maximum of 64 characters.
updated
Specifies the time the storage was last updated, represent as a number of
milliseconds since midnight, January 1, 1970 UTC. This value is numeric
and is automatically generated by the product.
GET /resources/storage example
[
{
"created": 1245009567366,
"hypervisors": [
"/resources/hypervisors/1"
],
"hypervisorstorageid": "https://myhypervisor.mycom/sdk#Datastore
#497e24f5-ab7b1019-30a5-001a643670e6",
"id": 1,
"name": "myhypervisor:localstorage1",
"updated": 1245009567366
},
{
"created": 1245009567758,
"hypervisors": [
"/resources/hypervisors/1"
],
"hypervisorstorageid": "https://myhypervisor.mycom/sdk#Datastore
#49824d1c-f0c6ea83-f3e0-001a643670e6"
"id": 2,
"name": "myhypervisor:sanstorage2",
"updated": 1245009567758,
}
]
See the description of GET /resources/storage/{id} for attribute details.
GET /resources/storage/{id} example
{
"created": 1245009567758,
"hypervisors": [
"/resources/hypervisors/1"
],
"hypervisorstorageid": "https://myhypervisor.mycom/
sdk#Datastore#49824d1c-f0c6ea83-f3e0-001a643670e6"
"id": 2,
"name": "myhypervisor:sanstorage2",
"updated": 1245009567758,
}
PUT /resources/storage/{id} example
Request JSON:
{
"created": 1245009567758,
"hypervisors": [
"/resources/hypervisors/1"
],
"hypervisorstorageid": "https://myhypervisor.mycom/
sdk#Datastore#49824d1c-f0c6ea83-f3e0-001a643670e6"
1008 IBM SmartCloud Orchestrator 2.3: User's Guide
"id": 2,
"name": "new name",
"updated": 1245009567758,
}
Response JSON:
{
"created": 1245009567758,
"hypervisors": [
"/resources/hypervisors/1"
],
"hypervisorstorageid": "https://myhypervisor.mycom/
sdk#Datastore#49824d1c-f0c6ea83-f3e0-001a643670e6"
"id": 2,
"name": "new name",
"updated": 1245009593409,
}
Related tasks:
REST API reference on page 940
The representational state transfer (REST) application programming interface (API)
is provided by SmartCloud Orchestrator.
Version REST API
You can use the representational state transfer (REST) application programming
interface (API) to obtain version information about SmartCloud Orchestrator.
Available HTTP Methods
Table 118. REST API for versions
HTTP
Method URI Pattern Data Format Success Codes Error Codes
GET /resources/version application/json
200 Returns information
about the Workload
Deployer component
version installed in
SmartCloud
Orchestrator. See the
example for a
sample of the data
returned.
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 940
The representational state transfer (REST) application programming interface (API)
is provided by SmartCloud Orchestrator.
Chapter 11. Reference 1009
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 SmartCloud Orchestrator but that were taken
over.
Available HTTP Methods
Table 119. REST API for VirtualApplianceInstances
HTTP
Method URI Pattern Data Format Success Codes Error Codes
GET /resources/
virtualApplianceInstances
application/json
200 Returns the list
of virtual
appliance
instances that are
visible to the
client.
403 This code is
returned if the
requester does
not have access
to list virtual
appliance
instances.
500 This code is
returned if
SmartCloud
Orchestrator
encountered an
internal error
while processing
the request.
GET /resources/
virtualApplianceInstances/{id}
application/json
200 Returns the
virtual appliance
instance
associated with
the given ID.
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
SmartCloud
Orchestrator
encountered an
internal error
while processing
the request.
1010 IBM SmartCloud Orchestrator 2.3: User's Guide
Table 119. REST API for VirtualApplianceInstances (continued)
HTTP
Method URI Pattern Data Format Success Codes Error Codes
PUT /resources/
virtualApplianceInstances/{id}
application/json
200 The virtual
appliance
instance was
successfully
updated. The
response body
contains a JSON
representation of
the current state
of the virtual
appliance.
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
SmartCloud
Orchestrator
encountered an
internal error
while processing
the request.
DELETE /resources/
virtualApplianceInstances/{id}
204 The virtual
appliance
instance has been
deleted.
403 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
SmartCloud
Orchestrator
encountered an
internal error
while processing
the request.
A virtual appliance instance has the following attributes:
Chapter 11. Reference 1011
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 SmartCloud 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",
1012 IBM SmartCloud Orchestrator 2.3: User's Guide
"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 940
The representational state transfer (REST) application programming interface (API)
is provided by SmartCloud Orchestrator.
Chapter 11. Reference 1013
Virtual applications REST API
You can use the REST API to manage your virtual applications.
The following tasks can be completed using the REST API.
Retrieve all virtual applications
GET /resources/virtualApplications/
Table 120. Retrieve all virtual application details
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:
[
{
"status": "RUNNING",
"virtual_system": {
"id": 3
},
"deployment": "https://10.102.155.72:9444/storehouse/user/deployments/
d-09c5ac70-27a3-4c3b-96df-d14a3b23b86c/deployment.json",
"deployment_name": " Sample JEE web application ",
"appmodel": "https://10.102.155.72:9444/storehouse/user/deployments/
d-09c5ac70-27a3-4c3b-96df-d14a3b23b86c/appmodel.json",
"app_type": "application",
"app_id": "a-3761fe57-2bda-4f9b-b90c-d2c435d69cb7",
"start_time": "2011-03-25T17:02:57.878Z",
"id": "d-09c5ac70-27a3-4c3b-96df-d14a3b23b86c",
"creator": "u-0",
"topology": "https://10.102.155.72:9444/storehouse/user/deployments/
d-09c5ac70-27a3-4c3b-96df-d14a3b23b86c/topology.json",
"role_error": false
},
...
]
Retrieve the virtual applications with filter
GET /resources/virtualApplications/{depl_id}
v Filter "app_type": Filter application patterns with application type.
v filterString can be application, or service (for shared service). If filterString is
null or empty, all virtual applications will be returned.
v Filter patterntype and version: Filter virtual application with versioned
pattern type, for example, ?patterntype=webapp&version=1.0
v
Table 121. Retrieve the virtual applications with filter
Example URL https://localhost/resources/virtualApplications/
?patterntype=webapp&version=1. 0&app_type=application
Response content-type application/json
Response code 200 OK
1014 IBM SmartCloud Orchestrator 2.3: User's Guide
Table 121. Retrieve the virtual applications with filter (continued)
401 The user is not authorized to
perform this action.
403 Access forbidden
500 Unexpected error
Response example:
[
{
"status": "RUNNING",
"virtual_system": {
"id": 3
},
"deployment": "https://172.16.33.84:9444/storehouse/user/deployments/
d-ecaa2e15-f556-43e8-8e09-8905aebab441/deployment.json",
"deployment_name": "Sample JEE web application",
"appmodel": "https://172.16.33.84:9444/storehouse/user/deployments/
d-ecaa2e15-f556-43e8-8e09-8905aebab441/appmodel.json",
"app_type": "application",
"app_id": "a-9d64b797-3d4a-4332-96d4-858ba709a499",
"start_time": "2011-05-14T12:42:20.950Z",
"id": "d-ecaa2e15-f556-43e8-8e09-8905aebab441",
"creator": "u-0",
"topology": "https://172.16.33.84:9444/storehouse/user/deployments/
d-ecaa2e15-f556-43e8-8e09-8905aebab441/topology.json",
"role_error": false
}
]
Deploy a virtual application
POST /resources/applicationPatterns/{app_id}/virtualApplications/
Table 122. Deploy a virtual application details
Request content-type application/json
Response content-type application/json
Response header location https://localhost/resources/applicationPatterns/a-de901667-
3b5f-44af-b27f-efd8971ee552/virtualApplications/d-7956c64e-
0fac-49f2-b04e-efbc131a4cc4
Response code 201 Created
401 The user is not authorized to
perform this action.
404 The application specified by
{appID} is not found
412 Precondition failed (unable to
deploy, such as template)
500 Unexpected error
Request body:
{
"deployment_name": "My Virtual Application",
"cloud_group": "1",
"ssh_keys":["ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCevpm4/EYFrjQ9NkC535Whr3Yswv2x
JkxGz44/2g5uC6385hWvEycSAyoUQ3pt6/n4BxMHxilLVrT3y9FhyGBfIkJsySvzsiMV
e0shh7JWct03uCiiQ5emoe2eaVOiYz2P5vBe9V8amTC1Is+Uv/SXFF7UuKlV7gP8hBuB
Chapter 11. Reference 1015
NGwnN2/hI6dKtZKH2GDcJbPz9J9dFl2XQYoX7XnaJ3eea+UZfIvS21Gi7SF3Ff+/UdPu
OumHGhw1S1POGbApFStjOWXU92p6Mz4wON+mRtWzYXGEdlXDAQisX8yBlZdVZ6+g4HB2
cv5TWvYchiAYqG6M1B5tZIr/ZYzEZVTjd4ZCQMwR auto generated key"]
}
The deployment_name is an optional parameter for virtual application name. By
default, it will be the name of application. The cloud_group is a required
parameter for deployment. The ssh_keys is an optional parameter for
deployment.
Response example:
{
"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": "10.102.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://10.102.165.49:50000/mydb:user=appdba;
password=FgxmZv47TM8GwJD62Y1;",
"id": "database-db2.11301072577884.DB2"
}
],
"public_ip": "10.102.165.49"
}
],
"role_error": false
}
Retrieve virtual application instance status
GET /resources/virtualApplications/{depl_id}
Table 123. Retrieve virtual application instance status
Example URL https://localhost/resources/virtualApplications/d-7956c64e-
0fac-49f2-b04e-efbc131a4cc4
Response content-type application/json
Response code 200 OK
401 The user is not authorized to
perform this action.
1016 IBM SmartCloud Orchestrator 2.3: User's Guide
Table 123. Retrieve virtual application instance status (continued)
404 The application specified by
{appID} is not found
500 Unexpected error
Response example:
{
"status": "RUNNING",
"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": "10.102.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://10.102.165.49:50000/mydb:user=appdba;
password=FgxmZv47TM8GwJD62Y1;",
"id": "database-db2.11301072577884.DB2"
}
],
"public_ip": "10.102.165.49"
}
],
"role_error": false
}
Update virtual application status
PUT /resources/virtualApplications/{depl_ID}/
In request body, the values of the operation are stop and terminate.
Table 124. Updated virtual application status details
Example URL https://localhost/resources/virtualApplications/d-7956c64e-
0fac-49f2-b04e-efbc131a4cc4
Response content-type application/json
Request body {
"operation": "kill"
}
Response code 202 Accepted
401 The user is not authorized to
perform this action.
Chapter 11. Reference 1017
Table 124. Updated virtual application status details (continued)
403 Access forbidden
404 The application specified by
{appID} is not found
409 Conflict
412 Precondition failed (invalid
operation)
500 Unexpected error
Delete a virtual application
DELETE /resources/virtualApplications/{depl_ID}
Table 125. Delete a virtual application details
Example URL https://localhost/resources/virtualApplications/d-7956c64e-
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
Update application access right for the specified user name or
group name
PUT /resources/virtualApplications/{appID}/accessRights/{name}?{ user or group }
Table 126. Update application access right for the specified user name or group name
Example URL https://localhost/resources/virtualApplications/
d-7956c64e-0fac-49f2-b04e-efbc131a4cc4/accessRights/
Everyone?group
Response content-type application/json
Request body example { "access_rights": "F"}
Response code 200 OK
401 The user is not authorized to
perform this action.
403 Access forbidden
404 The application specified by
{appID} is not found.
412 Invalid parameter supplied,
for example, the json file is
invalid.
1018 IBM SmartCloud Orchestrator 2.3: User's Guide
Table 126. Update application access right for the specified user name or group
name (continued)
500 Unexpected error
Virtual images REST API
You can use the representational state transfer (REST) application programming
interface (API) to manage virtual images.
Available HTTP Methods
Table 127. REST API for VirtualMachines
HTTP
Method URI Pattern Data Format Success Codes Error Codes
GET /resources/virtualImages application/json
200 Returns the list
of virtual images
that are visible to
the client.
403 This code is
returned if the
requester does
not have access
to list virtual
images.
500 This code is
returned if the
SmartCloud
Orchestrator
encountered an
internal error
while processing
the request.
GET /resources/virtualImages/{id} application/json
200 Returns the
virtual image
associated with
the given ID.
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
SmartCloud
Orchestrator
encountered an
internal error
while processing
the request.
Chapter 11. Reference 1019
Table 127. REST API for VirtualMachines (continued)
HTTP
Method URI Pattern Data Format Success Codes Error Codes
GET /resources/clouds/
{cloud_id}/images
application/json
200 Returns the list
of images of the
selected cloud
group. See the
example for a
sample of the
data returned.
500 This code is
returned if
SmartCloud
Orchestrator
encountered an
internal error
while processing
the request.
GET
/resources/clouds/
{cloud_id}/images/
{image_id}
/resources/clouds/
{cloud_id}/images/
{image_id}.ovf
application/json
200 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.
500 This code is
returned if
SmartCloud
Orchestrator
encountered an
internal error
while processing
the request.
GET /resources/templates application/json
200 Returns the list
of virtual images
that are visible to
the client.
403 This code is
returned if the
requester does
not have access
to list virtual
images.
500 This code is
returned if the
SmartCloud
Orchestrator
encountered an
internal error
while processing
the request.
POST /resources/templates application/json
201 The resources
has been created
successfully.
500 This code is
returned if
SmartCloud
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
1020 IBM SmartCloud Orchestrator 2.3: User's Guide
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.
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
Chapter 11. Reference 1021
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.
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": "",
1022 IBM SmartCloud Orchestrator 2.3: User's Guide
"owner": "/resources/users/1",
"updated": 1339575604458,
"description": "A virtual machine"
},
GET /resources/clouds/{id}/images example
[
{
"architecture": "x86",
"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,
Chapter 11. Reference 1023
"vcpu": 2,
"diskDetails": [
{
"size": "1572864000",
"hardwareid": 1,
"label": "vmdisk1",
"filename": "SLES11_32_Small.vmdk",
"created": 1339571317752,
"updated": 1339571317752,
"id": 1
}
],
"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
The request JSON contains the cloud group ID and an array of images that have to
be registered to that cloud group.
{
"cloudId":"1",
"cloudImages":[
{"id":"2496c17c-c303-4dd1-9008-0d16f8161b9c"},
{"id":"fab6d6be-dc4f-4dbe-bd41-4c9abc42b13e"},
{"id":"0adaaaba-ce86-48bf-8d62-c28a0cb0ebb1"}
]
}
Response JSON:
[
{
"name": "SLES11_32_Small_SCP_init-xvm141",
"description": "Suse Linux Enterprise 11 (32-bit)",
"linked": true,
"linked_entityid": "2496c17c-c303-4dd1-9008-0d16f8161b9c",
"cloudid": "1",
"linked_cloudid": "1",
"published": true,
"desiredstatus": "RM01027",
"id": 2,
"currentstatus": "RM01036",
1024 IBM SmartCloud Orchestrator 2.3: User's Guide
"currentmessage": null,
"editionstatus": "RM01036",
"currenteditionid": 2,
"code": 200,
"ownerid": 1
},
...
]
Related tasks:
REST API reference on page 940
The representational state transfer (REST) application programming interface (API)
is provided by SmartCloud Orchestrator.
Chapter 5, Managing virtual images, on page 287
Virtual images provide the operating system and product binary files that are
required to create a virtual system instance.
Related reference:
Virtual images command-line interface reference on page 893
You can manage virtual images in the catalog using the SmartCloud Orchestrator
command-line interface. Virtual images provide the operating system and product
binary files to create a virtual system instance.
Virtual machines REST API
You can use the representational state transfer (REST) application programming
interface (API) to manage virtual machines.
Available HTTP methods
Table 128. REST API for virtual machines
HTTP
Method URI Pattern Data Format Success Codes Error Codes
GET /resources/virtualSystems/
{id}/virtualMachines
application/json
200 Returns the list of
virtual system
instances that are
visible to the
client.
403 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
SmartCloud
Orchestrator
encountered an
internal error
while processing
the request.
Chapter 11. Reference 1025
Table 128. REST API for virtual machines (continued)
HTTP
Method URI Pattern Data Format Success Codes Error Codes
GET /resources/virtualSystems/
{id}/virtualMachines/{id}
application/json
200 Returns the
virtual machine
associated with
the given ID.
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
SmartCloud
Orchestrator
encountered an
internal error
while processing
the request.
POST /resources/virtualSystems/
{id}/virtualMachines
application/json
201 The virtual
machine(s) have
been defined in
SmartCloud
Orchestrator. The
virtual machines
are started when
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
this request. The
URI of the first
virtual machine is
also included in
the HTTP
Location header
of the response.
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 access to
list virtual
machines on the
virtual system
instance.
500 This code is
returned if
SmartCloud
Orchestrator
encountered an
internal error
while processing
the request.
1026 IBM SmartCloud Orchestrator 2.3: User's Guide
Table 128. REST API for virtual machines (continued)
HTTP
Method URI Pattern Data Format Success Codes Error Codes
PUT /resources/
adoptUnmanagedVM
application/json
200 The virtual
system instance
was successfully
updated. The
response body is
empty.
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
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
SmartCloud
Orchestrator
encountered an
internal error
while processing
the request.
A virtual system instance has the following attributes:
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.
Chapter 11. Reference 1027
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.
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",
1028 IBM SmartCloud Orchestrator 2.3: User's Guide
"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.
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
}
Chapter 11. Reference 1029
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 940
The representational state transfer (REST) application programming interface (API)
is provided by SmartCloud Orchestrator.
Virtual system instances REST API
You can use the representational state transfer (REST) application programming
interface (API) to manage virtual system instances.
Available HTTP Methods
Table 129. REST API for VirtualSystems
HTTP
Method URI Pattern Data Format Success Codes Error Codes
GET /resources/virtualSystems application/json
200 Returns the list
of virtual system
instances that
are visible to the
client.
403 This code is
returned if the
requester does
not have access
to list virtual
system
instances.
500 This code is
returned if
SmartCloud
Orchestrator
encountered an
internal error
while processing
the request.
1030 IBM SmartCloud Orchestrator 2.3: User's Guide
Table 129. REST API for VirtualSystems (continued)
HTTP
Method URI Pattern Data Format Success Codes Error Codes
POST /resources/virtualSystems application/json
201 The virtual
system instance
has been created
and is included
in the response
body. The URI
of the new
virtual system
instance is
included in the
Location header
of the response.
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
create virtual
system
instances.
500 This code is
returned if the
SmartCloud
Orchestrator
encountered an
internal error
while processing
the request.
GET /resources/virtualSystems/
{id}
application/json
200 Returns the
virtual system
instance
associated with
the given ID.
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
SmartCloud
Orchestrator
encountered an
internal error
while processing
the request.
Chapter 11. Reference 1031
Table 129. REST API for VirtualSystems (continued)
HTTP
Method URI Pattern Data Format Success Codes Error Codes
PUT /resources/virtualSystems/
{id}
application/json
200 The virtual
system instance
was successfully
updated. The
response body
contains a JSON
representation of
the current state
of the virtual
system.
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 system
instance.
404 This code is
returned if the
request
references a
resource that is
not defined.
500 This code is
returned if the
SmartCloud
Orchestrator
encountered an
internal error
while processing
the request.
DELETE /resources/virtualSystems/
{id}
204 The virtual
system instance
has been
deleted.
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
SmartCloud
Orchestrator
encountered an
internal error
while processing
the request.
The following attributes are required to create a virtual system:
1032 IBM SmartCloud Orchestrator 2.3: User's Guide
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 SmartCloud 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"
}
{
"ipGroup": "/resources/ipGroups/1",
Chapter 11. Reference 1033
"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 Specifies a string that uniquely identifies the parameter. The script
key is a string with a maximum length of 4098 characters.
1034 IBM SmartCloud Orchestrator 2.3: 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:
Request JSON:
{
"environmentProfiles": "/resources/environmentProfiles/1",
"endtime": 1260000000000,
"name": "sample virtual system instance",
"parts": [
{
"description": "Deployment manager",
"label": "Deployment manager",
"id": 1,
"cloud": "/resources/clouds/1",
"flavor": "m1.tiny",
"ipGroup": "/resources/ipGroups/1",
"ipaddresses":[{"hostname":"myhostname.mycompany.com",
"ipaddress":"192.168.0.100"}],
"properties": [
Chapter 11. Reference 1035
{
"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": "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"
}
],
1036 IBM SmartCloud Orchestrator 2.3: User's Guide
"scripts": [
{
"description": "Test script",
"id": 1,
"label": "test script",
"parameters": [
{
"key": "key1",
"value": "value1"
},
{
"key": "key2",
"value": "my value2"
}
]
}
]
},
{
"description": "Custom nodes",
"id": 3,
"label": "Custom nodes",
"cloud": "/resources/clouds/1",
"flavor": "m1.tiny",
"ipGroup": "/resources/ipGroup/1",
"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",
Chapter 11. Reference 1037
"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": [
]
}
],
"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
1038 IBM SmartCloud Orchestrator 2.3: User's Guide
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.
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 SmartCloud 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",
Chapter 11. Reference 1039
"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",
"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 940
The representational state transfer (REST) application programming interface (API)
is provided by SmartCloud Orchestrator.
OpenStack and IaaS REST API
You can use OpenStack and IaaS APIs to interact with these components.
When you use a IaaS API call, use as your main entry point http://central-
server-2:9973/providers, where central-server-2 is the virtual machine where
the IaaS gateway, Virtual Image Library and the public cloud gateway are located.
For the list of OpenStack and IaaS APIs that are supported by SmartCloud
Orchestrator, see http://api.openstack.org/api-ref.html.
1040 IBM SmartCloud Orchestrator 2.3: User's Guide
Using REST APIs to manage users, projects, roles, and domains
You can use OpenStack and IaaS APIs to manage users, projects, roles, and
domains.
OpenStack API
To query and manage users, projects, roles, and domains, you can use the Identity
Service API v3. This API is also known as the keystone API v3. You can get this API
from the OpenStack website at http://api.openstack.org/api-ref.html.
For more information about working with REST APIs, see the OpenStack API Quick
Start http://docs.openstack.org/api/quick-start/content/.
Requirements
When you use the Identity Service API to create a user, you must always assign a
primary project to the created user. That is, you must set the user's
default_project_id attribute to the ID of the primary project.
When you create a SmartCloud Orchestrator user, you must do the following
additional tasks:
v Add an attribute called tenantId to the request JSON, and set this attribute to
the ID of the primary project.
v Assign a role within the primary project to the user.
Note: These tasks are specific to SmartCloud Orchestrator, and are not described in
the OpenStack API documentation.
Example
In this example, you create a user, and assign the user to a primary project with a
specified role.
You make a scoped authentication request, and provide user, password, project,
and domain information. The entry point is the IaaSGateway URL to make the API
calls against, as shown in the following example:
http://<host_name>:9973/providers
1. Use the following API call to display the service catalog:
GET http://<host_name>:9973/providers
Sample output:
<serviceCatalog>
<service type="identity" name="keystone">
<endpoint interface="admin"
url="http://<host_name>:9973/eda84279864d4811a619ce3ce6542d68/v3" region="RegionOne"
id="eda84279864d4811a619ce3ce6542d68"/>
<endpoint interface="internal"
url="http://<host_name>:9973/8cf0faf13c3441bf85e7e21917256679/v3" region="RegionOne"
id="8cf0faf13c3441bf85e7e21917256679"/>
<endpoint interface="public" url="http://<host_name>:9973/721f941b32794896970f4b009fff2789/v3"
region="RegionOne" id="721f941b32794896970f4b009fff2789"/>
</service>
</serviceCatalog>
From the endpoint interface="admin" entry in the service catalog, you can find
the identity URL to use for subsequent REST calls:
<endpoint interface="admin"
url="http://<host_name>:9973/eda84279864d4811a619ce3ce6542d68/v3" .../>
Chapter 11. Reference 1041
2. Authenticate against the Identity Service API by using the URL retrieved from
the previous call:
POST http://<host_name>:9973/eda84279864d4811a619ce3ce6542d68/v3/auth/tokens
Remember to set the following request header:
Content-Type : application/json
Request JSON:
{
"auth": {
"identity": {
"methods": [
"password"
],
"password": {
"user": {
"name": "--user-name--",
"password": "********",
"domain": {
"name": "--domain-name--"
}
}
}
},
"scope": {
"project": {
"domain": {
"name": "--domain-name--"
},
"name": "--project-name--"
}
}
}
}
The response header of this call contains an auth token to be used for all
subsequent calls, for example, X-Subject-Token:
9f41f6d777fe4a8c808d2bef6513cce4. Make sure to set this auth token in the
header for each call, along with the Content-Type header:
Content-Type : application/json
X-Auth-Token: 9f41f6d777fe4a8c808d2bef6513cce4
3. Create the project:
POST v3/projects
Request body:
{
"project": {
"description": "Development project",
"domain_id": "--domain-id--",
"enabled": "1",
"name": "Development"
}
}
The response JSON of this call contains the ID of the new project:
"id": "--project-id--",
4. Create the user:
POST v3/users
Request body:
{
"user": {
"default_project_id": "--project-id--",
"tenantId": "--project-id--",
"description": "some description",
1042 IBM SmartCloud Orchestrator 2.3: User's Guide
"domain_id": "--optional--",
"email": "[email protected]",
"enabled": "1",
"name": "exampleUser",
"password": "********"
}
}
The response JSON of this call contains the ID of the new user:
"id": "--user-id--",
5. Create the role assignment of the user in the primary project:
PUT v3/projects/<project_id>/users/<user_id>/roles/<role_id>
No response body is returned for this call.
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 130. 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.
Chapter 11. Reference 1043
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
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 131. 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:
}
1044 IBM SmartCloud Orchestrator 2.3: User's Guide
Table 131. Retrieve an orchestration action entry REST API call (continued)
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 132. Add or update an entry in the orchestration actions REST API call
HTTP method PUT
URL pattern https://hostname/resources/automation/{id}
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)
Chapter 11. Reference 1045
Delete an orchestration action entry
Use this REST call to delete a selected entry from the orchestration actions.
Available HTTP method
Table 133. 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
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 134. 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
1046 IBM SmartCloud Orchestrator 2.3: User's Guide
operation_type
event
human_service
implementation_type
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 135. 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 following listing shows an example response that can be retrieved via the
request
GET /kernel/bpm/runbook/25.916d4552-9cf4-40c3-89fe-7f7bc43b2435
:
[
{
"id": "25.916d4552-9cf4-40c3-89fe-7f7bc43b2435",
"displayName": "Create Business Object Test"
Chapter 11. Reference 1047
"processAppId": "2066.5d35fbc5-6949-4971-8e06-83ca4c3cc760",
},
{
"id": "25.2951bb80-e9b2-457a-9097-4443886d1dd5",
"displayName":"SCO_Process"
"processAppId": "2066.5d35fbc5-6949-4971-8e06-83ca4c3cc760",
}
]
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 136. 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
SmartCloud 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
SmartCloud Orchestrator.
Available HTTP method
Table 137. Get list of all human services
HTTP method GET
URL pattern https://hostname/kernel/bpm/humanService
1048 IBM SmartCloud Orchestrator 2.3: User's Guide
Table 137. Get list of all human services (continued)
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
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 138. 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
Chapter 11. Reference 1049
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" }
.
Retrieve My Inbox
Use these APIs to retrieve information about the contents of My Inbox.
For detailed information about Business Process Manager task REST API, see the
Business Process Manager information center.
List all My Inbox items:
Use this REST API to retrieve a list of all the items contained in My Inbox.
Available HTTP method
Table 139. Get list of all My Inbox items
HTTP method GET
URL pattern https://hostname/kernel/bpm/task
Response A list of My Inbox items is returned. If My 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.
1050 IBM SmartCloud Orchestrator 2.3: User's Guide
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 My 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.
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 task.
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"
}
]
.
Chapter 11. Reference 1051
Get entries for a specific My Inbox item:
Use this REST call to retrieve information about a My Inbox item with an indicated
ID
Available HTTP method
Table 140. Get information about a specific My Inbox item
HTTP method GET
URL pattern https://hostname/kernel/bpm/task/<task id>
Response The following parameters of a My 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 My 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:
1052 IBM SmartCloud Orchestrator 2.3: User's Guide
approval - for an approval task
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.
v operationContextId - the ID of the operation context or My 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.
Chapter 11. Reference 1053
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 141. 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}
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.
1054 IBM SmartCloud Orchestrator 2.3: User's Guide
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.
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.
Chapter 11. Reference 1055
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.
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": {
1056 IBM SmartCloud Orchestrator 2.3: User's Guide
"Hello": "World"
},
"status": "RM01005",
"type": "TOPOLOGY",
"virtualApplicationId": "",
"virtualApplicationPatternId": "",
"virtualSystemId": "\/resources\/virtualSystems\/1",
"virtualSystemPatternId": "\/resources\/patterns\/1"
},
"roles": [
],
"services": [
],
"virtualMachines": [
{
"cloudGroup": "\/resources\/clouds\/1",
"disk": 10240,
"hostname": "172-0-0-13.lightspeed.brhmal.sbcglobal.net",
"hypervisorid": "\/resources\/hypervisors\/PM-1",
"id": "1",
"memory": 2048,
"name": "965a92be-OS Node-Test-1",
"networkInterfaces": [
{
"hostname": "172-0-0-13.lightspeed.brhmal.sbcglobal.net",
"ip": "172.0.0.13",
"ipgroup": "\/resources\/ipgroups\/2"
}
],
"partname": "OS Node",
"runtimeId": "1b9417ca-6f66-42ec-a2da-661739d8e66d",
"virtualCpu": 1
}
]
}
Metadata parameters REST APIs
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 142. 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:
Chapter 11. Reference 1057
{"Hello":"World"}
Post metadata parameters
Use this REST API call to post metadata parameters of a specific service instance.
Available HTTP method
Table 143. 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 144. 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.
1058 IBM SmartCloud Orchestrator 2.3: 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 145. 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 146. 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 1059
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 147. 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.
Task engine REST API
You can use this set of REST API calls to interact with role parameters of a specific
server instance.
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 148. 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:
v tasks - a comma-separated list of task objects.
1060 IBM SmartCloud Orchestrator 2.3: User's Guide
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 149. 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 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.
v internal status - one of the following: NEW, QUEUED, RUNNING,
SUSPENDED, FAILING, FAILED, COMPLETING, COMPLETED, CANCELING,
CANCELED.
Chapter 11. Reference 1061
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" ]
}
}
Deployment parameters REST API
You can use this set of REST API calls to interact with deployment parameters of a
specific instance.
1062 IBM SmartCloud Orchestrator 2.3: User's Guide
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 150. 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).
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.
Chapter 11. Reference 1063
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 151. 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.
Note: The combination of parameterclass, partkey and parametername is unique
within a virtual system instance.
Self-service offering REST API
You can use this set of REST API calls to interact with the self-service offerings in
SmartCloud Orchestrator.
List all self-service offerings
Use this REST API method to list all self-service offerings.
Available HTTP method
Table 152. Get list of all self-service offerings
HTTP method GET
URL pattern https://hostname/resources/services
1064 IBM SmartCloud Orchestrator 2.3: User's Guide
Table 152. Get list of all self-service offerings (continued)
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 a 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.
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",
Chapter 11. Reference 1065
"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 153. 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.
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.
1066 IBM SmartCloud Orchestrator 2.3: User's Guide
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 a 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",
"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
Chapter 11. Reference 1067
}
"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 154. 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 155. Update a self-service offering REST API call
HTTP method PUT
URL pattern https://hostname/resources/services/{id}
Response The self-service offering is updated.
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" }
1068 IBM SmartCloud Orchestrator 2.3: User's Guide
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 SmartCloud 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", ...}
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):
Chapter 11. Reference 1069
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 SmartCloud 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 uuid
For details, refer to Get entries for a specific self-service offering on page 1066.
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" }
For details, refer to http://pic.dhe.ibm.com/infocenter/dmndhelp/v8r5m0/
index.jsp?topic=%2Fcom.ibm.wbpm.ref.doc%2Frest%2Fbpmrest
%2Frest_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://pic.dhe.ibm.com/infocenter/dmndhelp/v8r5m0/
index.jsp?topic=%2Fcom.ibm.wbpm.ref.doc%2Frest%2Fbpmrest
%2Frest_bpm_wle_v1_processmodel_bpdid_get.htm
1070 IBM SmartCloud Orchestrator 2.3: User's Guide
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 SmartCloud 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 My Requests 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.
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://172.17.53.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\">
Chapter 11. Reference 1071
<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 SmartCloud 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://172.17.53.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 1061-
Sample 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",
"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
1072 IBM SmartCloud Orchestrator 2.3: User's Guide
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:
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.
Chapter 11. Reference 1073
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://172.17.41.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://172.17.41.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://172.17.41.98/resources/automation/3
-X POST
(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",
1074 IBM SmartCloud Orchestrator 2.3: User's Guide
"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://172.17.41.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",
"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
Chapter 11. Reference 1075
&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://172.17.41.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://172.17.41.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}}
1076 IBM SmartCloud Orchestrator 2.3: 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 SmartCloud Orchestrator components, see the following table
to find where the log files are stored.
Table 156. Log files
Component Log file default path Node
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
SmartCloud UI /var/log/scoui.log
/var/log/scoui.trc
Central Server 3
OpenStack /var/log/nova/*
/var/log/glance/*
/var/log/cinder/*
Region Server
/var/log/keystone/* Central Server 2
IaaS Gateway /var/log/iaasgateway/
iaasgateway.log
Central Server 2
SmartCloud Entry /root/.SCE31/logs Region Server
Public Cloud Gateway /var/log/pcg.log Central Server 2
Virtual Image Library Server /opt/IBM/WebSphere/
AppServer/profiles/
imageLibraryProfile/logs/
imageLibraryServer/*
Central Server 2
Copyright IBM Corp. 2013, 2014 1077
Table 156. Log files (continued)
Component Log file default path Node
Virtual Image Library Proxy /opt/origami/vilProxy*.log
/opt/p2pdiff/
TransferClient/agent.out
(on the Region Server)
/opt/p2pdiff/
TransferClient/
globaltracker.out (on
Central Server 2)
Region Server and Central
Server 2
Origami /var/log/origami/
origami.log
Region Server and Central
Server 2
Redis /var/log/origami/redis/
redis.log
Central Server 2
Image Construction and
Composition Tool
/drouter/.../trace/
trace.log
The machine where the
Image Construction and
Composition Tool is installed.
Image Construction and
Composition Tool
installation
/var/ibm/
InstallationManager/logs*
The machine where the
Image Construction and
Composition Tool is installed.
Business Process Manager /opt/ibm/BPM/v8.5/profiles/
Node1Profile/logs
Central Server 4
Business Process Manager
installation
/var/ibm/
installationManager/logs
Central Server 4
Activation Engine For Linux:
v /opt/ibm/ae/log/*
v /opt/ibm/ae/AR/*
For Windows:
v c:\windows\setup\ibm\log
v c:\windows\setup\ibm\ar
The deployed virtual
machine
Problem determination with pdcollect tool
The script pdcollect.py is a log collection and log archive utility, which collects
logs from all components in SmartCloud Orchestrator.
The pdcollect.py script is located in /iaas/pdcollect on the 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 archive 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 an archive 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
1078 IBM SmartCloud Orchestrator 2.3: User's Guide
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.
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.
Running the pdcollect tool
Run the pdcollect.py script on the Central Server 1 to collect logs from all
components in SmartCloud Orchestrator.
Before you begin
The pdcollect.py script is located in /iaas/pdcollect on the Central Server 1.
The script requires the exchange of ssh keys to remote machines before execution.
Procedure
On Central Server 1, 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, --hostnames=SYSTEMLIST
Lists the host names to be scanned for the log files. The SYSTEMLIST format
is hostname1,hostname2,hostname3,....
Chapter 12. Troubleshooting 1079
-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
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 SmartCloud
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 SmartCloud Orchestrator Server:
[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 SmartCloud
Orchestrator servers without interruption:
su - <yourmechid> -c "ssh <yourmechid>@$SCO_server_ip"
2. Copy the /iaas/pdcollect and change the directory permission:
a. On Central Server 1, copy the directory /iaas/pdcollect to
/home/<yourmechid>:
cp -rf /iaas/pdcollect /home/<yourmechid>
b. Replace Components.xml with Components_nonroot.xml:
cp Components.xml Components.xml.org
cp Components_nonroot.xml Components.xml
1080 IBM SmartCloud Orchestrator 2.3: User's Guide
c. Replace pdcollect.py with pdcollect_nonroot.py:
cp pdcollect.py pdcollect.py.org
cp 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 SmartCloud 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:
Refer to Running the pdcollect tool on page 1079, 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.
Example Components.xml
This topic provides an example of Components.xml file that is used by
pdcollect.py.
<pdcollect>
<component name="ALL">
<execute command="ifconfig" workdir="/tmp" output="ifconfig.txt" />
<execute command="ps aux" workdir="/tmp" output="ps_aux.txt" />
<execute command="netstat -tulpen" workdir="/tmp" output="netstat_tulpen.txt" />
<execute command="netstat -rn" workdir="/tmp" output="netstat_rn.txt" />
<execute command="df -h" workdir="/tmp" output="df_h.txt" />
<execute command="free -m" workdir="/tmp" output="free_m.txt" />
<!-- Examples -->
<!-- Copies script /root/work/Example.sh to target machine into workdir
directory tmp. Executes command /tmp/Example.sh in directory /tmp and
saves command output in ExOutputlog which is compressed as ExOutput.txt.zip -->
<!--execute command="/tmp/Example.sh" workdir="/tmp" output="ExOutputlog"
script="/root/work/Example.sh" additionalOutput="ExOutput.txt"/ -->
<!-- Collects all matching /tmp/exampleOut*.log files and compresses
them into exout_logs.zip. output must be specified if using * or ? in filename -->
<!--logfile filename="/tmp/exampleOut*.log" output="exout_logs"/ -->
<!-- Collects single file /tmp/exampleOut.log -->
<!--logfile filename="/tmp/exampleOut.log" / -->
<!-- Collects directory /tmp/log and compresses it into tmp_logs.zip -->
<!--logdir directory="/tmp/log" output="tmp_logs"/ -->
</component>
Chapter 12. Troubleshooting 1081
<component name="INSTALLER">
<execute command="zip bootstrap-all-log.zip
bootsrap.log
workdir="var/log/smartcloud/" output="bootstrap-
all-out-log" additionalOutput="bootstrap-all-log.zip" />
<execute command="zip deploy-all--log.zip deploy*.log"
workdir="/var/log/smartcloud/" output="deploy-all
out-log" additionalOutput="deploy_all_log.zip" />
<execute command="zip db2-all-log.zip db2*.log
workdir="/var/log/smartcloud/" output="db2-all-out-
log" additionalOutput="db2-all-log.zip" />
</component>
<component name="BPM_Database">
<logdir directory="/tmp/db2" output="bpm_db2_logs" />
</component>
<component name="OpenStack_Nova">
<execute command="brctl show" workdir="/tmp" output="brctl.txt" />
<execute command="ip a s" workdir="/tmp" output="ip_a_s.txt" />
<logdir directory="/var/log/nova" output="nova_logs" />
<logdir directory="/etc/nova" output="nova_etc" />
</component>
<component name="OpenStack Neutron">
<logdir directory="/var/log/neutron"
output="neutron_logs" />
<logdir directory="/etc/neutron" output="neutron_etc" />
</component>
<component name="OpenStack_Glance">
<logdir directory="/var/log/glance" output="glance_logs" />
<logdir directory="/etc/glance" output="glance_etc" />
</component>
<component name="OpenStack_Cinder">
<logdir directory="/var/log/cinder" output="cinder_logs" />
<logdir directory="/etc/cinder" output="cinder_etc" />
</component>
<component name="OpenStack_Keystone">
<logdir directory="/var/log/keystone" output="keystone_logs" />
<logdir directory="/etc/keystone" output="keystone_etc" />
<execute command="source /root/keystonerc;keystone catalog" workdir="/tmp"
output="keystone_catalog.txt" />
</component>
<component name="IaaSGateway">
<logdir directory="/var/log/iaasgateway" output="iaasgw_logs" />
<logdir directory="/etc/iaasgateway" output="iaasgw_etc" />
</component>
<component name="VIL">
<logdir
directory="/opt/IBM/WebSphere/AppServer/profiles/imageLibraryProfile/logs/imageLibraryServer"
output="vil_imglibsrv_logs" />
<logfile filename="/tmp/fresh_install_vil.log" />
<logfile filename="/tmp/upgrade_vil.log" />
<logdir directory="/opt/origami/logs" output="origami_logs" />
<logdir directory="/opt/p2pdiff/TransferClient" output="transfer_client_logs" />
</component>
<component name="PCG">
<logfile filename="/var/log/pcg.log" />
<logfile directory="/opt/ibm/pcg/etc" />
</component>
<component name="SCE">
<logdir directory="/root/.SCE24/logs/" output="sce_logs" />
</component>
<component name="smartcloud">
<logfile filename="/var/log/nova/smartcloud.log" />
</component>
<component name="IWD_Rainmaker">
<logdir directory="/drouter/ramdisk2/mnt/raid-volume/raid0/logs/trace"
output="rainmaker_logs" />
<logfile filename="/drouter/ramdisk2/mnt/raid-volume/raid0/logs/derby.log" />
<logfile filename="/var/log/iwd.log" />
<logdir directory="/opt/ibm/rainmaker/purescale.app/config"
output="rainmaker_config" />
</component>
<component name="IWD_Storehouse">
<logdir
directory="/drouter/ramdisk2/mnt/raid-volume/raid0/usr/servers/storehouse/logs"
output="storehouse_logs_2" />
<logdir
directory="/drouter/ramdisk/mnt/raid-volume/raid0/usr/servers/storehouse/logs"
output="storehouse_logs" />
</component>
<component name="IWD_KernelServices">
<logdir
directory="/drouter/ramdisk2/mnt/raid-volume/raid0/usr/servers/kernelservices/logs"
output="ks_logs_2" />
<logdir
directory="/drouter/ramdisk/mnt/raid-volume/raid0/usr/servers/kernelservices/logs"
output="ks_logs" />
</component>
<component name="SCUI">
<logfile filename="/var/log/scoui.log" />
<logfile filename="/opt/ibm/ccs/scui/etc/config.json" />
</component>
1082 IBM SmartCloud Orchestrator 2.3: User's Guide
<component name="SCO">
<logfile
filename="/opt/ibm/SmartCloud_Orchestrator/properties/version/SmartCloud_Orchestrator-2.3.0.swtag" />
</component>
<component name="BPM_WebSphere">
<logdir directory="/opt/ibm/BPM/v8.5/profiles/Node1Profile/logs"
output="bpm_node_logs" />
<logdir directory="/opt/ibm/BPM/v8.5/profiles/DmgrProfile/logs"
output="bpm_dmgr_logs" />
<logfile filename="/tmp/bpm/bpm_install.log" />
</component>
<component name="SAAM">
<execute
command="/opt/IBM/tsamp/eez/bin/getamdata -all -outdir /tmp; zip saam_logs.zip /tmp/*-tsaam_data*"
workdir="/tmp" output="getamdata_out.txt" additionalOutput="saam_logs.zip" />
</component>
</pdcollect>
Example Environment.xml
This topic provides an example of Environment.xml file that is used by
pdcollect.py.
<pdcollect>
<host hostname="CS1_IP">
<component name="ALL"/>
<component name="INSTALLER"/>
<component name="CHEF_SERVER"/>
<component name="db2"/>
<component name="BPM_Database"/>
</host>
<host hostname="CS2_IP">
<component name="ALL"/>
<component name="OpenStack_Keystone"/>
<component name="IaaSGateway"/>
<component name="VIL"/>
<component name="PCG"/>
</host>
<host hostname="CS3_IP">
<component name="ALL"/>
<component name="IWD_Rainmaker"/>
<component name="IWD_Storehouse"/>
<component name="IWD_KernelServices"/>
<component name="SCUI"/>
<component name="SCO"/>
</host>
<host hostname="CS4_IP">
<component name="ALL"/>
<component name="BPM_WebSphere"/>
</host>
</pdcollect>
Example Environment_work.xml
This topic provides an example of Environment_work.xml file that is generated by
pdcollect.py.
<pdcollect>
<host hostname="CS1_IP">
<component name="ALL"/>
<component name="INSTALLER"/>
<component name="CHEF_SERVER"/>
<component name="db2"/>
<component name="BPM_Database"/>
</host>
<host hostname="CS2_IP">
<component name="ALL"/>
<component name="OpenStack_Keystone"/>
<component name="IaaSGateway"/>
<component name="VIL"/>
<component name="PCG"/>
Chapter 12. Troubleshooting 1083
</host>
<host hostname="CS3_IP">
<component name="ALL"/>
<component name="IWD_Rainmaker"/>
<component name="IWD_Storehouse"/>
<component name="IWD_KernelServices"/>
<component name="SCUI"/>
<component name="SCO"/>
</host>
<host hostname="CS4_IP">
<component name="ALL"/>
<component name="BPM_WebSphere"/>
</host>
<!-- KVM Region Server -->
<host hostname="KVM_Region_Server_IP">
<component name="ALL"/>
<component name="OpenStack_Nova"/>
<component name="OpenStack_Cinder"/>
<component name="OpenStack_Glance"/>
<component name="VIL_PROXY"/>
</host>
<!-- VMware Region Server -->
<host hostname="VMware_Region_Server_IP">
<component name="ALL"/>
<component name="OpenStack_Nova"/>
<component name="OpenStack_Cinder"/>
<component name="OpenStack_Glance"/>
<component name="SCE"/>
<component name="VIL_PROXY"/>
<component name="smartcloud"/>
</host>
<!-- PowerVM Region Server -->
<host hostname="PowerVM_Region_Server_IP">
<component name="ALL"/>
<component name="OpenStack_Nova"/>
<component name="OpenStack_Cinder"/>
<component name="OpenStack_Glance"/>
<component name="SCE"/>
<component name="VIL_PROXY"/>
<component name="smartcloud"/>
</host>
</pdcollect>
Setting logging levels
Set the logging levels of the SmartCloud Orchestrator components to increase or
decrease the collected troubleshooting information.
When the log data from SmartCloud 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.
1084 IBM SmartCloud Orchestrator 2.3: User's Guide
v To increase the logging level for the OpenStack Nova components such as
nova-api, nova-network, or nova-scheduler, 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
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 SmartCloud Orchestrator services,
see Managing the services on page 137.
v 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 SmartCloud Orchestrator services, see Managing the
services on page 137.
v To increase the logging level for the openstack-smartcloud component, edit the
etc/nova/smartcloud.conf file on the Region Server and change the Debug
value to True. After changing the logging level, you must restart
openstack-smartcloud. For information about starting SmartCloud Orchestrator
services, see Managing the services on page 137.
v 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.
v To increase the logging level for the SmartCloud Entry component, which is the
layer that communicates with VMControl and vCenter, edit the
/root/.SCE31/logging.properties file on the Region Server and change
level=WARNING to level=FINE or level=FINEST. After changing the logging level,
you must restart the SmartCloud Entry component by running the service sce
restart command.
v To increase the logging level for the IaaS Gateway component, edit the
/etc/iaasgateway/logging.conf file on Central Server 2 and change level =
WARNING to level = DEBUG. After changing the logging level, you must restart
the IaaS gateway component by running the service openstack-iaasgateway
restart command.
v To set the logging level for the Workload Deployer component, see Workload
Deployer log files on page 1087.
v To set the logging level for the Virtual Image Library component, see Log files
on page 330.
v 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 4 and click
Troubleshooting > Logs and trace to access the Logging and Tracing panel.
v To set the logging level for the Image Construction and Composition Tool, see
Setting logging levels for troubleshooting on page 467.
Log file rotation
SmartCloud Orchestrator uses the logrotate mechanism of Linux to manage log
file size and rotation settings. For information about adjusting the settings of the
Chapter 12. Troubleshooting 1085
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 IaaS gateway and Keystone log rotation settings are defined in the
/etc/logrotate.d/openstack-iaasgateway and /etc/logrotate.d/openstack-
keystone files on Central Server 2. For more information about the IaaS gateway
log file rotation, see Controlling the size of the IaaS gateway log file.
To set the log file rotation for the Virtual Image Library component, see Log files
on page 330.
Controlling the size of the IaaS gateway log file
When the size of the log file /var/log/iaasgateway/iaasgateway.log in Central
Server 2 increases too rapidly, apply one of the following solutions to solve the
problem.
v Follow the instruction at http://linuxcommand.org/man_pages/logrotate8.html
to update /etc/logrotate.d/openstack-iaasgateway, for example:
/var/log/iaasgateway/*.log {
weekly <==== Change this to "daily"
rotate 4
missingok
compress
minsize 100k
}
v Follow the instruction at http://docs.python.org/2/library/
logging.handlers.html to update the log handler in /etc/iaasgateway/
logging.conf, for example:
[loggers]
keys = root, iaasgateway
[handlers]
keys = stderr, stdout, watchedfile, syslog
[formatters]
keys = legacyiaasgateway, default
[logger_root]
level = WARNING
handlers = stdout
[logger_iaasgateway]
level = INFO
handlers = watchedfile next rotation will occur
qualname = iaasgateway
[handler_stderr]
class = StreamHandler
args = (sys.stderr,)
formatter = legacyiaasgateway
[handler_stdout]
class = StreamHandler
args = (sys.stdout,)
formatter = legacyiaasgateway
[handler_watchedfile]
class = handlers.RotatingFileHandler ===> rotate log file with 10 backups
args = (/var/log/iaasgateway/iaasgateway.log,a, 52428800, 10) ===> and set maxsize 50 M for each log file.
formatter = legacyiaasgateway
[handler_syslog]
class = handlers.SysLogHandler
args = (/dev/log, handlers.SysLogHandler.LOG_USER)
1086 IBM SmartCloud Orchestrator 2.3: User's Guide
formatter = legacyiaasgateway
[formatter_legacyiaasgateway]
format = %(asctime)s %(levelname)s [%(name)s] %(funcName)s %(message)s
[formatter_default]
format = %(message)s
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 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
Chapter 12. Troubleshooting 1087
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:
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 SEVERE: The task cannot continue, but the component can still function.
v WARNING: Potential or impending error.
v INFO: General information outlining the overall task progress.
v 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:
Problem determination command-line interface reference on page 874
You can work with SmartCloud Orchestrator problem determination using the
command-line interface.
Example script to configure the trace levels on page 238
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
SmartCloud Orchestrator.
1088 IBM SmartCloud Orchestrator 2.3: User's Guide
Product limitations
Review the following list of limitations of SmartCloud Orchestrator.
v The Power NPIV feature requires that all of the hosts in a given system pool
have NPIV-capable Fibre Channel adapters.
v Network adapter of type E1000E is not supported by SmartCloud Orchestrator.
You cannot deploy images containing this type of network adapter.
v For Power and VMware Regions, some of the image's configurations will affect
instances' flavor, for virtual system instances deployed from them. Their flavor
may be renamed to a format like Instance_UUID when using the nova show
<instance_id>. You can get the correct instance flavor from SmartCloud
Orchestrator using the following steps :
1. Login to SmartCloud Orchestrator.
2. Click Instances > Virtual System Instances.
3. Select YOUR_INSTANCE_NAME and in the Virtual machines section, expand your
virtual machine and see the Flavor in the Hardware and network section.
v It is not possible to resize VMware or Power virtual machines from a flavor with
larger disk size to a flavor with smaller disk size.
Installation errors
Check the known errors that can occur when installing SmartCloud Orchestrator.
Region Server installation failure with error: Region already
exists
Region Server installation fails with error Region <region_name> already exists.
Symptoms
On a Region Server, when you rerun deploy_region_server.sh to install a Region
Server, the installation fails with following error message:
E, [2013-09-05T05:59:39.667459 #3999] ERROR -- sc-deploy: install_task.rb::`log_error::
#< Region RegionOne already exists.
E, [2013-09-05T05:59:39.689040 #3999] ERROR -- sc-deploy: task_runner.rb::
`run::#<Thread:0x7fc4c1fa8358> RuntimeError: Region RegionOne already exists.>
Resolving the problem
Change the region name specified in the /install_image/installer/region-
server.cfg file, for example, region_name="OtherName". Then, try to install Region
Server again.
Installation fails because the chef-server is down
Installation fails with connect error because the chef-server is down.
Symptoms
The installation fails with following error message:
E, [2013-10-15T10:58:27.859323 #26090] ERROR -- sc-deploy: task_runner.rb::`run:
:#< Errno::ECONNREFUSED: Connection refused - Connection refused -
Connection refused connecting to 172.16.146.200:4000 for /environments/production, giving up
Causes
The problem is due to the fact that the chef server is down.
Resolving the problem
To resolve the problem, restart the chef server on central-server1 by entering the
following command:
Chapter 12. Troubleshooting 1089
service chef_repo_srvd restart
Then, try the installation again.
Installation fails to deploy central servers
Installation fails to deploy central servers.
Symptoms
Installation fails to deploy central servers using command
./deploy_central_server.sh -a password -P password.
You see the following error message in /var/log/smartcloud/deploy.log:
10.10.0.153 [Thu, 10 Oct 2013 03:51:17 -0400] INFO: execute[Invoke IWD command line interface
to install foundation...] sh(sudo -i /opt
/ibm/cli/deployer.cli/bin/deployer -h 10.10.0.153 -u admin -p sco4svt -c
"deployer.patterntypes.create(http://172.16.134.151/scp/
install-packages/iwd/foundation-2.0.1.1.tgz)")
10.10.0.153 [Thu, 10 Oct 2013 03:55:25 -0400] ERROR: execute[Invoke IWD
command line interface to install foundation...] (
workload_deployer::install_ptype line 6) has had an error
10.10.0.153 [Thu, 10 Oct 2013 03:55:25 -0400] ERROR: execute[Invoke IWD
command line interface to install foundation...] (/var/chef/
cache/cookbooks/workload_deployer/recipes/install_ptype.rb:6:in `from_file) had an error:
10.10.0.153 execute[Invoke IWD command line interface to install foundation...]
(workload_deployer::install_ptype line 6) had an error:
Chef::Exceptions::ShellCommandFailed: Expected process to exit with [0], but received 1
Additionally, the file /opt/ibm/cli/deployer.cli/logs/cli.log, also located on the
central-server, contains a time-correlated message similar to the following message:
Thu Oct 10 03:55:22 2013 DEBUG:
HTTP response: 500 Internal Server Error
---------[body]---------
{
"errorMessage": "CWZPL0077X: Failed to extract contents of solution archive",
"message": "CWZPL0077X: Failed to extract contents of solution archive",
"errorStatusCode": 500,
"rootCause": "com.ibm.maestro.util.wrapper.exception.MaestroServerException:
CWZPL0077X: Failed to extract contents of solution archive"
}
Causes
The problem is due to a bad network status or storage latency.
Resolving the problem
Perform the following steps and then try to install SmartCloud Orchestrator again.
1. Check network status and ensure that there is no network latency. For example,
on central-server-3:
# wget http://$central-server-1_ip/scp/install-packages/iwd/foundation-2.0.1.1.tgz
If the speed is very slow, restart the http service on central-server-1 and check
the network connections of your environment and then try it again.
2. Check storage latency. For example:
# time dd if=/dev/zero of=/$storage_partition_path/test.img bs=4k count=1M
1048576+0 records in
1048576+0 records out
4294967296 bytes (4.3 GB) copied, 70.2898 s, 61.1 MB/s <==This is the speed.
real 1m10.291s
user 0m0.951s
sys 0m48.375s
1090 IBM SmartCloud Orchestrator 2.3: User's Guide
The speed must be greater than 100 MBs, otherwise a storage latency issue might
exist. Check your storage configuration and ensure that there is no storage latency
Installation fails to deploy central servers (2)
There might be another case that the installation fails to deploy central servers.
Symptoms
Installation fails to deploy central servers using command
./deploy_central_server.sh -a password -P password.
The output message looks like the following:
License accepted
LOG file is /tmp/bootstrap-2014-02-06-13-00-26.log
2014-02-06 13:00:28 chrvl551 [check_prereq] Running with Red Hat Enterprise Linux 6.4 iso.
2014-02-06 13:00:28 chrvl551 [clean_last] Cleaning /etc/hosts ...
...
...
2014-02-06 13:00:48 chrvl551 [result] Bootstrap completes.
Refer to /var/log/smartcloud/bootstrap-2014-02-06-13-00-26.log for more details.
Initializing ... done
Refer to /var/log/smartcloud/deploy.log for more details.
- Loading deployment tasks ... done
- Processing task 1 of 13, whole deployment process will be completed in about 153 minutes (0% completed).
- Running task load-context(about 1 minutes): Load deployment context ... done
- Processing task 2 of 13, whole deployment process will be completed in about 152 minutes (0% completed).
- Running task pre-check(about 1 minutes): Checking parameters ... done
- Processing task 3 of 13, whole deployment process will be completed in about 151 minutes (1% completed).
- Running task setup-repos(about 5 minutes): Setup SCP/O components central server repositories ... done
- Processing task 4 of 13, whole deployment process will be completed in about 146 minutes (4% completed).
- Running task chef-environment(about 1 minutes): Create chef environment definition ... fail
[ERROR] undefined method `override_attributes for #<Hash:0x7f4ad03a7f60>
Refer to /var/log/smartcloud/deploy.log for more details.
And you can see the following error message in /var/log/smartcloud/deploy.log:
Thread:0x7f4ad2e4a358> task setup-repos: Setup SCP/O components central server repositories
completed successfully.
I, [2014-02-06T13:02:55.231692 #11637] INFO -- sc-deploy: task_runner.rb::`run::#
<Thread:0x7f4ad2e4a358> Running task chef-environment: Create chef environment definition
E, [2014-02-06T13:02:55.7I, [2014-02-06T13:02:55.230718 #11637]
INFO -- sc-deploy: task_runner.rb::`run::#35068 #11637]
ERROR -- sc-deploy: task_runner.rb::`run::#<Thread:0x7f4ad2e4a358>
NoMethodError: undefined method `override_attributes for #<Hash:0x7f4ad03a7f60>
/install_images/installer/commands/../lib/deploy/central-server/020gen_chef_env.rb:21:in
`additional_attr
Causes
v There may be some existing ruby-gem packages which conflict with the
SmartCloud Orchestrator installation gem packages.
v Some rubygem RPMs are not installed correctly, particularly the rubygem-json
RPM.
Resolving the problem
Check if some of the following packages are installed on the Central Servers
operating systems and remove them before installing SmartCloud Orchestrator
again:
puppet, facter, hiera, mcollective, mcollective-common, subversion-ruby, libselinux-ruby,
ruby-augeas, ruby-rgen, ruby-shadow, rubygem-json, rubygem-stomp, rubygems
If there is still some error during the SmartCloud Orchestrator installation
informing that some file is not found in ruby path, manually remove the ruby
RPM and clean the folder /usr/lib/ruby/* . Then deploy the Central Servers
again.
Chapter 12. Troubleshooting 1091
Region Server deployment completes with network configuration
warning
This topic describes a problem that may occur when the Region Server is being
installed.
Symptoms:
The Region Server installation completes with the following warning message:
* Failed to run task config-network: Network configuration. Failed to configure
region-server network settings, refer to document for the region-server network
post-configuration.
[WARN] region-server deployment completed with warning, refer document for the further
information.
Resolving the problem:
1. Check the file /install_image/installer/region-server.cfg to make sure that
the parameters are correctly defined.
2. On the Region Server, rerun the config_network.sh:
# cd /install_image/installer/scripts
# ./config_network.sh -d $db2_password -p $vcenter/vmcontrol_password
Error when upgrading the Region Server
The following error may occur when you upgrade the Region Server.
Symptoms:
When upgrading the Region Server, in /tmp/bootstrap-update-yyyy-mm-dd-hh-mi-
ss.log, you see the following error message:
Existing lock /var/run/yum.pid: another copy is running as pid 12232.
Another app is currently holding the yum lock; waiting for it to exit...
The other application is: PackageKit
Memory : 47 M RSS (357 MB VSZ)
Started: Fri Mar 14 08:05:48 2014 - 1:35:49 ago
State : Sleeping, pid: 12232
Another app is currently holding the yum lock; waiting for it to exit...
The other application is: PackageKit
Memory : 47 M RSS (357 MB VSZ)
Started: Fri Mar 14 08:05:48 2014 - 1:35:51 ago
State : Sleeping, pid: 12232
......
Reason:
PackageKit is attempting to update the yum database when upgrading SmartCloud
Orchestrator. You must kill the PackageKit process manually or disable automatic
update checks for PackageKit.
Solution 1: Kill the PackageKit process manually:
Perform the following steps:
[root@rs-kvm-rhel63Desktop tmp]# ps -ef | grep yum
root 12232 12230 0 08:05 ? 00:00:01 /usr/bin/python /usr/share/PackageKit/helpers/yum/yumBackend.py get-packages unknown
root 16612 16411 0 09:41 pts/0 00:00:01 /usr/bin/python /usr/bin/yum clean all
root 17110 6398 0 10:03 pts/1 00:00:00 grep yum
Kill the first one (which is mentioned in the log):
[root@rs-kvm-rhel63Desktop tmp]# kill -9 12232
1092 IBM SmartCloud Orchestrator 2.3: User's Guide
After you have killed the PackageKit, the upgrade can be processed.
Solution 2: disable automatic update checks for PackageKit:
Edit refresh-packagekit.conf:
Open /etc/yum/pluginconf.d/refresh-packagekit.conf with a text editor and
make this change:
enabled=0
Reboot the system.
Run the script for upgrading the SmartCloud Orchestrator Region Server again.
For information on PackageKit, refer to https://access.redhat.com/site/
documentation/en-US/Red_Hat_Enterprise_Linux/6/html/Deployment_Guide/
ch-PackageKit.html.
Upgrade Central Server fails while re-run
deploy_central_server.sh
Re-running deploy_central_server.sh on Central Sever 1 fails when some pattern
type already exists.
Symptoms:
Re-running deploy_central_server.sh on Central Sever 1 to upgrade the
SmartCloud Orchestrator Region Servers fails with following error message:
I, [2014-03-26T18:00:48.231760 #32030] INFO -- sc-deploy: exec_cmd.rb::`run_cmd_log::#<Thread:0x7ff4d97cf030> 10.9.219.28 ---- Begin output of sudo
...
...
I, [2014-03-26T18:00:48.234481 #32030] INFO -- sc-deploy: exec_cmd.rb::`run_cmd_log::#<Thread:0x7ff4d97cf030> 10.9.219.28 File "/opt/ibm/cli/deploye
I, [2014-03-26T18:00:48.234692 #32030] INFO -- sc-deploy: exec_cmd.rb::`run_cmd_log::#<Thread:0x7ff4d97cf030> 10.9.219.28 return _defaultChunkedResp
I, [2014-03-26T18:00:48.234931 #32030] INFO -- sc-deploy: exec_cmd.rb::`run_cmd_log::#<Thread:0x7ff4d97cf030> 10.9.219.28 File "/opt/ibm/cli/deploye
I, [2014-03-26T18:00:48.235233 #32030] INFO -- sc-deploy: exec_cmd.rb::`run_cmd_log::#<Thread:0x7ff4d97cf030> 10.9.219.28 raise IOError(utos(read.ge
I, [2014-03-26T18:00:48.235490 #32030] INFO -- sc-deploy: exec_cmd.rb::`run_cmd_log::#<Thread:0x7ff4d97cf030> 10.9.219.28 IOError: CMPUT0061E: The p
Causes:
Some pattern type has already been created on Central Sever 3 when running
deploy_central_server.sh for the first time.
Resolving the problem:
You must run the following command on Central Server 3 to remove the pattern
type before re-running deploy_central_server.sh:
# sudo -i /opt/ibm/cli/deployer.cli/bin/deployer -h <Central Server 3 IP address> -u admin -p <admin password> -c "deployer.patterntypes.delete(orc
Note: In a different environment, the command may be different. The pattern
name in the command must be consistent with the one in error message.
Taking the error message for example, on Central Server 3, you must run:
# sudo -i /opt/ibm/cli/deployer.cli/bin/deployer -h 10.9.219.28 -u admin -p password -c "deployer.patterntypes.delete(orchestration ,1.0.1.1)"
Chapter 12. Troubleshooting 1093
Hypervisor errors and scenarios that can cause them
You can receive error messages for hypervisors defined to SmartCloud
Orchestrator under certain circumstances.
If you change a password on a started hypervisor, SmartCloud Orchestrator gives
you error messages. The following error messages are shown for each of the
following scenarios:
Login is not valid
This message is shown, in the user interface, on the Hypervisors window if
you have performed the following steps:
1. Defined a hypervisor to SmartCloud Orchestrator and started it.
2. Changed the password on the hypervisor, but did not change it in
SmartCloud Orchestrator.
3. Rediscovered the hypervisor in SmartCloud Orchestrator.
Be sure that you change the password for the hypervisor on SmartCloud
Orchestrator, and not just on the hypervisor itself, to prevent this issue.
Unable to connect to endpoint. URL:
<address_of_hypervisor_that_cannot_be_reached>
This message is shown, in the user interface, if you have performed the
following steps:
1. Defined a hypervisor to SmartCloud Orchestrator and started it.
2. Disconnected the hypervisor from the network.
3. Rediscovered the hypervisor in SmartCloud Orchestrator.
Minus (-) free ram is displayed in OpenStack for command nova
hypervisor-show
After the deployment of SmartCloud Orchestrator, use the following
commands to get the nova information:
[root@region-server-1 ]# nova hypervisor-list
+----+----------------------+
| ID | Hypervisor hostname |
+----+----------------------+
| 1 | computenodeB |
+----+----------------------+
[root@region-server-1 ~]# nova hypervisor-show 1
+----------------------+--------------------------+
| Property | Value |
+----------------------+--------------------------+
| hypervisor_hostname | computenodeB |
| cpu_info | {"vendor": "Intel", .....|
| free_disk_gb | 45 |
| hypervisor_version | 12001 |
| disk_available_least | -7 | => Note that the disk is
| local_gb | 125 | a negative number
| free_ram_mb | 36993 |
| id | 1 |
| vcpus_used | 9 |
| hypervisor_type | QEMU |
| local_gb_used | 80 |
| memory_mb_used | 11264 |
| memory_mb | 48257 |
| current_workload | 0 |
| vcpus | 16 |
| running_vms | 7 |
| service_id | 7 |
| service_host | computenodeB |
+----------------------+--------------------------+
1094 IBM SmartCloud Orchestrator 2.3: User's Guide
Solution
disk_available_least for hypervisor can be a negative number to indicate
the over commitment of hypervisor disk space.
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.
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
OpenStack hypervisor fails and virtual machines cannot be
deployed
The following message is displayed:
Hypervisors could not be located to place virtual systems
This error might occur when many continuous deployment tasks are being run. In
the Hypervisor menu, you can see the hypervisor is in failure state and when you
check the hypervisor details, the following errors are reported:
v "An internal error occurred while accessing hypervisor: Problem while
invoking get operation for URI: /os-networks"
v "An internal error occurred while accessing hypervisor: Problem while
invoking get operation for URI: /servers"
Another symptom of this problem is the message that is displayed when you
check the cloud group details: You must start at least one hypervisor to
create virtual systems.
Solution
Restart the hypervisor by performing the following steps:
1. Log in to the user interface.
2. Go to the Hypervisor menu.
3. Select the hypervisor that is in failure state and put it in maintenance mode.
4. Run the discovery.
5. Restart the hypervisor.
Chapter 12. Troubleshooting 1095
An internal error occurs while accessing the hypervisor
This could occur when the connection to the hypervisor times out (for example,
when the whole system is restarted and a region is started after SmartCloud
Orchestrator is already up and running. SmartCloud Orchestrator could get in
timeout before the region is active).
Solution:
v Navigate to Configuration-->Hypervisor.
v Select the failed hypervisor.
v Select: Quiesce.
v Select: Maintain.
v Select: Start.
Related tasks:
Administering hypervisors on page 187
You can use the SmartCloud Orchestrator user interface to work with the
hypervisors.
Image errors
Check the known errors that can occur when managing images in SmartCloud
Orchestrator.
Cannot invoke method startsWith() on null object
When selecting a virtual image in the SmartCloud Orchestrator user interface, the
following error is displayed:
Cannot invoke method startsWith() on null object
In the trace.log file, the following error is found:
java.io.FileNotFoundException:
/drouter/ramdisk2/mnt/raid-volume/raid0/templates/rainmaker-templates/15/.cloudburst
(No such file or directory)
The virtual image cannot be deleted.
Causes
The problem occurs because the /drouter/ramdisk2/mnt/raid-volume/raid0/
templates/rainmaker-templates/ directory is empty or it does not contain required
information about the virtual image.
Resolving the problem
Restore the directory content from a product backup or register the image again.
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
1096 IBM SmartCloud Orchestrator 2.3: User's Guide
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.
The deployment of Windows images never completes
You can encounter this issue if you either captured a Windows image on
OpenStack or directly on the hypervisor (VMware or KVM). The problem depends
on the fact that the activation engine already runs on the image.
You can check this looking for the presence of the file c:\windows\setup\ibm\AR\
ovf-env.done. If the activation engine already completed its job, then the autologon
feature is disabled.
The consequence of this problem, is that if you try to deploy the captured image
using Workload Deployer, the deployment does not succeed because the activation
engine waits for somebody to log on to the system to run.
Resolving the problem
To resolve this problem, run the following command before capturing the image:
rl.cmd --user=<Administrator name> --password=<Administrators password>
The command can be found in the deployed image under c:\Windows\Setup\ibm.
Problem deploying an image into VMware
The user attempts to deploy an image into the VMware hypervisor and receives an
error in the Workload DeployerUI, which says "Virtual machine could not be
registered." No other error is displayed to the user.
Resolving the problem:
The administrator needs to ssh into the Central Server 3, and look in the
/drouter/ramdisk2/mnt/raid-volume/raid0/logs/error/error.log and
/drouter/ramdisk2/mnt/raid-volume/raid0/logs/trace/trace.log files to see if
there is anything describing why the image could not be registered.
If the administrator does not find anything in those 2 logs, then they need to look
on the Region Server in /var/log/nova/smartcloud.log to see if there is anything
showing why the virtual machine failed to launch.
Chapter 12. Troubleshooting 1097
If the administrator does not find anything in the smartcloud.log file, then they
need to look in /root/.SCE31/logs/skc-0.log to see if there is anything showing
why the virtual machine failed to launch.
VMware disk size is not handled properly
The user attempts to deploy an image into the VMware hypervisor and receives an
error in the Workload Deployer UI, which says "Virtual machine could not be
registered." No other error is displayed to the user.
Resolving the problem:
The administrator needs to ssh into the Central Server 3, and look in the
/drouter/ramdisk2/mnt/raid-volume/raid0/logs/error/error.log and
/drouter/ramdisk2/mnt/raid-volume/raid0/logs/trace/trace.log files to see if
there is anything describing why the image could not be registered.
If the administrator does not find anything in those 2 logs, then they need to look
on the Region Server in /var/log/nova/smartcloud.log to see if there is anything
showing why the virtual machine failed to launch.
If the administrator does not find anything in the smartcloud.log file, then they
need to look in /root/.SCE31/logs/skc-0.log to see if there is anything showing
why the virtual machine failed to launch.
For this case, where the flavor is the wrong size, they will find the error in the
smartcloud.log file:
CYX0825E: The size specified 10240 for the disk Hard disk 1 is invalid.
The value must be an integer between 12,288 and 16,777,216.
They must either create a new flavor with a large enough disk to fit the image they
are attempting to launch, or choose the m1.tiny flavor with a disk size of 0.
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.
Trying to register an image in Workload Deployer, the virtual
image remains in "downloading virtual image" status
Causes
The image contains spaces and this creates an issue to Virtual Image Library.
Resolving the problem
Extend the image giving it a name without spaces. To avoid that the image
remains in "downloading virtual image" status, restart Workload Deployer
(running service iwd restart on the Central Server 3). After the restart, the image
will be in "failed" status and you can remove it using the Workload Deployer user
interface.
1098 IBM SmartCloud Orchestrator 2.3: User's Guide
Deploying images using SmartCloud Orchestrator fails with
message "Registration failed"
Deploying images on VMware with SmartCloud Orchestrator fails with message
"Registration failed". Even if you try to deploy the image directly using OpenStack
with nova boot, the deployment of the image goes in ERROR state (you can check
it with nova list).
Look on the Region Server at the SmartCloud Entry driver logs under
/root/.SCE31/logs for this string:
Required property identity is missing from data object of type CustomizationSpec
Resolving the problem
If you find this error, then check that the template that you are deploying has the
proper operating system set in vCenter:
v Convert the template to a virtual machine, select it, and display its properties.
v Select the Options tab.
v Check that the Guest Operating System radio button is either Windows or
Linux, if not modify it according to the operating system of your image.
v Convert back the image to a template.
When you have completed this activity in vCenter:
v In Virtual Image Library, select the image and basic index it again.
v Remove the image from Workload Deployer and register it back to ensure that
Workload Deployer displays the proper operating system in the pattern editor.
v Deploy the image again.
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
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 and has been traced in the community. 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.
Chapter 12. Troubleshooting 1099
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
Can check the known errors that may occur when managing instances in
SmartCloud 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 SmartCloud
Orchestrator package and then run:
/etc/init.d/openstack-nova-consoleauth restart
.
Deployment errors
Check the known errors that can occur when deploying virtual system patterns
and images in SmartCloud 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 hostname 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 could be something like the following sample:
nslookup $IPADDR | findstr Name > %TEMP%\oldhostname
set /p str=<%TEMP%\oldhostname
echo."%str%"
1100 IBM SmartCloud Orchestrator 2.3: User's Guide
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 SmartCloud 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 provided script example reboots the image.
This limitation impacts on 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 the Properties variable syntax topic.
Unable to deploy a virtual system pattern with a non-admin user
Refer to this topic if you are 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-172-16-30-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, then 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
172.16.30.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 |
+----------------------------------+------------+---------+
| 1f9f8b62052046ee97763f4eb88288e3 | service | true |
| 3c8b192caab1499aa4aeb2dcf4280a12 | admin | true |
Chapter 12. Troubleshooting 1101
| c7ea7db95d2241c383f2f5995b31fa19 | project003 | true |
+----------------------------------+------------+---------+
[root@SVT-CIL-NEW ~]# nova-manage network list
id IPv4 IPv6 start address DNS1 DNS2 VlanID
1 172.16.30.0/24 None 172.16.30.10 172.16.30.2 172.16.30.2 4090
project ...
c7ea7db95d2241c383f2f5995b31fa19 ...
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 172.16.30.0/24 c7ea7db95d2241c383f2f5995b31fa19
Error displayed when deploying a virtual system pattern
Refer to this topic if you 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 may 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, in some cases
the Flavor field could also be empty.
Solution:
After selecting the Deploy icon, select Configure virtual parts, and enter
the required details.
Unable to deploy a virtual machine in a VMware multi-region
environment
Refer to this topic if you are unable to deploy a virtual machine in a VMware
multi-region environment.
Symptoms:
You cannot see theSmartCloud Entry login page and you see the following errors
in the log file /root/.SCE24/logs/skc-0.log:
00002 WARNING: CYX5911W: Failed to connect to AMQP server or lost the connection
[hostname: 172.16.34.2:5672] due to [connection aborted], will retry later -
com.ibm.cfs.services.messaging.qpid.internal.QPIDConnection$1.onException
[08/10/13 11:15:36:439] 00002 SEVERE: CYX4690E: Problem refreshing workload.
The workload IBM OS Image for ken has been lost in the Cloud. It may have purposely
been deleted in the Cloud.
No action is required at this time. -
com.ibm.cfs.services.cloud.delegates.impl.internal.DeploymentRefreshDelegateByPush.deleteDeployment
[08/10/13 11:15:37:004] 00003 SEVERE: CYX1027E: Exception prevented fulfilling API request.
null
See the error message for details about recovery. -
com.ibm.cfs.api.mappers.BaseExceptionMapper.toResponse
[08/10/13 23:45:46:503] 00002 WARNING: CYX5911W: Failed to connect to AMQP server
or lost the connection [hostname: 172.16.34.2:5672] due to [connection aborted],
will retry later - com.ibm.cfs.services.messaging.qpid.internal.QPIDConnection$1.onException
1102 IBM SmartCloud Orchestrator 2.3: User's Guide
Solution:
Restart the following services to recover the environment:
service qpidd restart
service sce restart
service openstack-smartcloud restart
Unable to deploy a virtual machine due to insufficient resources
SmartCloud Orchestrator fails to deploy a virtual machine due to insufficient
resources, although it is possible to provision a virtual machine directly via
OpenStack.
Symptoms
An attempt to deploy a virtual machine in a VMware environment fails with "The
cloud did not contain sufficient memory to place the virtual system."
In the file /drouter/ramdisk2/mnt/raid-volume/raid0/logs/trace/trace.log on
cs-3, you find following exception:
[2013-09-29 05:19:53:631 EDT] 00000664 groovy E
app.scripts.groovy.rainmaker.core.EventUtils.groovy java.lang.RuntimeException:
java.lang.Exception: Can not place virtual system due to insufficient memory
Checking the hypervisor page, you see that the memory usage is 100%.
It is possible to deploy a virtual machine using the same flavor directly through
the OpenStack CLI.
Causes
The difference in behavior is caused by the different memory over commitment
settings used by SmartCloud Orchestrator and OpenStack. By default, OpenStack
assumes an over-commitment ratio of 1.5, as defined in nova.conf:
# virtual ram to physical ram allocation ratio (default: 1.5)
ram_allocation_ratio=1.5
SmartCloud Orchestrator does not allow over-commitment at all. This causes
difference in the conditions where there is less than required by flavor definition
amount of memory available on a hypervisor. In such cases, Workload Deployer
fails to provision the virtual machine while OpenStack uses the over-commitment
setting.
Resolving the problem
It is possible to deploy a virtual machine using the same flavor directly through
the OpenStack CLI.
Deployment might hang
Deploying a pattern, the deployment might hang.
Symptoms
In some scenarios, when you deploy a pattern, it might hang. An example is a
scenario where you:
1. Create a Windows VMware template.
2. Reconfigure it, converting it to a VMware virtual machine.
3. Log on to the virtual machine.
4. Convert the virtual machine back to template.
Chapter 12. Troubleshooting 1103
Causes
In some cases, the deployment hangs because autologon was reset with the first
login in the template or VM.
Resolving the problem
Perform the following steps:
1. Convert the template to virtual machine.
2. Enter the command: c:\\windows\\setup\\ibm\\ae.bat --reset -n --user
"<username> " --password "<password>"
3. Shut down the operating system.
4. Convert the virtual machine back to a template.
Unable to deploy IBM DB2 Enterprise or WebSphere MQ OVA
image
When you try to deploy the IBM DB2 Enterprise 10.5 OVA image, or the
WebSphere MQ OVA image, the operation might hang.
Solution
To resolve the problem, complete the following steps for both IBM DB2 Enterprise
10.5 and for WebSphere MQ:
1. Convert the base template to a virtual machine.
2. Log into the virtual machine as the root user.
3. Ensure that the /opt/IBM/AE/compatflags file has an entry for the --searchap
flag.
4. Create the /root/.bashrc file:
# cp /root/.bash_profile /root/.bashrc
5. Run the following commands:
# rm /opt/IBM/AE/AP/noap
# rm /etc/udev/rules.d/70-persistent-net.rules
# rm /lib/udev/write_net_rules
# cat /dev/null /etc/sysconfig/network-scripts/ifcfg-eth0
6. Log out of the virtual machine.
7. Convert the virtual machine back to a template.
8. Try to deploy again.
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 will
then use 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"},
1104 IBM SmartCloud Orchestrator 2.3: User's Guide
"rules":
[{"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.
Unable to deploy WebSphere Portal 8.0.0.1 pattern
When you try to deploy WebSphere Portal 8.0.0.1, the operation might hang.
Solution
To resolve the problem, perform the following steps:
1. Add the virtual image to the catalog in SmartCloud Orchestrator by importing
the OVA file.
2. Once the image has been added, verify in Virtual Image Library that it is
stored in the reference repository.
3. Once the image indexing is successfully completed, checkout the image
(selecting VMware as hypervisor manager).
4. If the image failed to checkout from Virtual Image Library with error
"COPIML865EVMWareToolsNotInstalled" then log on to the vSphere Server
using the vSphere Client, install the VMware tool in the Image virtual
machine, shutdown the virtual machine and convert the virtual machine into
template by right-clicking on VM >> Template >> convert to template. This
template/image will be shown in the VMware region repository.
5. Wait until the image indexing ends successfully.
6. Import the image to the local repository in Image Construction and
Composition Tool and extend it.
7. Once extended, launch the synchronize action.
8. During the synchronization, activate manually the virtual machine otherwise
the synchronization will fail: first, check the assigned IP address (using the
nova list command), then access to the vCenter, and, once the virtual
machine is started, activate it, setting the checked value as IP address.
9. After manually assigning the IP address, if restart network is failing with an
error like device eth0 does not seem to be present, delaying
initialization, then execute this command:
rm -f /etc/udev/rules.d/70-persistent-net.rules
and reboot.
10. Once synchronized, log in to the synchronized image and remove the
/opt/ibm/ae/AP/noap file.
11. Capture it.
12. In SmartCloud Orchestrator, go to Image and patterns > Virtual images > +,
select the image which has just been extended in Image Construction and
Composition Tool, click Map to image and select the original image in the list
of registered images.
13. Deploy the pattern.
Chapter 12. Troubleshooting 1105
14. If the deploy fails with an OpenStack null error and, moreover, Flavor list
cannot be available for the Deployment manager node, you must remove and
add again this Deployment manager node in the pattern editing canvas.
Unable to deploy IBM InfoSphere Information Server Enterprise
Edition 9.1 pattern
When you try to deploy IBM InfoSphere Information Server Enterprise Edition 9.1,
the operation might hang.
Solution
To resolve the problem, perform the following steps:
1. Add the virtual image to the catalog in SmartCloud Orchestrator by importing
the OVA file.
2. Once the image has been added, verify in Virtual Image Library that it is
stored in the reference repository.
3. Once the image indexing is successfully completed, checkout the image
(selecting VMware as hypervisor manager).
4. Wait until the image indexing ends successfully.
5. Import the image to the local repository in Image Construction and
Composition Tool and extend it.
6. Once extended, launch the synchronize action.
7. During the synchronization, activate manually the virtual machine otherwise
the synchronization will fail: first, check the assigned IP address (using the
nova list command), then access to the vCenter, and, once the virtual
machine is started, activate it, setting the checked value as IP address.
8. After manually assigning the IP address, if restart network is failing with an
error like device eth0 does not seem to be present, delaying
initialization, then execute this command:
rm -f /etc/udev/rules.d/70-persistent-net.rules
and reboot.
9. Once synchronized, log in the image synchronized and remove the
file /opt/ibm/ae/AP/noap.
10. Capture it.
11. In SmartCloud Orchestrator, go to Image and patterns > Virtual images > +,
select the image which has just been extended in Image Construction and
Composition Tool, click Map to image and select the original image in the list
of registered images.
12. Deploy the pattern.
Unable to deploy IBM Integration Bus Hypervisor Edition pattern
When you try to deploy IBM Integration Bus Hypervisor Edition, the operation
might hang.
Solution
To resolve the problem, perform the following steps:
1. Add the virtual image to the catalog in SmartCloud Orchestrator by importing
the OVA file.
2. Once the image has been added, verify in Virtual Image Library that it is
stored in the reference repository.
1106 IBM SmartCloud Orchestrator 2.3: User's Guide
3. Once the image indexing is successfully completed, checkout the image
(selecting VMware as hypervisor manager).
4. Wait until the image indexing ends successfully.
5. Import the image to the local repository in Image Construction and
Composition Tool and extend it.
6. Once extended, launch the synchronize action.
7. During the synchronization, activate manually the virtual machine otherwise
the synchronization will fail: first, check the assigned IP address (using the
nova list command), then access to the vCenter, and, once the virtual
machine is started, activate it, setting the checked value as IP address.
8. After manually assigning the IP address, if restart network is failing with an
error like device eth0 does not seem to be present, delaying
initialization, then execute this command:
rm -f /etc/udev/rules.d/70-persistent-net.rules
and reboot.
9. Once synchronized, log in to the synchronized image and remove the
/opt/ibm/ae/AP/noap file.
10. Capture it.
11. In SmartCloud Orchestrator, go to Image and patterns > Virtual images > +,
select the image which has just been extended in Image Construction and
Composition Tool, click Map to image and select the original image in the list
of registered images.
12. Deploy the pattern.
Unable to deploy or to delete virtual machines
This problem applies only to VMware regions.
Symptoms:
Deploying or deleting deployed virtual machines is not possible neither from the
user interface nor from OpenStack directly.
In /var/log/nova/smartcloud.log you can find messages like:
2013-11-23 09:08:24 ERROR smartcloud.virt.sce.service [-] There was a
problem retrieving the host information for workload 39801 from SCE. The
server cant be managed by nova. This is most likely an SCE issue.
This problem depends on the fact that SmartCloud Entry is misaligned with the
current VMware vCenter infrastructure.
Solution:
1. On the Region Server for the failing region run glance image-list to get the
IDs of all images. A sample output is:
[root@myfirstbox ~]# glance image-list
+--------------------------------------+-------------------------------------
| ID | Name
+--------------------------------------+-------------------------------------
| 4205ff92-e82b-3645-9252-f1f33d4084ba | MyImage
| 42057a0e-e93f-e495-1f4d-d89d6144e87a | TestImage
+--------------------------------------+-------------------------------------
+-------------+------------------+--------+--------+
| Disk Format | Container Format | Size | Status |
+-------------+------------------+--------+--------+
Chapter 12. Troubleshooting 1107
| vmdk | bare | | active |
| vmdk | bare | | active |
+-------------+------------------+--------+--------+
2. Get the public URL of keystone from the openstack-iaasgateway service
running keystone endpoint-list. A sample output is:
[root@myfirstbox ~]# keystone endpoint-list
+----------------------------------+-----------+---------------------------------------------------------
| id | region | publicurl
+----------------------------------+-----------+---------------------------------------------------------
| 3a62f7ec92474c738659a1bb33c4ead5 | RegionOne | http://172.17.43.128:5000/v3
| 7c4833e69f6643239530518669c3300a | RegionOne | http://172.17.43.128:8776/v1/%(tenant_id)s
| 7d344cfcbc9841f988b9ef79c5c87529 | RegionOne | http://172.17.43.128:8774/v2/%(tenant_id)s
| afbcd2278ccc40febdb1f51db8188d12 | RegionOne | http://172.17.43.128:9292/
| cc8502efb79a42ef83b87682a7bba754 | RegionOne | https://172.17.43.129:9443/ImageLibrary/ImageService/v1
+----------------------------------+-----------+---------------------------------------------------------
+---------------------------------------------------------
| internalurl
+---------------------------------------------------------
| http://172.17.43.128:5000/v3
| http://172.17.43.128:8776/v1/%(tenant_id)s
| http://172.17.43.128:8774/v2/%(tenant_id)s
| http://172.17.43.128:9292/
| https://172.17.43.129:9443/ImageLibrary/ImageService/v1
+---------------------------------------------------------
+---------------------------------------------------------+----------------------------------+
| adminurl | service_id |
+---------------------------------------------------------+----------------------------------+
| http://172.17.43.128:35357/v3 | 786318e637bf4f4db363346fab847a8d |
| http://172.17.43.128:8776/v1/%(tenant_id)s | e96e8ff119964389b2802742064eb22c |
| http://172.17.43.128:8774/v2/%(tenant_id)s | c03ec01b38ba4fd28ecc312a3aa10e77 |
| http://172.17.43.128:9292/ | a842a179175b4a3dbc0d8269c7ca257e |
| https://172.17.43.129:9443/ImageLibrary/ImageService/v1 | 3c243197492d41aa85679c5f8662c67a |
+---------------------------------------------------------+----------------------------------+
3. Generate the unscoped token to connect to the openstack-iaasgateway service
running the following command (enter the command on one line) on the
Region Server or on any other system that can access openstack-iaasgateway
service in that region :
curl -v -d { "auth": { "identity": { "methods":["password"], "password": { "user":
{ "domain": { "name": "Default"}, "password":"<type admins password here>",
"name":"admin" } } } } }
<public URL for keystone retrieved at step 2>/auth/tokens>
-H "Content-type: application/json" -H "Content: application/json"
Here you can see an example of the command (on one line):
curl -v -d { "auth": { "identity": { "methods":["password"], "password":
{ "user": { "domain": { "name": "Default"}, "password":"passw0rd", "name":"admin" } } } } }
http://172.17.43.128:5000/v3/auth/tokens -H "Content-type: application/json"
-H "Content: application/json"
and a sample response could be (on one line):
<HTTP/1.1 201 Created < X-Subject-Token: f7445c42833b4d98bdf9486bfa668560
< Vary: X-Auth-Token < Content-Type: application/json < Content-Length: 256
< Date: Tue, 03 Dec 2013 14:13:07 GMT {"token": {"issued_at":
"2013-12-03T14:13:07.647824Z", "extras": {}, "methods": ["password"],
"expires_at": "2013-12-04T14:13:07.647781Z", "user": {"domain":
{"id" : "default", "name": "Default"}, "id": "4c12c2be3d764e66baddee9d56a44b90",
"name": "admin"}}}
4. Then generate the scoped token using the following command (on one line):
curl -v -d { "auth": { "scope": { "project": { "domain":{ "name":"Default" },
"name":"admin" } }, "identity": { "methods":["password"], "password":
{ "user": { " domain": { "name": "Default"},
"password":"<admins password>", "name":"admin" } } } } }
<keystone endpoint retrieved at step 2/auth/tokens>
-H "Content-type:application/json" -H " Content: application/json"
-H "X-Auth-Token":"<token obtained at step 3>"
1108 IBM SmartCloud Orchestrator 2.3: User's Guide
Here you can see an example of the command (on one line):
curl -v -d { "auth": { "scope": { "project": { "domain":{ "name":"Default" },
"name":"admin" } }, "identity": { "methods":["password"], "password":
{ "user": { " domain": { "name": "Default"},
"password":"passw0rd", "name":"admin" } } } } }
http://172.17.43.128:5000/v3/auth/tokens
-H "Content-type: application/json" -H "Content: application/json"
-H "X-Auth-Token":"f7445c42833b4d98bdf9486bfa668560"
A sample response could be (on one line):
< HTTP/1.1 201 Created < X-Subject-Token:
22b333746f824fbfb8bda0c893e10980 < Vary: X-Auth-Token < Content-Type: application/json
< Content-Length:4138 < Date: Tue, 03 Dec 2013 15:58:22 GMT {"token":
{"methods": ["password"], "roles": [{"id":"9fe2ff9ee4384b1894a90878d3e92bab",
"name": "_member_"}, {"id": "389e9e3d054d4726ae8168d76410587a", "name":"KeystoneAdmin"},
{"id": "ab31db52afc14784b0d654e455658389", "name": "KeystoneServiceAdmin"},
{"id": "25916399d2504398b1f731391c0058e5", " name": "admin"}],
"expires_at": "2013-12-04T15:58:22.549466Z", "project": {"domain": {"id": "default",
"name": "Default"}, "id": " d9de5bd29f504be6a3a558fc2c5e6a5c", "name": "admin"},
"catalog": [{"endpoints":
[{"url": "http://172.17.43.128:8776/v1/d9de5bd29f504be6a3a558fc2c5e6a5c",
"region": "RegionOne", "legacy_endpoint_id": "7c4833e69f6643239530518669c3300a",
"interface": "admin", "id":"5614104374d042918622b12292cc7c58"},
{"url" : "http://172.17.43.128:8776/v1/d9de5bd29f504be6a3a558fc2c5e6a5c",
"region": "RegionOne", "legacy_endpoint_id": "7c4833e69f6643239530518669c3300a",
"interface": "internal", "id": "d0e4086bddb940ae88706dd443c235a2"},
{"url": "</i>http://172.17.43.128:8776/v1/d9de5bd29f504be6a3a558fc2c5e6a5c</u></i>",
"region": "RegionOne", "legacy_endpoint_id":
"7c4833e69f6643239530518669c3300a", "interface": "public",
"id": "8d7ce6f4e2da43aeb931603a95f85fae"}], "type": "volume" ,
"id": "e96e8ff119964389b2802742064eb22c"}, {"endpoints":
[{"url": "http://172.17.43.128:35357/v3", "region": "RegionOne",
"legacy_endpoint_id": "3a62f7ec92474c738659a1bb33c4ead5", "interface": "admin",
"id": "01c3f219646a4e60a4985d8d0a7bd513"}, {"url": "<i><u>http://172.17.43.128:5000/v3",
"region": " RegionOne", "legacy_endpoint_id": "3a62f7ec92474c738659a1bb33c4ead5",
"interface": "internal", "id": "40ff14ff4d9e49778b5b540be0ea2e19"},
{"url": "http://172.17.43.128:5000/v3", "region": "RegionOne",
"legacy_endpoint_id": "3a62f7ec92474c738659a1bb33c4ead5", "interface": "public",
"id": "954ff380c683476592484d1bb5b77333"}], "type": "identity",
"id": "786318e637bf4f4db363346fab847a8d"}, {"endpoints":
[{"url": "https://172.17.43.129:9443/ImageLibrary/ImageService/v1", "region": "RegionOne",
"legacy_endpoint_id": "cc8502efb79a42ef83b87682a7bba754", "interface": "admin",
"id": " 1898853973444f44b9c7813595c8fc49"},
{"url": "</i>https://172.17.43.129:9443/ImageLibrary/ImageService/v1",
"region": "RegionOne", "legacy_endpoint_id": " cc8502efb79a42ef83b87682a7bba754",
"interface": "internal", "id": "aeb4bafed253495ebb8c6034bd2e18c4"},
{"url": "https://172.17.43.129:9443/ImageLibrary/ImageService/v1",
"region": "RegionOne", "legacy_endpoint_id": "cc8502efb79a42ef83b87682a7bba754",
"interface": "public", "id": "190c9c1dd6ee482f8143d234c8319799"}], "type": "vil",
"id": "3c243197492d41aa85679c5f8662c67a"}, {"endpoints":
[{"url": "http://172.17.43.128:8774/v2/d9de5bd29f504be6a3a558fc2c5e6a5c",
"region": "RegionOne", "legacy_endpoint_id": "7d344cfcbc9841f988b9ef79c5c87529",
"interface": "admin", "id": " 7a88cd7d88f8457492b2ee3dae2bca9a"},
{"url": "http://172.17.43.128:8774/v2/d9de5bd29f504be6a3a558fc2c5e6a5c",
"region": "RegionOne", " legacy_endpoint_id": "7d344cfcbc9841f988b9ef79c5c87529",
"interface": "internal", "id": "2636dcb5bfe741c1a782ad9f0f524293"},
{"url": "<i><u>http://172.17.43.128:8774/v2/d9de5bd29f504be6a3a558fc2c5e6a5c",
"region": "RegionOne", "legacy_endpoint_id": "7d344cfcbc9841f988b9ef79c5c87529",
"interface": "public", "id": "9c25b416c98c4e3bbfd64311d1d17da7"}], "type": "compute",
"id": "c03ec01b38ba4fd28ecc312a3aa10e77"}, {"endpoints":
[{"url": "http://172.17.43.128:9292/", " region": "RegionOne",
"legacy_endpoint_id": "afbcd2278ccc40febdb1f51db8188d12", "interface": "admin",
"id": "7dcb0ec3ff7b4340988ebe70e248f621"}, {"url": "http://172.17.43.128:9292/",
"region": "RegionOne", "legacy_endpoint_id": "afbcd2278ccc40febdb1f51db8188d12",
"interface": "internal", "id": "9378f84a8c4b48c5ad1b049991e3f989"},
{"url": "http://172.17.43.128:9292/", "region": "RegionOne",
Chapter 12. Troubleshooting 1109
"legacy_endpoint_id": "afbcd2278ccc40febdb1f51db8188d12 ", "interface": "public",
"id": "816e4c75619f4c21866bc5aeb093a30b"}], "type": "image",
"id": "a842a179175b4a3dbc0d8269c7ca257e"}], "extras": {}, "user": {" domain":
{"id": "default", "name""Default"}, "id": "4c12c2be3d764e66baddee9d56a44b90",
"name": "admin"}
5. Reset the image customization running this command for each image got in the
first step:
curl -v -i <URL with interface value "public" got in Step 4
from the endpoint of type "compute">/images/
<image id got from step 1>/customization
-H "X-Auth-Token":"<X-Subject-Token got from step 4>" -X DELETE
Here you can see an example of the command (on one line):
curl -v -i http://172.17.43.128:8774/v2/d9de5bd29f504be6a3a558fc2c5e6a5c/images/
4205ff92-e82b-3645-9252-f1f33d4084ba/customization
-H "X-Auth-Token":"22b333746f824fbfb8bda0c893e10980" -X DELETE
A sample response could be (on one line):
< HTTP/1.1 200 OK
< Content-Length: 0
X-Compute-Request-Id: req-39f115c7-c86f-4d48-862b-3bba5585fd9f
< Content-Type: application/json
< Date: Tue, 03 Dec 2013 16:35:46 GMT
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
You can recognize this case by looking into the deployment history, which it will
end with the message:
Virtual machine could not be registered date/time
In addition, when browsing the Virtual Machines section of the failed instance, you
will notice the name(s) of the virtual machine(s) containing just the first octet of
the IP address instead of the hostname, for example: d_172 (when the IP address of
the machine is like 172.16.*.*).
Causes
This is caused by the missing DNS entry 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 HV tools (vCenter or OpenStack).
Resolving the problem
There are two possible ways to solve this issue:
v The preferred way is to update the DNS configuration, so that it will correctly
resolve the hostname for the given IP address.
v Alternatively, you can change the virtual machine name format property from
the environment profile definition to not use ${hostname} (or remove it
completely).
1110 IBM SmartCloud Orchestrator 2.3: User's Guide
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.
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.
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 doesn't exist,
since nova-manage is not able to use the keystone API to verify the project's
existence.
The OpenStack community has 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 nova-manage, we will not fix this
problem (the community would not like to accept code changes for deprecated
components). In the current SmartCloud Orchestrator release, we can still use the
nova-manage command to manage nova resources.
Chapter 12. Troubleshooting 1111
Security limitations
Check the known security limitations that might expose your SmartCloud
Orchestrator environment to risks.
Keystone does not revoke tokens
Problem
When you log out from Scalable Web Infrastructure, your security token is
not revoked and can be used again without any authentication.
Solution
You can use the following command to delete a security token:
DELETE /tokens/{tokenid}
You must have administrative privileges to run this command.
The deployed VMs are visible to all tenants in Virtual Image
Library
This problem arises when the same admin user that is used to register the
OpenStack repository is used to deploy VMs. The admin user should not be used
to deploy VMs because these VMs will be visible in Virtual Image Library to all
tenants.
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 1123 for detailed
information on this security limitation.
User interface errors
Refer to this topic for information about known errors that may occur when
interacting with the SmartCloud Orchestrator user interface.
CTJCP0027E: An internal error occurred. The requested page cannot be
displayed. Please contact your administrator.
This generic message is displayed when an internal, unspecified error has occurred
in the system. This situation usually requires an action from the system
administrator.
Refer to the SmartCloud Orchestrator log files for detailed information about the
problem that has occurred. You can find the /var/log/scoui.log log files on
Central Server 3.
1112 IBM SmartCloud Orchestrator 2.3: User's Guide
Fixing command-line interface errors when using multi-byte
character sets
If you are working with codecs commonly used for languages with multi-byte
characters, you could see errors. These Jython 2.5.1 errors most commonly occur
while using the SmartCloud Orchestrator command-line interface in interactive
mode. Errors usually occur as LookupErrors indicating that your encoding is
unknown.
Before you begin
If you are using Jython 2.5.1 in a multi-byte character set, you can see a
LookupError error as shown in the following example:
LookupError: unknown encoding gb2312
About this task
If you encounter these errors while using the command-line interface, use the
following steps to correct the problem.
Procedure
1. Identify the lib directory that corresponds to the Workload Deployer
component version in SmartCloud Orchestrator. The deployer.cli/lib
directory contains one subdirectory for each Workload Deployer component
version with which the command-line interface has communicated. You can
determine the Workload Deployer version with the following command:
$ deployer -h <hostname> -u <username>
-p <password> -c deployer.version
2. Choose one of the following options, depending on the intended users:
v To change the codec for all users who run it, edit the registry file in the lib
directory and uncomment the lines indicated in the comments at the top of
the file.
v To change the codec used by the command-line interface for a single user,
copy the registry file to a file named .jython in the home directory of the
use. Then edit the registry file in the lib directory and uncomment the lines
indicated in the comments at the top of the file.
3. Update deployer.console.encoding to specify the correct codec for your
environment.
As examples, the following list includes specific codecs for certain locales:
v Simplified Chinese: deployer.console.encoding=gb2312
v Traditional Chinese: deployer.console.encoding=big5
v Japanese: deployer.console.encoding=shift_jis
v Korean: deployer.console.encoding=ks_c_5601-1987
4. Restart the command-line interface.
Results
You can use the command-line interface without errors.
Chapter 12. Troubleshooting 1113
SmartCloud Entry does not function properly
Check the known problems that might occur with SmartCloud Entry and learn
how to solve them.
The openstack-smartcloud status is "openstack-smartcloud dead
but pid file exists"
Problem
This status means that SmartCloud Entry did not connect to the clouds
that were created by the entry.
Solution
Check the log file: /var/log/nova/smartcloud.log. If you find the
following error messages:
<body><h2>HTTP ERROR 404</h2>
<p>Problem accessing /cloud/api/productInfo/version. Reason:
<pre> ProxyServlet: /cloud/ap/productInfo/version</pre>
wait before you start openstack-smartcloud.
Note: The amount of time you must wait depends on the speed of the
network and the size of the cloud, for example for an average network
with 10 virtual machines, 10 s is enough.
If the problem continues, check vCenter.
Command nova-cloud-create fails with an error
You use the command nova-cloud-create and it fails with the error:
"{"computeFault": {"message": "The server has either erred or is incapable of
performing the requested operation.", "code": 500}}."
This error can relate to two issues:
v The openstack-smartcloud service is not started.
v The os-hostname does not match the host that runs the openstack-smartcloud
service.
You must:
v Validate that the service is started by checking the service openstack-smartcloud
status.
v Validate that the os-hostname matches the host that runs the
openstack-smartcloud service by running the command hostname.
Unable to change the flavor of VMware virtual machines
Attempts to change the flavor of VMware virtual machines by using an OpenStack
fail with an error.
If:
v You try to change the flavor of VMware virtual machines by using an
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.
1114 IBM SmartCloud Orchestrator 2.3: User's Guide
You must also make sure that the virtual machine uses an SCSI disk.
Error message displayed after launching a virtual system
The resource could not be found message may appear when a user from a newly
created tenant tries to start a virtual system.
An example of this situation is when you run the following command to run a VM
from OpenStack:
nova boot --image rhelova --flavor m1.large --nic net-id=e325a701-ab07-4fb9-a7df-621e0eb31c9b test1vm2
and you get the following message: ERROR: The resource could not be found.
(HTTP 404) (Request-ID: req-4d801615-5fb3-49fe-8830-860de3f3f7db)
The reason is that the user is not able to access the network that is defined in the
environment profile.
To solve this issue, you must make sure that the network has the same tenant
associated or set as None so that all tenant users can use it. When a non-admin
user tries to start a virtual system, you must make sure that the network specified
has been associated to the tenant of this non-admin user. For an admin user, the
network could be associated to the same tenant or set as None. Run the following
command to view details of an OpenStack network:
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 | <= This should be None or
| rxtx_base | None | the same tenant as the user.
| 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 |
+---------------------+--------------------------------------+
When you boot a virtual machine from OpenStack with the API or the CLI without
the --nic parameter with an admin user, OpenStack will associate the network
with the tenant of the current user if the tenant of the current user is not
associated to any network. Then this network cannot be used by other tenant user.
Chapter 12. Troubleshooting 1115
If you still want it to be used by another tenant user, you can run the following
command to disassociate the project from the network:
nova-manage network modify 10.10.0.0/16 --disassociate-project
To associated a tenant to a network manually, you can run the command:
nova-manage network modify 10.10.0.0/16 --project $TENANT_ID
where $TENANT_ID is the tenant id of the tenant you want to associate. For example,
it could be 9d9d88a46e5b4022aef64f6b2ed42469.
You can then check whether the network is disassociated from the tenant:
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 | <= This means the nework is
| rxtx_base | None | shared.
| 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 |
+---------------------+--------------------------------------+
Unable to list keystone endpoints on the Region Server
This is a limitation of OpenStack because the keystone version 3 support is not
completed. To support the keystone version 3, the keystone client must use
OS_SERVICE_TOKEN and OS_SERVICE_ENDPOINT .
Symptoms:
The keystone endpoint URLs is empty when running the "keystone
endpoint-list" on the Region Server with the /root/openrc sourced:
[root@power-rs ~]# . openrc
[root@power-rs ~]# keystone endpoint-list
+----------------------------------+-------------+-----------+-------------+----------
| id | region | publicurl | internalurl | adminurl
+----------------------------------+-------------+-----------+-------------+----------
1116 IBM SmartCloud Orchestrator 2.3: User's Guide
| 019e393701f5436480d6ec9552cd0642 | RegionOne | | |
| 08f15c7f3b764af4ad7209404cdd6c05 | RegionOne | | |
| 1c76d4c3cd7e4eb683f92202c1fbceee | RegionOne | | |
| 27e1fac972ec441babbdc95eb61fba84 | PowerRegion | | |
| 4009da63dcf5471e8094a0ae96a01a10 | PowerRegion | | |
| 40846cc21c7f4477b9d123dd06b5b190 | RegionOne | | |
| 62d78649fae94529a8ced0d56d499e02 | PowerRegion | | |
| 6aca4f17e82d42e6b34cdcfb5f59a756 | PowerRegion | | |
| 8203260f686047bb811435078177ad10 | RegionOne | | |
| 84f3a1f0fef140c18655deab113f6f09 | PowerRegion | | |
| 895206c5c7144fcb8c00ca657b8e2bb5 | RegionOne | | |
| 940e895b630b4ff693cd1765c27e0450 | PowerRegion | | |
| 97781db45f6e41d69768220025f37523 | RegionOne | | |
| 9ee159c0da834d60a495641d76c2ee13 | PowerRegion | | |
| a691b7ae28834a96a31c39764fe93af2 | RegionOne | | |
| a752e8a14f914bf5b868faf813aa1c49 | RegionOne | | |
| b0c34598d05945259528391c5430fcb6 | PowerRegion | | |
| b41db8b713ba41c1b45f4172f7231e4e | RegionOne | | |
| b52a97b7c3af42e1bc61a67c5065cd01 | RegionOne | | |
| c0d4ae1fec4a442c84f5f3f14a5191a6 | RegionOne | | |
| d0ad615e0a0745de85ad6f8d137998ce | RegionOne | | |
| d9591717925c42c99bcba0dbc27d264c | RegionOne | | |
| df6f33f4e0144189a413e5385db6f255 | RegionOne | | |
| f78a0b379924491e9e83409deba9c3d3 | PowerRegion | | |
+----------------------------------+-------------+-----------+-------------+----------
+----------------------------------+
| service_id |
+----------------------------------+
| 6c3ba418b10b4c62a195d9aafd1c3412 |
| e6c343c911c844c9b6fb492166e3945a |
| 6c3ba418b10b4c62a195d9aafd1c3412 |
| 6c3ba418b10b4c62a195d9aafd1c3412 |
| be9192ecbe7c4306beebf8efaf2b49b9 |
| 2b84a9bc5c6f4338aba4d638072d5624 |
| 6c3ba418b10b4c62a195d9aafd1c3412 |
| e6c343c911c844c9b6fb492166e3945a |
| e6c343c911c844c9b6fb492166e3945a |
| e6c343c911c844c9b6fb492166e3945a |
| e6c343c911c844c9b6fb492166e3945a |
| be9192ecbe7c4306beebf8efaf2b49b9 |
| 2b84a9bc5c6f4338aba4d638072d5624 |
| be9192ecbe7c4306beebf8efaf2b49b9 |
| 18877e517fdd4643921ceb3b354c928b |
| 18877e517fdd4643921ceb3b354c928b |
| e6c343c911c844c9b6fb492166e3945a |
| be9192ecbe7c4306beebf8efaf2b49b9 |
| 6c3ba418b10b4c62a195d9aafd1c3412 |
| 18877e517fdd4643921ceb3b354c928b |
| be9192ecbe7c4306beebf8efaf2b49b9 |
| 2b84a9bc5c6f4338aba4d638072d5624 |
| be9192ecbe7c4306beebf8efaf2b49b9 |
| 6c3ba418b10b4c62a195d9aafd1c3412 |
+----------------------------------+
Solution:
1. Copy the /root/keystonerc from central-server-2, change the
"OS_REGION_NAME" variable to the corresponding region name.
2. Source the copied keystonerc:
[root@stone-rs ~]# source keystonerc
3. Rerun the "keystone endpoint-list" command.
Chapter 12. Troubleshooting 1117
Unable to log in by using an LDAP user
Refer to this topic if you are unable to log in into SmartCloud Orchestrator by
using 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 editing:
/usr/share/pyshared/keystone/common/ldap/core.py and adding a new
line under the ldap.initialize line:
self.conn.set_option(ldap.OPT_REFERRALS,0)
Must remove hosts that are not eligible for cloud
Hosts that are not eligible for cloud must be removed from OpenStack.
Restriction:
In VMControl environments, IBM SmartCloud Orchestrator supports deployment
against VMControl server pools only, and not against spare hosts that do not
belong to a server pool. SmartCloud Orchestrator automatically creates availability
zones from the server pools, and puts spare hosts in a default availability zone
called nova_smartcloud.
Solution:
If your VMControl environment has server pools and spare hosts, you must
remove the spare hosts in one of the following ways:
v Put the spare hosts in a server pool, as described in the IBM Systems Director
VMControl Installation and User's Guide.
v Disable the spare hosts, as follows:
1. After VMControl registration, run the nova-cloud-create command to
automatically add the cloud provider and all the related resources, including
server pools and hosts, to Virtual Image Library.
2. Run the nova availability-zone-list command to display a list of the
server pools detected.
3. For each server that is listed under the nova_smartcloud availability zone,
identify the host name and service name, as shown in the following example:
# nova availability-zone-list
+------------------------------------+----------------------------------------+
| Name | Status |
+------------------------------------+----------------------------------------+
| internal | available |
1118 IBM SmartCloud Orchestrator 2.3: User's Guide
| |- sco-vmw-16-fb | |
| | |- nova-cert | enabled 2013-10-07T21:54:25.388465 |
| | |- nova-smartcloud | enabled :-)13-10-07T21:54:28.004757 |
| | |- nova-conductor | enabled :-) 2010-07T21:54:08.138195 |
| | |- nova-consoleauth | enabled :-) 2013-07T21:54:25.398669 |
| | |- nova-network | enabled :-) 2013-10-21:54:28.790816 |
| | |- nova-scheduler | enabled :-) 2013-10-07T54:25.392513 |
| | |- nova-console | enabled :-) 2013-10-07T21:26.199419 |
| | |- nova-cells | enabled :-) 2013-10-07T21:54:406953 |
| nova_smartcloud | available |
| |- [email protected] | |
| | |- nova-compute | disabled :-) 2013-10-07T21:54:27.630 |
+------------------------------------+----------------------------------------+
4. For each server that is listed under the nova_smartcloud availability zone,
run the following command to disable that host:
nova-manage service disable --host <host_name> --service <service_name>
For the above example:
nova-manage service disable --host spare_host1 --service nova_compute
Hotplug is not fully supported
SUSE Linux 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.
Unable to capture a NIM-based image in VMControl
When you try to capture a Network Installation Management (NIM)-based image
in VMControl, the operation fails.
Symptoms
If you try to capture the image from the Image Construction and Composition
Tool, the operation fails and the captured image remains in a queued or saving
state in Glance.
If you try to capture the image from the command line, by running the nova
image-create command, no error is displayed. However, the captured image
remains in a queued or saving state in Glance.
In each case, the captured image is not created in VMControl.
This problem applies to the following types of NIM-based configuration:
All NIM
The image to be captured is stored in a NIM image repository, which is
configured as the default image repository for the server pool.
Chapter 12. Troubleshooting 1119
Mixed NIM and SCS
The image to be captured is stored in a NIM image repository, but the
target server pool is configured with a Storage Copy Services (SCS) default
image repository.
Solution
The solution is to create an extended image to be used in SmartCloud Orchestrator.
The method depends on the type of NIM-based configuration.
All NIM
1. Import the base NIM image from the Image Construction and Composition
Tool UI and extend the imported image.
2. In the Image Construction and Composition Tool, synchronize the image.
3. When the image is in a synchronized state, click Virtual System > IP Address,
and note the IP address.
4. In the region server where the image is synchronized, run the nova list
command.
5. In the nova list command output, identify the Server ID that has the same IP
address as noted in step 3.
6. Run the following command:
nova root-password server_ID
where server_ID is the value identified in step 5. Provide the root password of
the base image.
7. To complete the extend operation, capture the image from the Image
Construction and Composition Tool.
Mixed NIM and SCS
Restriction: For a mixed NIM and SCS configuration, the target repository to host
the captured image cannot be selected from OpenStack. Therefore, the image must
be captured from the VMControl UI.
1. Import the base NIM image from the Image Construction and Composition
Tool UI and extend the imported image.
2. In the Image Construction and Composition Tool, synchronize the image.
3. When the image is in a synchronized state, click Virtual System > IP Address,
and note the IP address.
4. In the region server where the image is synchronized, run the nova list
command.
5. In the nova list command output, identify the Server ID that has the same IP
address as noted in step 3.
6. Reset the image that was created by the Image Construction and Composition
Tool, as described in the "Prepare the virtual server to be captured" step at
Installing the VMControl activation engine on AIX and Linux.
7. In the VMControl UI, identify the server name and capture the image
(captured_image_name).
8. Download the OVF file for the captured image, as follows:
a. Run the following command:
wget --no-check-certificate --http-user=VMC_user --http-password=VMC_pwd
-c https://VMControlServer:8422/ibm/director/rest/VMControl/virtualAppliances?name=captured_image_name
1120 IBM SmartCloud Orchestrator 2.3: User's Guide
b. In the file downloaded in the previous step, identify the OID of the image
(image_oid).
c. Run the following command to create the image_oid.ovf file:
wget --no-check-certificate --http-user=VMC_user --http-password=VMC_pwd
-c https://VMControlServer:8422/ibm/director/rest/VMControl/virtualAppliances/image_oid.ovf
9. Edit the image_oid.ovf file to insert the following lines after the
</ovf:ProductSection> tag:
<ovf:ProductSection ovf:class="ConfigSSH" ovf:instance="1"
<ovf:Info>SSH Configuration</ovf:Info>
<ovf:Property ibmExt:invisible="true" ovf:key="username" ovf:type="string"
ovf:userConfigurable="false" ovf:value="" ovf:required="false">
<ovf:Label ovf:msgid="ConfigSSH.username.label">SSH Username</ovf:Label>
<ovf:Description ovf:msgid="ConfigSSH.username.description">
User name for SSH access to the node</ovf:Description>
</ovf:Property>
<ovf:Property ibmExt:invisible="true" ovf:key="ssh_key" ovf:type="string"
ovf:userConfigurable="false" ovf:value="" ovf:required="false">
<ovf:Label ovf:msgid="ConfigSSH.ssh_key.label">SSH Key</ovf:Label>
<ovf:Description ovf:msgid="ConfigSSH.ssh_key.description">
SSH key for access to the node</ovf:Description>
</ovf:Property>
<ovf:Property ibmExt:invisible="true" ovf:key="user_ssh_key" ovf:type="string"
ovf:userConfigurable="false" ovf:value="" ovf:required="false">
<ovf:Label ovf:msgid="ConfigSSH.user_ssh_key.label">SSH public key</ovf:Label>
<ovf:Description ovf:msgid="ConfigSSH.user_ssh_key.description">
Provide your own SSH public key for access to the node</ovf:Description>
</ovf:Property>
</ovf:ProductSection>
<ovf:ProductSection ovf:class="ConfigPWD_ROOT" ovf:instance="1">
<ovf:Info>Root Password Configuration</ovf:Info>
<ovf:Property ibmExt:invisible="true" ovf:key="username" ovf:type="string"
ovf:userConfigurable="false" ovf:value="root" ovf:required="false">
<ovf:Label ovf:msgid="ConfigPWD_ROOT.username.label">Root username</ovf:Label>
<ovf:Description ovf:msgid="ConfigPWD_ROOT.username.description">
This is the username for the root account</ovf:Description>
</ovf:Property>
<ovf:Property ibmExt:invisible="false" ovf:key="password" ovf:password="true"
ovf:type="string" ovf:userConfigurable="true" ovf:value="" ovf:required="true">
<ovf:Label ovf:msgid="ConfigPWD_ROOT.password.label">Administrator Password</ovf:Label>
<ovf:Description ovf:msgid="ConfigPWD_ROOT.password.description">
This is the Administrator password for the system</ovf:Description>
</ovf:Property>
<ovf:Property ibmExt:invisible="true" ovf:key="pwdencrypted" ovf:type="string"
ovf:userConfigurable="false" ovf:value="false" ovf:required="false">
<ovf:Label ovf:msgid="ConfigPWD_ROOT.pwdencrypted.label">Administrator Password encrypted</ovf:Label>
<ovf:Description ovf:msgid="ConfigPWD_ROOT.pwdencrypted.description">
This is the Administrator password for the system</ovf:Description>
</ovf:Property>
</ovf:ProductSection>
10. Save the updated image_oid.ovf file as image_oid_modified.ovf.
11. Put the image_oid_modified.ovf file on VMControl, as follows:
curl -k -X PUT -H "Content-Type: application/ovf+xml" -d image_oid_modified.ovf
-u VMC_user:VMC_pwd
https://VMControlServer:8422/ibm/director/rest/VMControl/virtualAppliances/image_oid
12. Purge the Glance properties of the captured image, as follows:
a. Display the image details:
nova image-list | grep captured_image_name
b. In the output from the previous step, identify the image ID (image_uuid).
c. Display debug information for the image:
nova --debug image-show image_uuid
The debug information includes a curl call, similar to the following call:
REQ: curl -i http://RegionServerIP:8774/v2/97733aff9c10492abc2a671211bdc597/images/
046fa7ce-ff14-45a9-888c-a2907e944823
-X GET
-H "X-Auth-Project-Id: admin"
-H "User-Agent: python-novaclient"
-H "Accept: application/json"
-H "X-Auth-Token: 791f8aed82bc45c4911f8cbe769c8b77"
Chapter 12. Troubleshooting 1121
d. Run a modified version of the curl call. Replace GET with DELETE, and
append /customization after the image_uuid in the URL, as shown in the
following example:
curl -i http://RegionServerIP:8774/v2/97733aff9c10492abc2a671211bdc597/images/
046fa7ce-ff14-45a9-888c-a2907e944823/customization
-X DELETE
-H "X-Auth-Project-Id: admin"
-H "User-Agent: python-novaclient"
-H "Accept: application/json"
-H "X-Auth-Token: 791f8aed82bc45c4911f8cbe769c8b77"
Troubleshooting Workload Deployer
You can troubleshoot problems in Workload Deployer
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).
Troubleshooting virtual applications
Troubleshoot problems for deployed virtual applications. Virtual applications have
common troubleshooting capabilities provided by the IBM Foundation Pattern
type.
About this task
Use the following troubleshooting tasks to help you troubleshoot problems with
virtual application-related problems.
Procedure
Setting runtime trace in the Agent process on page 1123.
1122 IBM SmartCloud Orchestrator 2.3: User's Guide
Setting runtime trace in the Agent process
You can set the runtime trace in the Agent process on the virtual machine by
accessing the deployed virtual application instance in the Virtual Application
Console.
About this task
This setting is available for debugging purposes with the SmartCloud Orchestrator
agent. To set the trace, follow these steps:
Procedure
1. On the user interface, click Instances > Virtual Application Patterns. The
Virtual Application Instances panel displays.
2. Select a virtual_application_instance . The virtual application instance details
display to the right.
3. Click the Manage icon located in the upper right corner. The Virtual Machine
Monitoring panel displays.
4. Click Operation. The Operations panel displays.
5. Select the Agent role from the list operations.
6. Expand Set the trace in the agent process on the virtual machine.
7. In the Trace string that will be applied to the agent field, type the name of the
trace string.
8. Click Submit.
Results
You have enabled run time tracing on all the agents in the deployment.
Deployment stops during middleware setup in VMware
The deployment of a virtual application stops during middleware setup in a
VMware environment.
This happens because the deployed virtual machine's time does not match the time
of the SmartCloud Orchestrator server.
To resolve the problem, synchronize the time of the ESXi servers to the time of the
SmartCloud Orchestrator server (Central Server 3) before deploying the virtual
application.
Troubleshooting Business Process Manager
Refer to this topic for information on known issues or limitations that may occur
when 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.
Chapter 12. Troubleshooting 1123
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 4 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 4 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
The size of the Performance Data Warehouse Database increases
continuously (> 100 GB) when SmartCloud Orchestrator is up
and 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:
"undefined tracking group with external ID 5cde1ff9-d1ab-4a88-8810-b0e7dcbe571e" ...and so forth
Solution:
1. Open the Business Process Manager Process Designer.
2. Open Process Apps or Toolkits, for example:
SCOrchestrator_Support_vSys_Toolkit (SCOVSYS)
.
3. File --> "Update Tracking Definitions".
Troubleshooting Virtual Image Library
For information about troubleshooting Virtual Image Library, see
Troubleshooting on page 330.
1124 IBM SmartCloud Orchestrator 2.3: User's Guide
Troubleshooting Image Construction and Composition Tool
For information about troubleshooting Image Construction and Composition Tool,
see Troubleshooting issues with Image Construction and Composition Tool on
page 466.
Chapter 12. Troubleshooting 1125
1126 IBM SmartCloud Orchestrator 2.3: User's Guide
Notices
This information was developed for products and services offered in the U.S.A.
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
Armonk, NY 10504-1785
U.S.A.
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 Web sites are provided for
convenience only and do not in any manner serve as an endorsement of those Web
sites. The materials at those Web sites are not part of the materials for this IBM
product and use of those Web sites is at your own risk.
Copyright IBM Corp. 2013, 2014 1127
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 information 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.
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.
If you are viewing this information softcopy, the photographs and color
illustrations may not appear.
1128 IBM SmartCloud Orchestrator 2.3: User's Guide
Glossary
This glossary includes terms and definitions for
SmartCloud 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, 2014 1129
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.
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.
1130 IBM SmartCloud Orchestrator 2.3: User's Guide
O
operational repository
A repository for virtual images and
deployed virtual machines that are
managed by a hypervisor.
P
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.
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.
Glossary 1131
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.
reference repository
The local image storage that is used by
the Virtual Image Library component to
store the virtual images.
registry
A repository that contains access and
configuration information for users,
systems, and software.
S
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.
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.
1132 IBM SmartCloud Orchestrator 2.3: User's Guide
V
version chain
A representation of the relationship
among the different versions of a virtual
image depending on the criteria used
when the image is checked in or imported
into the reference repository.
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
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.
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.
Glossary 1133
1134 IBM SmartCloud Orchestrator 2.3: User's Guide
Trademarks and service marks
For trademark attribution, visit the IBM Terms of Use Web site
(http://www.ibm.com/legal/us/).
Copyright IBM Corp. 2013, 2014 1135
1136 IBM SmartCloud Orchestrator 2.3: User's Guide
Privacy policy considerations
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.
Copyright IBM Corp. 2013, 2014 1137
1138 IBM SmartCloud Orchestrator 2.3: User's Guide
Accessibility features for SmartCloud 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 SmartCloud Orchestrator are described in this topic.
Accessibility features
The following list includes the major accessibility features in SmartCloud
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
User documentation is provided in HTML and PDF format. Descriptive text is
provided for all documentation images.
The information center, and its related publications, are accessibility-enabled.
Related accessibility information
You can view the publications for SmartCloud Orchestrator in Adobe Portable
Document Format (PDF) using the Adobe Reader. PDF versions of the
documentation are available in the information 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, 2014 1139
1140 IBM SmartCloud Orchestrator 2.3: User's Guide
Product Number: 5725-H28
Printed in USA
You might also like
- Solution Manual Elementary Classical Analysis Marsden Chap 5 TO80% (6)Solution Manual Elementary Classical Analysis Marsden Chap 5 TO82 pages
- Exam Ref 70-247 - Configuring and Deploying A Private Cloud100% (1)Exam Ref 70-247 - Configuring and Deploying A Private Cloud345 pages
- Installation & Maintenance Guide For Co-Resident Server100% (1)Installation & Maintenance Guide For Co-Resident Server3,226 pages
- IT Service Management - Best Practice - SCCD100% (1)IT Service Management - Best Practice - SCCD802 pages
- Cisco SBA DC UnifiedComputingSystemDeploymentGuideNo ratings yetCisco SBA DC UnifiedComputingSystemDeploymentGuide79 pages
- PlantPAx 4.5 Virtualization User Manual 9528-Um001 - En-P PDFNo ratings yetPlantPAx 4.5 Virtualization User Manual 9528-Um001 - En-P PDF264 pages
- Exam Ref 70-246 - Monitoring and Operating A Private Cloud PDF100% (1)Exam Ref 70-246 - Monitoring and Operating A Private Cloud PDF425 pages
- Hitachi Storage Replication Adapter 2.1: For Vmware® Vcenter Site Recovery Manager™ 5.1/5.5 Deployment GuideNo ratings yetHitachi Storage Replication Adapter 2.1: For Vmware® Vcenter Site Recovery Manager™ 5.1/5.5 Deployment Guide68 pages
- Morpheus Documentation Hpevm Docs Morpheusdata Com en LatestNo ratings yetMorpheus Documentation Hpevm Docs Morpheusdata Com en Latest180 pages
- Apache CloudStack 4.2.0 Admin Guide en USNo ratings yetApache CloudStack 4.2.0 Admin Guide en US143 pages
- In 1040 InstallationForPowerCenterAndDataQuality enNo ratings yetIn 1040 InstallationForPowerCenterAndDataQuality en287 pages
- VMware Cookbook A Real World Guide to Effective VMware Use 1st Edition Ryan Troy all chapter instant downloadNo ratings yetVMware Cookbook A Real World Guide to Effective VMware Use 1st Edition Ryan Troy all chapter instant download90 pages
- Forescout Installation Guide v8.1.x 10-14-2021No ratings yetForescout Installation Guide v8.1.x 10-14-202188 pages
- Compellent Enterprise Manager Administrators GuideNo ratings yetCompellent Enterprise Manager Administrators Guide436 pages
- Matlab Distributed Computing Server DocumentationNo ratings yetMatlab Distributed Computing Server Documentation174 pages
- Network Administrator'S Guide: Autocad 2009No ratings yetNetwork Administrator'S Guide: Autocad 2009102 pages
- Zenoss Resource Manager Installation Guide r6.2.1 d1652.18.248.67No ratings yetZenoss Resource Manager Installation Guide r6.2.1 d1652.18.248.6753 pages
- Dell Compellent Enterprise Manager: 2014 R1 Administrator's GuideNo ratings yetDell Compellent Enterprise Manager: 2014 R1 Administrator's Guide636 pages
- Zenoss Resource Manager Installation GuideNo ratings yetZenoss Resource Manager Installation Guide49 pages
- Deploying Cloud Components On POWER: Front CoverNo ratings yetDeploying Cloud Components On POWER: Front Cover196 pages
- (Ebook) VMware Cookbook: A Real-World Guide to Effective VMware Use by Ryan Troy ISBN 9780596801748, 0596801742download100% (3)(Ebook) VMware Cookbook: A Real-World Guide to Effective VMware Use by Ryan Troy ISBN 9780596801748, 0596801742download55 pages
- Citrix Xenserver ® 6.0 Installation Guide: Published Thursday, 05 September 2013 1.3 EditionNo ratings yetCitrix Xenserver ® 6.0 Installation Guide: Published Thursday, 05 September 2013 1.3 Edition51 pages
- VMware Vsphere Storage Appliance Evaluation GuideNo ratings yetVMware Vsphere Storage Appliance Evaluation Guide46 pages
- Advanced Multiplayer Game Development with Ureal Engine 5: A Comprehensive Guide to C++ ScriptingFrom EverandAdvanced Multiplayer Game Development with Ureal Engine 5: A Comprehensive Guide to C++ ScriptingNo ratings yet
- CNC Machining Handbook: Building, Programming, and ImplementationFrom EverandCNC Machining Handbook: Building, Programming, and ImplementationNo ratings yet
- Cybersecurity for Executives: A Guide to Protecting Your BusinessFrom EverandCybersecurity for Executives: A Guide to Protecting Your BusinessNo ratings yet
- Linux DevOps Tools Engineer (701) Practice Tests: 400 Questions to Ace Your CertificationFrom EverandLinux DevOps Tools Engineer (701) Practice Tests: 400 Questions to Ace Your CertificationNo ratings yet
- VMW 10Q3 PPT Library VMware Icons Diagrams R7 COMM 2 of 2No ratings yetVMW 10Q3 PPT Library VMware Icons Diagrams R7 COMM 2 of 242 pages
- IBM System p5 550 and 550Q: Technical Overview and IntroductionNo ratings yetIBM System p5 550 and 550Q: Technical Overview and Introduction110 pages
- Subject: Registration Procedure With APEDANo ratings yetSubject: Registration Procedure With APEDA9 pages
- Tamilnadu Precision Farming Project 2. Products Part IiNo ratings yetTamilnadu Precision Farming Project 2. Products Part Ii42 pages
- Clicks Entrance Test - Notification - 21.06.2023No ratings yetClicks Entrance Test - Notification - 21.06.20234 pages
- Cloudaffaire Debjeet: Amazon Ecr Public GalleryNo ratings yetCloudaffaire Debjeet: Amazon Ecr Public Gallery7 pages
- Unit: Dynamic Websites Assignment Title: Plastic Pollution Autumn 2019No ratings yetUnit: Dynamic Websites Assignment Title: Plastic Pollution Autumn 20194 pages
- EcoStruxure Power Monitoring Expert 8.2 - PSWSANCZZSPEZZNo ratings yetEcoStruxure Power Monitoring Expert 8.2 - PSWSANCZZSPEZZ2 pages
- Vsphere Esxi Vcenter Server 65 Upgrade GuideNo ratings yetVsphere Esxi Vcenter Server 65 Upgrade Guide298 pages
- Playerunknown'S Battlegrounds (Pubg) Is An: Battlegrounds Was First Released ForNo ratings yetPlayerunknown'S Battlegrounds (Pubg) Is An: Battlegrounds Was First Released For5 pages
