Novell PLATESPIN ORCHESTRATE Developer Guide and Reference
Novell®
www.novell.com
Developer Guide and Reference
PlateSpin® Orchestrate
novdocx (en) 13 May 2009
AUTHORIZED DOCUMENTATION
2.0.2
July 9, 2009
PlateSpin Orchestrate 2.0 Developer Guide and Reference
Legal Notices
Novell, Inc. makes no representations or warranties with respect to the contents or use of this documentation, and
specifically disclaims any express or implied warranties of merchantability or fitness for any particular purpose.
Further, Novell, Inc. reserves the right to revise this publication and to make changes to its content, at any time,
without obligation to notify any person or entity of such revisions or changes.
Further, Novell, Inc. makes no representations or warranties with respect to any software, and specifically disclaims
any express or implied warranties of merchantability or fitness for any particular purpose. Further, Novell, Inc.
reserves the right to make changes to any and all parts of Novell software, at any time, without any obligation to
notify any person or entity of such changes.
Any products or technical information provided under this Agreement may be subject to U.S. export controls and the
trade laws of other countries. You agree to comply with all export control regulations and to obtain any required
licenses or classification to export, re-export or import deliverables. You agree not to export or re-export to entities on
the current U.S. export exclusion lists or to any embargoed or terrorist countries as specified in the U.S. export laws.
You agree to not use deliverables for prohibited nuclear, missile, or chemical biological weaponry end uses. See the
Novell International Trade Services Web page (http://www.novell.com/info/exports/) for more information on
exporting Novell software. Novell assumes no responsibility for your failure to obtain any necessary export
approvals.
novdocx (en) 13 May 2009
Copyright © 2008-2009 Novell, Inc. All rights reserved. No part of this publication may be reproduced, photocopied,
stored on a retrieval system, or transmitted without the express written consent of the publisher.
Novell, Inc. has intellectual property rights relating to technology embodied in the product that is described in this
document. In particular, and without limitation, these intellectual property rights may include one or more of the U.S.
patents listed on the Novell Legal Patents Web page (http://www.novell.com/company/legal/patents/) and one or
more additional patents or pending patent applications in the U.S. and in other countries.
Novell, Inc.
404 Wyman Street, Suite 500
Waltham, MA 02451
U.S.A.
www.novell.com
Online Documentation: To access the latest online documentation for this and other Novell products, see
the Novell Documentation Web page (http://www.novell.com/documentation).
Novell Trademarks
For Novell trademarks, see the Novell Trademark and Service Mark list (http://www.novell.com/company/legal/
trademarks/tmlist.html).
Third-Party Materials
All third-party trademarks are the property of their respective owners.
novdocx (en) 13 May 2009
novdocx (en) 13 May 2009
4 PlateSpin Orchestrate 2.0 Developer Guide and Reference
Contents
About This Guide 11
1 Getting Started With Development 15
1.1 What You Should Know . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
1.1.1 Prerequisite Knowledge. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
1.1.2 Setting Up Your Development Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
1.2 Prerequisites for the Development Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
2 Advanced Job Development Concepts 19
2.1 JDL Job Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
2.1.1 Principles of Job Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
2.2 Understanding TLS Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
2.3 Understanding Job Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
2.3.1 provisionBuildTestResource.job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
2.3.2 Workflow Job Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
novdocx (en) 13 May 2009
3 The PlateSpin Orchestrate Datagrid 25
3.1 Defining the Datagrid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
3.1.1 PlateSpin Orchestrate Datagrid Filepaths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
3.1.2 Distributing Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
3.1.3 Simultaneous Multicasting to Multiple Receivers. . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
3.1.4 PlateSpin Orchestrate Datagrid Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
3.2 Datagrid Communications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
3.2.1 Multicast Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
3.2.2 Grid Performance Factors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
3.2.3 Plan for Datagrid Expansion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
3.3 datagrid.copy Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
4 Using PlateSpin Orchestrate Jobs 31
4.1 Resource Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
4.1.1 Provisioning Jobs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
4.1.2 Resource Discovery Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
4.2 Resource Selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
4.3 Workload Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
4.4 Policy Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
4.5 Auditing and Accounting Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
4.6 BuildTest Job Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
4.6.1 buildTest.policy Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
4.6.2 buildTest.jdl Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
4.6.3 Packaging Job Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
4.6.4 Deploying Packaged Job Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
4.6.5 Running Your Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
4.6.6 Monitoring Job Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
4.6.7 Debugging Jobs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Contents 5
5 Policy Elements 45
5.1 Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
5.2 Facts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
5.3 Computed Facts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
6 Using the PlateSpin Orchestrate Client SDK 47
6.1 SDK Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
6.2 Creating an SDK Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
7 Job Architecture 49
7.1 Understanding JDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
7.2 JDL Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
7.2.1 .sched Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
7.3 Job Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
7.3.1 Job State Transition Events. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
7.3.2 Handling Custom Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
7.4 Job Invocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
7.5 Deploying Jobs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
7.5.1 Using the PlateSpin Orchestrate Development Client . . . . . . . . . . . . . . . . . . . . . . . . 54
7.5.2 Using the zosadmin Command Line Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
7.6 Starting PlateSpin Orchestrate Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
7.7 Working with Facts and Constraints. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
7.7.1 Grid Objects and Facts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
7.7.2 Defining Job Elements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
7.7.3 Job Arguments and Parameter Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
7.8 Using Facts in Job Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
7.8.1 Fact Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
7.8.2 Fact Operations in the Joblet Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
7.8.3 Using the Policy Debugger to View Facts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
7.9 Using Other Grid Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
7.10 Communicating Through Job Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
7.10.1 Sending and Receiving Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
7.10.2 Synchronization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
7.11 Executing Local Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
7.11.1 Output Handling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
7.11.2 Local Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
7.11.3 Safety and Failure Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
7.12 Logging and Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
7.12.1 Creating a Job Memo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
7.12.2 Tracing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
7.13 Improving Job and Joblet Robustness . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
7.14 Using an Event Notification in a Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
7.14.1 Receiving Event Notifications in a Running Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
7.14.2 Event Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
novdocx (en) 13 May 2009
8 Job Scheduling 71
8.1 The PlateSpin Orchestrate Job Scheduler Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
8.2 Schedule and Trigger Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
8.2.1 Schedule File Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
8.2.2 Trigger File XML Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
8.3 Scheduling with Constraints. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
6 PlateSpin Orchestrate 2.0 Developer Guide and Reference
9 Virtual Machine Job Development 77
9.1 VM Job Best Practices. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
9.1.1 Plan Robust Application Starts and Stops . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
9.1.2 Managing VM Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
9.1.3 Managing VM Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
9.1.4 Managing VM Hypervisors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
9.1.5 VM Job Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
9.2 Virtual Machine Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
9.3 VM Life Cycle Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
9.4 Manual Management of a VM Lifecycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
9.4.1 Manually Using the zos Command Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
9.4.2 Automatically Using the Development Client Job Scheduler . . . . . . . . . . . . . . . . . . . 81
9.4.3 Provision Job JDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
9.5 Provisioning Virtual Machines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
9.5.1 Provisioning VMs Using Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
9.5.2 VM Placement Policy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
9.5.3 Provisioning Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
9.6 Automatically Provisioning a VM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
9.7 Defining Values for Grid Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
9.7.1 PlateSpin Orchestrate Grid Objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
9.7.2 Repository Objects and Facts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
9.7.3 VmHost Objects and Facts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
9.7.4 VM Resource Objects and Other Base Resource Facts . . . . . . . . . . . . . . . . . . . . . 101
9.7.5 Physical Resource Objects and Additional Facts . . . . . . . . . . . . . . . . . . . . . . . . . . 108
novdocx (en) 13 May 2009
10 Complete Job Examples 111
10.1 Accessing Job Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
10.2 Installation and Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
10.3 PlateSpin Orchestrate Sample Job Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
10.4 Parallel Computing Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
demoIterator.job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
quickie.job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
10.5 General Purpose Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
dgtest.job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
failover.job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
instclients.job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
notepad.job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
sweeper.job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
whoami.job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
10.6 Miscellaneous Code-Only Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
factJunction.job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
jobargs.job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
A PlateSpin Orchestrate Client SDK 187
A.1 Constraint Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
A.1.1 AndConstraint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
A.1.2 BetweenConstraint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
A.1.3 BinaryConstraint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
A.1.4 Constraint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
A.1.5 ContainerConstraint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
A.1.6 ContainsConstraint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
A.1.7 DefinedConstraint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
A.1.8 EqConstraint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
A.1.9 GeConstraint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
Contents 7
A.1.10 GtConstraint. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
A.1.11 IfConstraint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
A.1.12 LeConstraint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
A.1.13 LtConstraint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
A.1.14 NeConstraint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
A.1.15 NotConstraint. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
A.1.16 OperatorConstraint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
A.1.17 OrConstraint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
A.1.18 TypedConstraint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
A.1.19 UndefinedConstraint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
A.1.20 ConstraintException. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
A.2 Datagrid Package. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
A.2.1 GridFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
A.2.2 GridFileFilter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
A.2.3 GridFileNameFilter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
A.2.4 DGLogger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
A.2.5 DataGridException. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
A.2.6 DataGridNotAvailableException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
A.2.7 GridFile.CancelException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
A.3 Grid Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
A.3.1 AgentListener. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
A.3.2 ClientAgent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
A.3.3 Credential . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
A.3.4 Fact . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
A.3.5 FactSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
A.3.6 GridObjectInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
A.3.7 ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
A.3.8 JobInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
A.3.9 Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
A.3.10 Message.Ack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
A.3.11 Message.AuthFailure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
A.3.12 Message.ClientResponseMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
A.3.13 Message.ConnectionID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
A.3.14 Message.Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
A.3.15 Message.GetGridObjects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
A.3.16 Message.GridObjects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
A.3.17 Message.JobAccepted . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
A.3.18 Message.JobError . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
A.3.19 Message.JobFinished . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
A.3.20 Message.JobIdEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
A.3.21 Message.JobInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
A.3.22 Message.Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
A.3.23 Message.JobStarted . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
A.3.24 Message.JobStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
A.3.25 Message.LoginFailed. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
A.3.26 Message.LoginSuccess. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
A.3.27 Message.LogoutAck . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
A.3.28 Message.RunningJobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
A.3.29 Message.ServerStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
A.3.30 Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
A.3.31 Priority . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
A.3.32 WorkflowInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
A.3.33 ClientOutOfDateException. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
A.3.34 FactException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
A.3.35 GridAuthenticationException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
A.3.36 GridAuthorizationException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
A.3.37 GridConfigurationException. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
A.3.38 GridDeploymentException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
novdocx (en) 13 May 2009
8 PlateSpin Orchestrate 2.0 Developer Guide and Reference
A.3.39 GridException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
A.3.40 GridObjectNotFoundException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
A.4 TLS Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
A.4.1 TlsCallbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
A.4.2 PemCertificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
A.4.3 TlsConfiguration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
A.5 Toolkit Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
A.5.1 ClientAgentFactory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
A.5.2 ConstraintFactory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
A.5.3 CredentialFactory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
B PlateSpin Orchestrate Job Classes and JDL Syntax 201
B.1 Job Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
B.2 Joblet Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
B.3 Utility Classes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
B.4 Built-in JDL Functions and Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
B.4.1 getMatrix() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
B.4.2 system(cmd) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
B.4.3 Grid Object TYPE_* Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
B.4.4 The __agent__ Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
B.4.5 The __jobname__ Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
B.4.6 The __mode__ Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
B.5 Job State Field Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
B.6 Repository Information String Values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
B.7 Joblet State Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
B.8 Resource Information Values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
B.9 JDL Class Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
AndConstraint() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
BinaryConstraint. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
BuildSpec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
CharRange. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
ComputedFact . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
ComputedFactContext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
Constraint. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
ContainerConstraint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
ContainsConstraint. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
DataGrid. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
DefinedConstraint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
EqConstraint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
Exec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
ExecError . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
FileRange. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
GeConstraint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
GridObjectInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
GroupInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
GtConstraint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
JobInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
Joblet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
JobletInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
JobletParameterSpace. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
LeConstraint. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
LtConstraint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
MatchContext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
MatchResult . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
MatrixInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
novdocx (en) 13 May 2009
Contents 9
MigrateSpec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
NeConstraint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
NotConstraint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
OrConstraint. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
ParameterSpace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
PolicyInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
ProvisionSpec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
RepositoryInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
ResourceInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
RunJobSpec. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
ScheduleSpec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
Timer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
UndefinedConstraint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
UserInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
VMHostInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
VmSpec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
C Understanding Resource Metrics Facts 253
C.1 Resource Facts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
C.2 Interpreting the Units of Metrics Fact Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
novdocx (en) 13 May 2009
D Documentation Updates 257
D.1 July 9, 2009 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
D.2 June 17, 2009 (2.0.2 Release). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
10 PlateSpin Orchestrate 2.0 Developer Guide and Reference
About This Guide
novdocx (en) 13 May 2009
This Job Developer Guide and Reference is a component of the documentation library for
PlateSpin
and networking tools to manage complex virtual machines and high performance computing
resources in a datacenter, this guide explains how to develop grid application jobs and polices that
form the basis of PlateSpin Orchestrate functionality. This guide provides developer information to
create and run custom PlateSpin Orchestrate jobs. It also helps provides the basis to build, debug,
and maintain policies using PlateSpin Orchestrate.
This guide contains the following sections:
Chapter 1, “Getting Started With Development,” on page 15
Chapter 2, “Advanced Job Development Concepts,” on page 19
Chapter 3, “The PlateSpin Orchestrate Datagrid,” on page 25
Chapter 4, “Using PlateSpin Orchestrate Jobs,” on page 31
Chapter 5, “Policy Elements,” on page 45
Chapter 6, “Using the PlateSpin Orchestrate Client SDK,” on page 47
Chapter 7, “Job Architecture,” on page 49
Chapter 8, “Job Scheduling,” on page 71
Chapter 9, “Virtual Machine Job Development,” on page 77
Chapter 10, “Complete Job Examples,” on page 111
Appendix A, “PlateSpin Orchestrate Client SDK,” on page 187
®
Orchestrate from Novell®. While PlateSpin Orchestrate provides the broad framework
Appendix B, “PlateSpin Orchestrate Job Classes and JDL Syntax,” on page 201
Appendix C, “Understanding Resource Metrics Facts,” on page 253
Appendix D, “Documentation Updates,” on page 257
Audience
The developer has control of a self-contained development system where he or she creates jobs and
policies and tests them in a laboratory environment. When the jobs are tested and proven to function
as intended, the developer delivers them to the PlateSpin Orchestrate administrator.
Prerequisite Skills
As data center managers or IT or operations administrators, it is assumed that users of the product
have the following background:
General understanding of network operating environments and systems architecture.
Knowledge of basic Linux* shell commands and text editors.
Documentation Updates
For the most recent version of this Job Developer Guide and Reference, visit the PlateSpin
Orchestrate 2.0 Web site (http://www.novell.com/documentation/pso_orchestrate20/).
About This Guide 11
Additional Product Documentation
In addition to this Job Developer Guide and Reference, PlateSpin Orchestrate 2.0 includes the
following additional guides that contain valuable information about the product:
PlateSpin Orchestrate 2.0 Getting Started Reference
PlateSpin Orchestrate 2.0 Upgrade Guide
PlateSpin Orchestrate 2.0 High Availability Configuration Guide
PlateSpin Orchestrate 2.0 Administrator Reference
PlateSpin Orchestrate 2.0 VM Client Guide and Reference
PlateSpin Orchestrate 2.0 Virtual Machine Management Guide
PlateSpin Orchestrate 2.0 Development Client Reference
PlateSpin Orchestrate 2.0 Command Line Reference
PlateSpin Orchestrate 2.0 Server Portal Reference
Documentation Conventions
novdocx (en) 13 May 2009
In Novell documentation, a greater-than symbol (>) is used to separate actions within a step and
items in a cross-reference path.
A trademark symbol (®, TM, etc.) denotes a Novell trademark. An asterisk (*) denotes a third-party
trademark.
When a single pathname can be written with a backslash for some platforms or a forward slash for
other platforms, the pathname is presented with a backslash. Users of platforms that require a
forward slash, such as Linux or UNIX, should use forward slashes as required by your software.
Other typographical conventions used in this guide include the following:
Convention Description
Italics Indicates variables, new terms and concepts, and book titles. For example, a job is
a piece of work that describes how an application can be run in Grid Management
on multiple computers.
Boldface Used for advisory terms such as Note, Tip, Important, Caution, and Warning.
Keycaps Used to indicate keys on the keyboard that you press to implement an action. If
you must press two or more keys simultaneously, keycaps are joined with a
hyphen. For example,
Ctrl-C. Indicates that you must press two or more keys to implement an action.
Simultaneous keystrokes (in which you press down the first key while you type the
second character) are joined with a hyphen; for example, press Stop-a.
Consecutive keystrokes (in which you press down the first key, then type the
second character) are joined with a plus sign; for example, press F4+q.
12 PlateSpin Orchestrate 2.0 Developer Guide and Reference
Convention Description
Fixed-width Used to indicate various types of items. These include:
Commands that you enter directly, code examples, user type-ins in body text, and
options. For example,
cd mydir
System.out.println("Hello World");
Enter abc123 in the Password box, then click Next.
-keep option
Jobs and policy keywords and identifiers. For example,
<run>
</run>
File and directory names. For example,
/usr/local/bin
novdocx (en) 13 May 2009
Note: UNIX path names are used throughout and are indicated with a forward
slash (/). If you are using the Windows platform, substitute backslashes (\) for the
forward slashes (/).
Fixed-width italic
and
<Fixed-width italic>
Indicates variables in commands and code. For example,
zos login <servername> [--user=] [--passwd=] [--port=]
Note: Angle brackets (< >) are used to indicate variables in directory paths and
command options.
| (pipe) Used as a separator in menu commands that you select in a graphical user
interface (GUI), and to separate choices in a syntax line. For example,
File|New
{a|b|c}
[a|b|c]
{ } (braces) Indicates a set of required choices in a syntax line. For example,
{a|b|c}
means you must choose a, b, or c.
[ ] (brackets) Indicates optional items in a syntax line. For example,
[a|b|c]
means you can choose a, b, c, or nothing.
< > (angle brackets) Used for XML content elements and tags, and to indicate variables in directory
paths and command options. For example,
<template>
<DIR>
-class <class>
About This Guide 13
Convention Description
novdocx (en) 13 May 2009
. . . (horizontal
ellipses)
plain text Used for URLs, generic references to objects, and all items that do not require
ALL CAPS Used for SQL statements and HTML elements. For example,
lowercase Used for XML elements. For example,
PlateSpin
Orchestrate Server
root directory
Used to indicate that portions of a code example have been omitted to simplify the
discussion, and to indicate that an argument can be repeated several times in a
command line. For example,
zosadmin [options|optfile.xmlc ...] docfile
special typography. For example,
http://www.novell.com/documentation/index.html
The presentation object is in the presentation layer.
CREATE statement
<INPUT>
<onevent>
Note: XML is case-sensitive. If an existing XML element uses mixed-case or
uppercase, it is shown in that case. Otherwise, XML elements are in lowercase.
Where the PlateSpin Orchestrate Server is installed. The PlateSpin Orchestrate
executables and libraries are in a directory. This directory is referred to as the
PlateSpin Orchestrate Server root directory or <PlateSpin Orchestrate
Server_root>.
Paths UNIX path names are used throughout and are indicated with a forward slash (/). If
you are using the Windows platform, substitute backslashes (\) for the forward
slashes (/). For example,
UNIX: /usr/local/bin
Windows: \usr\local\bin
URLs URLs are indicated in plain text and are generally fully qualified. For example,
http://www.novell.com/documentation/index.html
Screen shots Most screen shots reflect the Microsoft Windows look and feel.
Feedback
We want to hear your comments and suggestions about this manual and the other documentation
included with this product. Please use the User Comments feature at the bottom of each page of the
online documentation, or go to www.novell.com/documentation/feedback.html (http://
www.novell.com/documentation/feedback.html) and enter your comments there.
Novell Support
Novell offers a support program designed to assist with technical support and consulting needs. The
Novell support team can help with installing and using the Novell product, developing and
debugging code, maintaining the deployed applications, providing onsite consulting services, and
delivering enterprise-level support.
14 PlateSpin Orchestrate 2.0 Developer Guide and Reference
1
Getting Started With Development
This Developer Guide for PlateSpin® Orchestrate from Novell® is intended for individuals acting as
PlateSpin Orchestrate job developers. This document discusses the tools and technology required to
create discrete programming scripts—called “jobs”—that control nearly every aspect of the
PlateSpin Orchestrate product.The guide also explains how to create, debug, and maintain policies
that can be associated with jobs running on the PlateSpin Orchestrate Server.
As a job developer, you need your own self-contained, standalone system with full access to your
network environment. As a job developer, you might eventually assume all system roles: job creator,
job deployer, system administrator, tester, etc. For more information about jobs, see “Jobs” in the
PlateSpin Orchestrate 2.0 Getting Started Reference.
This section includes the following information:
Section 1.1, “What You Should Know,” on page 15
Section 1.2, “Prerequisites for the Development Environment,” on page 16
novdocx (en) 13 May 2009
1
1.1 What You Should Know
This section includes the following information:
Section 1.1.1, “Prerequisite Knowledge,” on page 15
Section 1.1.2, “Setting Up Your Development Environment,” on page 16
1.1.1 Prerequisite Knowledge
This guide assumes you have the following background:
Sound understanding of networks, operating environments, and system architectures.
Familiarity with the Python development language. For more information, see the following
online references:
Python Development Environment (PyDEV): The PyDEV plug-in (http://
pydev.sourceforge.net/) enables developers to use Eclipse* for Python and Jython
development. The plug-in makes Eclipse a more robust Python IDE and comes with tools
for code completion, syntax highlighting, syntax analysis, refactoring, debugging, etc.
Python Reference Manual: This reference (http://python.org/doc/2.1/ref/ref.html)
describes the exact syntax and semantics but does not describe the Python Library
Reference, (http://python.org/doc/2.1/lib/lib.html) which is distributed with the language
and assists in development.
Python Tutorial: This online tutorial (http://python.org/doc/2.1/ref/ref.html)helps
developers get started with Python.
Sound understanding of the PlateSpin Orchestrate Job Development Language (JDL).
JDL incorporates compact Python scripts to create job definitions to manage nearly every
aspect of the PlateSpin Orchestrate grid. For more information, see Appendix B, “PlateSpin
Orchestrate Job Classes and JDL Syntax,” on page 201.
Knowledge of basic UNIX shell commands or the Windows command prompt, and text editors.
Getting Started With Development
15
An understanding of parallel computing and how applications are run on PlateSpin Orchestrate
infrastructure.
Familiarity with on-line PlateSpin Orchestrate API Javadoc as you build custom client
applications. For more information see Appendix A, “PlateSpin Orchestrate Client SDK,” on
page 187.
Developer must assume both PlateSpin Orchestrate administrative and end-user roles while
testing and debugging jobs.
1.1.2 Setting Up Your Development Environment
To set up a development environment for creating, deploying, and testing jobs, we recommend the
following procedure:
1 Initially set up a simple, easy-to-manage server, agent, and client on a single machine. Even on
a single machine, you can simulate multiple servers by starting extra agents (see “Installing the
Orchestrate Agent Only” in the PlateSpin Orchestrate 2.0 Installation and Configuration
Guide.
2 As you get closer to a production environment, your setup might evolve to handle more
complex system demands, such as any of the following:
An Orchestrate Server instance deployed on one computer.
An Orchestrate Agent installed on every managed server.
novdocx (en) 13 May 2009
An Orchestrate Development Client installed on your desktop machine.
From your desktop machine, you can build jobs/policies, and then remotely deploy them
using zosadmin command line tool. You can then remotely modify the jobs and other grid
object through the PlateSpin Orchestrate Development Client.
3 Use a version control system, such as Subversion*, to organize and track development changes.
4 Put the job version number inside the deployed file. This will help you keep your job versions
organized.
5 Create make or Ant scripts for bundling and deploying your jobs.
By leveraging the flexibility of the PlateSpin Orchestrate environment, you should not have to write
jobs targeted specifically for one hypervisor technology (Xen*, VMware*, etc.).
1.2 Prerequisites for the Development Environment
Install the Java* Development Kit (https://sdlc3d.sun.com/ECom/
EComActionServlet;jsessionid=DCA955A842E56492B469230CC680B2E1), version 1.5 or
later, to create jobs and to compile a Java SDK client in the PlateSpin Orchestrate environment.
The PlateSpin Orchestrate installer ships with a Java Runtime Environment (JRE) suitable for
running PlateSpin Orchestrate jobs.
Components to write Python-based Job Description Language (JDL) scripts:
Eclipse version 3.2.1 or later. (http://www.eclipse.org/).
16 PlateSpin Orchestrate 2.0 Developer Guide and Reference
Development Environment: Set up your environment according to the guidelines outlined in
“Planning the Orchestrate Server Installation” in the PlateSpin Orchestrate 2.0 Installation and
Configuration Guide. In general, the installed PlateSpin Orchestrate Server requires 2
(minimum for 100 or fewer managed resources) to 4 gigabytes (recommended for more than
100 managed resources) of RAM.
Network Capabilities: For Virtual Machine Management, you need a high-speed Gigabit
Ethernet. For more information about network requirements, see “Orchestrate VM Client” and
“VM Hosts” in the PlateSpin Orchestrate 2.0 Installation and Configuration Guide.
Initial Configuration: After you install and configure PlateSpin Orchestrate, start in the agent
and user auto registration mode as described in “First Use of Basic PlateSpin Orchestrate
Components” in the PlateSpin Orchestrate 2.0 Installation and Configuration Guide. As a
first-time connection, the server creates an account for you as you set up a self-contained
system.
IMPORTANT: Because auto registration mode does not provide high security, make sure you
prevent unauthorized access to your network from your work station during development. As
you migrate to a production environment, make sure that this mode is deactivated.
novdocx (en) 13 May 2009
Getting Started With Development 17
novdocx (en) 13 May 2009
18 PlateSpin Orchestrate 2.0 Developer Guide and Reference
2
Advanced Job Development
novdocx (en) 13 May 2009
Concepts
This section provides advanced conceptual information to help you create your own PlateSpin®
Orchestrate jobs:
Section 2.1, “JDL Job Scripts,” on page 19
Section 2.2, “Understanding TLS Encryption,” on page 21
Section 2.3, “Understanding Job Examples,” on page 21
2.1 JDL Job Scripts
The PlateSpin Orchestrate job definition language (JDL) is an extended and embedded
implementation of Python. The PlateSpin Orchestrate system provides additional constructs to
control and access the following:
Interaction with the infrastructure under management (requesting resources, querying load,
etc.)
Distributed variable space with job, user and system-wide scoping
Extensible event callbacks mechanism
Job logging
2
Datagrid for efficient movement of files across the infrastructure.
Automatic distribution of parallel operations
Failover logic
For more information about the PlateSpin Orchestrate JDL script editor, see Section 7.2, “JDL
Package,” on page 50.
The JDL language allows for the scripted construction of logic that can be modified by external
parameters and constraints (through one or more associated policies) at the time the job instance is
executed. Development of a job with the JDL (Python) language is very straightforward. For a
listing of the job, joblet, and utility classes, see Appendix B, “PlateSpin Orchestrate Job Classes and
JDL Syntax,” on page 201.
A simple “hello world” Python script example that runs a given number of times (numTests) in
parallel (subject to resource availability and policy) is shown below:
class exampleJob(Job):
def job_started_event(self):
print 'Hello world started: got job_started_event'
# Launch the joblets
numJoblets = self.getFact("jobargs.numTests")
pspace = ParameterSpace()
i = 1
while i <= numJoblets:
pspace.appendRow({'name':'test'+str(i)})
i += 1
Advanced Job Development Concepts
19
self.schedule(exampleJoblet, pspace, {})
class exampleJoblet(Joblet):
def joblet_started_event(self):
print "Hello from resource%s" % self.getFact("resource.id")
This example script contains two sections:
The class that extends the job and runs on the server.
The class that extends the joblet that will run on any resource employed by this job.
Because the resources are not requested explicitly, they are allocated based on the resource
constraints associated with this job. If none are specified, all resources match. The
exampleJoblet
class would typically execute some process or test based on unique parameters.
2.1.1 Principles of Job Operation
Whenever a job is run on the PlateSpin Orchestrate system it undergoes state transition, as illustrated
in Figure 2-1 on page 20. In all, there are 11 states. The following four states are important in
understanding how constraints are applied on a job’s life cycle through policies:
novdocx (en) 13 May 2009
Accept: Used to prevent work from starting; enforces a hard quota on the jobs.
Start: Used to queue up work requests; limits the quantity of jobs or the load on a resource.
Resource: Used to select specific resources.
Stop: Used to abort jobs; provides special timeout or overrun conditions.
Figure 2-1 Constraint-Based Job State Transition
For more information about job life cycle, see Section 7.3.1, “Job State Transition Events,” on
page 51.
20 PlateSpin Orchestrate 2.0 Developer Guide and Reference
2.2 Understanding TLS Encryption
Understanding Transport Layer Security (TLS) encryption is particularly important if you reinstall
the server and have an old server certificate in either your agent or client user profile similar to
shared keys. If you have an old certificate, you need to either manually replace it or delete it and
allow the client or agent to download the new one from the server using one of the following
procedures:
ssh
novdocx (en) 13 May 2009
For the Agent: The TLS certificate is in
<agentdir>/tls/server.pem
. Deleting this
certificate will cause the agent, by default, to log a minor warning message and download a
new one the next time it tries to connect to the server. This is technically not secure, since the
server could be an impersonator. If security is required for this small window of time, then the
real server’s
<serverdir>/<instancedir>/tls/cert.pem
can be copied to the above
server.pem file.
For the Client: The easiest way to update the certificate from the command line tools is to
simply answer “yes” both times when prompted about the out-of date certificate. This is, again,
not 100% secure, but is suitable for most situations. For absolute security, hand copy the
server’s cert.pem (see above) to
For Java SDK clients: Follow the manual copy technique above to replace the certificate. If
the local network is fairly trustworthy, you can also delete the above
~/.novell/zos/client/tls/<serverIPAddr:Port>.pem
~/.novell/.../*.pem
files, which will cause the client to auto-download a new certificate.
2.3 Understanding Job Examples
The following simple examples demonstrate how you can use JDL scripting to manage specific
functionality:
Section 2.3.1, “provisionBuildTestResource.job,” on page 21
Section 2.3.2, “Workflow Job Example,” on page 23
To learn about other job examples that are packaged with PlateSpin Orchestrate, see Chapter 10,
“Complete Job Examples,” on page 111.
.
2.3.1 provisionBuildTestResource.job
The following job example illustrates simple scripting to ensure that each of three desired OS
platforms might be available in the grid and, if not, it tries to provision them (provided that a VM
image matching the OS type exists). The resource Constraint object is created programmatically, so
there is no need for external policies.
1 class provisionBuildTestResource(Job):
2
3 def job_started_event(self):
4 oslist = ["Windows XP", "Windows 2000", "Windows 2003 Server"]
5 for os in oslist:
6 constraint = EqConstraint()
7 constraint.setFact("resource.os.name")
8 constraint.setValue(os)
9 resources = getMatrix().getGridObjects("resource",constraint)
10 if len(resources) == 0:
11 print "No resources were found to match constraint. \
12 os:%s" % (os)
Advanced Job Development Concepts 21
13 else:
14 #
15 # Find an offline vm instance or template.
16 #
17 instance = None
18 for resource in resources:
19 if resource.getFact("resource.type") != "Fixed Physical"
and \
20 resource.getFact("resource.online") == False:
21 # Found a vm or template. provision it for job.
22 print "Submitting provisioning request for vm %s." %
(resource)
23 instance = resource.provision()
24 print "Provisioning successfully submitted."
25 break
26 if instance == None:
27 print "No offline vms or templates found for os: %s" %
(os)
It is not necessary to always script resource provisioning. Automatic resource provisioning (“on
demand”) is one of the built-in functions of the Orchestrate Server. For example, a job requiring a
Windows 2003 Server resource that cannot be satisfied with online resources only needs to have the
appropriate facts set in the Orchestrate Development Client; that is,
job.provision.maxcount
is
enabled.
novdocx (en) 13 May 2009
This fact could also be set through association with a policy. If it is set up this way, PlateSpin
Orchestrate detects that a job is in need of a resource and automatically takes the necessary
provisioning steps, including reservation of the provisioned resource.
All provisioned virtual machines and the status of the various hosts are visible in the following view
of the Orchestrate Development Client.
Figure 2-2 The PlateSpin Orchestrate Development Client Showing Virtual Machine Management
22 PlateSpin Orchestrate 2.0 Developer Guide and Reference
2.3.2 Workflow Job Example
This brief example illustrates a job that does not require resources but simply acts as a coordinator
(workflow) for the buildTest and provision jobs discussed in Section 4.6, “BuildTest Job Examples,”
on page 35.
1 class Workflow(Job):
2 def job_started_event(self):
3 self.runJob("provisionBuildTestResource", {})
4 self.runJob("buildTest", { "testlist" : "/QA/testlists/production",
5 "buildId": "2006-updateQ1" } )
The job starts in line 1 with the job_started_event, which initiates provisionBuildTestResource.job
(page 21) to ensure all the necessary resources are available, and then starts the buildTest.jdl
Example (page 37). This workflow job does not complete until the two subjobs are complete, as
defined in lines 3 and 4.
If so desired, this workflow could monitor the progress of subjobs by simply defining new event
handler methods (by convention, using the
_event
events. Every message received by the job executes the corresponding event handler method and can
also contain a payload (a Python dictionary).
suffix). The system defines many standard
novdocx (en) 13 May 2009
Advanced Job Development Concepts 23
novdocx (en) 13 May 2009
24 PlateSpin Orchestrate 2.0 Developer Guide and Reference
3
The PlateSpin Orchestrate
novdocx (en) 13 May 2009
Datagrid
This section explains concepts related to the datagrid of the PlateSpin® Orchestrate Server datagrid
and specifies many of the objects and facts that are managed in the grid environment:
Section 3.1, “Defining the Datagrid,” on page 25
Section 3.2, “Datagrid Communications,” on page 27
Section 3.3, “datagrid.copy Example,” on page 29
3.1 Defining the Datagrid
Within the PlateSpin Orchestrate environment, the datagrid has three primary functions:
Section 3.1.1, “PlateSpin Orchestrate Datagrid Filepaths,” on page 25
Section 3.1.2, “Distributing Files,” on page 26
Section 3.1.3, “Simultaneous Multicasting to Multiple Receivers,” on page 26
3.1.1 PlateSpin Orchestrate Datagrid Filepaths
The PlateSpin Orchestrate datagrid provides a file naming convention that is used in JDL code and
by the PlateSpin Orchestrate CLI for accessing files in the datagrid. The naming convention is in the
form of a URL. For more information, see “Jobs”in the PlateSpin Orchestrate 2.0 Administrator
Reference.
3
The datagrid defines the root of the namespace as
illustrated in the figure below:
Figure 3-1 File Structure of Data Nodes in a Datagrid
grid://
, with further divisions under the root as
The PlateSpin Orchestrate Datagrid
25
novdocx (en) 13 May 2009
The grid URL naming convention is the form
grid://<gridID>/<file path>
. Including the
gridID is optional and its absence means the host default grid. When writing jobs and configuring a
datagrid, you can use the symbol ^ as a shortcut to the <jobid> directory either standalone,
indicating the current job, or followed by the jobid number to identify a particular job.Likewise, the
symbol ! can be used as a shortcut to the deployed jobs’ home directory either standalone, indicating
the current jobs’ type, or followed by the deployed jobs’ name. The symbol ~ is also a shortcut to the
user’s home directory in the datagrid, either by itself, indicating the current user, or followed by the
desired user ID to identify a particular user.
zos
The following examples show address locations in the datagrid using the
These examples assume you have logged in using
zos login
to the Orchestrate Server you are
command line tool.
using:
“Directory Listing of the Datagrid Root Example” on page 26
“Directory Listing of the Jobs Subdirectory Example” on page 26
Directory Listing of the Datagrid Root Example
$ zos dir grid:///
<DIR> Jun-26-2007 9:42 installs
<DIR> Jun-26-2007 9:42 jobs
<DIR> Jun-26-2007 14:26 users
<DIR> Jun-26-2007 9:42 vms
<DIR> Jun-26-2007 10:09 warehouse
Directory Listing of the Jobs Subdirectory Example
$ zos dir grid:///jobs
<DIR> Jun-26-2007 9:42 cpuInfo
<DIR> Jun-26-2007 9:42 findApps
<DIR> Jun-26-2007 9:42 osInfo
<DIR> Jun-26-2007 9:42 vcenter
<DIR> Jun-26-2007 9:42 vmHostVncConfig
<DIR> Jun-26-2007 9:42 vmprep
<DIR> Jun-26-2007 9:42 vmserver
<DIR> Jun-26-2007 9:42 vmserverDiscovery
<DIR> Jun-26-2007 9:42 xen30
<DIR> Jun-26-2007 9:42 xenDiscovery
<DIR> Jun-26-2007 9:42 xenVerifier
3.1.2 Distributing Files
The PlateSpin Orchestrate datagrid provides a way to distribute files in the absence of a distributed
file system. This is an integrated service of PlateSpin Orchestrate that performs system-wide file
delivery and management.
3.1.3 Simultaneous Multicasting to Multiple Receivers
The datagrid provides a multicast distribution mechanism that can efficiently distribute large files
simultaneously to multiple receivers. This is useful even when a distributed file system is present.
For more information, see Section 3.2, “Datagrid Communications,” on page 27.
26 PlateSpin Orchestrate 2.0 Developer Guide and Reference
3.1.4 PlateSpin Orchestrate Datagrid Commands
The following datagrid commands can be used when creating job files. To see where these
commands are applied in the PlateSpin Orchestrate Development Client, see “Typical Use of the
Grid”.
Command Description
novdocx (en) 13 May 2009
cat
copy
delete
dir
head
log
mkdir
move
tail
Displays the contents of a datagrid file.
Copies files and directories to and from the datagrid.
Deletes files and directories in the datagrid.
Lists files and directories in the datagrid.
Displays the first of a datagrid file.
Displays the log for the specified job.
Makes a new directory in the datagrid.
Moves files and directories in the datagrid.
Displays the end of a datagrid file.
3.2 Datagrid Communications
There is no set limit to the number of receivers (nodes) that can participate in the datagrid or in a
multicast operation. Indeed, multicast is rarely more efficient when the number of receivers is small.
Any type of file or file hierarchy can be distributed via the datagrid.
The datagrid uses both a TCP/IP and IP multicast protocols for file transfer. Unicast transfers (the
default) are reliable because of the use of the reliable TCP protocol. Unicast file transfers use the
same server/node communication socket that is used for other job coordination datagrid packets are
simply wrapped in a generic DataGrid message. Multicast transfers use the persistent socket
connection to setup a new multicast port for each transfer.
After the multicast port is opened, data packets are received directly. The socket communication is
then used to coordinate packet resends.Typically, a receiver will loose intermittent packets (because
of the use of IP multicast, data collisions, etc.). After the file is transferred, all receivers will respond
with a bit map of missed packets. The logically ANDing of this mask is used to initiate a resend of
commonly missed packets. This process will repeat a few times (with less data to resend on each
iteration). Finally, any receiver will still have incomplete data until all the missing pieces are sent in
a reliable unicast fashion.
The data transmission for a multicast datagrid transmission is always initiated by the Orchestrate
Server. Currently this is the same server that is running the grid.
With the exception of multicast file transfers, all datagrid traffic goes over the existing connection
between the agent/client and the server. This is done transparently to the end user or developer. As
long as the agent is connected and/or the user is logged in to the grid, the datagrid operations
function.
The PlateSpin Orchestrate Datagrid 27
3.2.1 Multicast Example
Multicast transfers are currently only supported through JDL code on the agents. In JDL, after you
get the Datagrid object, you can enable and configure multicasting like this:
dg.setMulticast(true)
Additional multicast tuneables can be set on the object as well, such as the following example:
dg.setMulticastRate(20000000)
This would set the maximum data rate on the transfer to 20 million bytes/sec. There are a number of
other options as well. Refer to the JDL reference for complete information.
The actual multicast copy is initiated when a sufficient number of JDL joblets on different nodes
issue the JDL command:
dg.copy(...)
novdocx (en) 13 May 2009
to actually copy the requested file locally. See the
setMulticastMin
and
setMulticastQuorum
options to change the minimum receiver count and other thresholds for multicasting.
For example, to set up a multicast from a joblet, where the data rate is 30 million bytes/sec, and a
minimum of five receivers must request multicast within 30 seconds, but if 30 receivers connect,
then start right away, use the following JDL:
dg = DataGrid()
dg.setMulticast(true)
dg.setMulticastRate(30000000)
dg.setMulticastMin(5)
dg.setMulticastQuorum(30)
dg.setMulticastWait(30000)
dg.copy('grid:///vms/huge-image.dsk', 'image.dsk')
In the above example, if at least five agents running the joblet request the file within the same 30
second period, then a multicast is started to all agents that have requested multicast before the
transfer is started. Agents requesting after the cutoff have to wait for the next round. Also, if fewer
than 5 agents request the file, then each agent will simply fall back to plain old unicast file copy.
Furthermore, if more than 30 agents connect before 30 seconds is up, then the transfer begins
immediately after the 30th request. This is useful for situations where you know how many agents
will request the file and want to start as soon as all of them are ready.
3.2.2 Grid Performance Factors
The multicast system performance is dependent on the following factors:
Network Load: As the load increases, there is more packet loss, which results in more retries.
Number of Nodes: The more nodes (receivers) there are, the greater the efficiency of the
multicast system.
File Size: The larger the file size, the better. Unless there are a large number of nodes, files less
than 2 Mb are probably too small.
28 PlateSpin Orchestrate 2.0 Developer Guide and Reference
Tuning: The datagrid facility has the ability to throttle network bandwidth. Best performance
has been found at about maximum bandwidth divided by 2. Using more bandwidth leads to
more collisions. Also the number of simultaneous multicasts can be limited. Finally the
minimum receiver size, receiver wait time and quorum receiver size can all be tuned.
Access to the datagrid is typically performed via the CLI tool or JDL code within a job. There is also
a Java API in the Client SDK (on which the CLI is implemented). See “ClientAgent” on page 193.
3.2.3 Plan for Datagrid Expansion
When planning your datagrid, you need to consider where you want the Orchestrate Server to store
its data. Much of the server data is the contents of the datagrid, including ever-expanding job logs.
Every job log can become quite large and quickly exceed its storage constraints.
In addition, every deployed job with its job package—JDL scripts, policy information, and all other
associated executables and binary files—is stored in the datagrid. Consequently, if your datagrid is
/opt
going to grow very large, store it in a directory other than
.
3.3 datagrid.copy Example
novdocx (en) 13 May 2009
This example fetches the specified source file to the destination. A recursive copy is then attempted
setRecursive(True)
if
setMulticast(True)
is set. The default is a single file copy. A multicast also is attempted if
is set. The default is to do a unicast copy.The following example copies a
file from the datagrid to a resource, then read the lines of the file:
1 datagrid = DataGrid()
2 datagrid.copy("grid:///images/myFile","myLocalFile")
3 text = open("myLocalFile").readlines()
This is an example to recursively copy a directory and its sub directories from the datagrid to a
resource:
4 datagrid = DataGrid()
5 datagrid.setRecursive(True)
6 datagrid.copy("grid:///testStore/testFiles","/home/tester/
myLocalFiles")
Here’s an example to copy down a file from the job deployment area to a resource and then read the
lines of the file:
7 datagrid = DataGrid()
8 datagrid.copy("grid:///!myJob/myFile","myLocalFile")
9 text = open("myLocalFile").readlines()
Here are the same examples without using the shortcut characters. This shows the job “myJob” is
under the “jobs” directory under the Datagrid root:
10 datagrid = DataGrid()
11 datagrid.copy("grid:///jobs/myJob/myFile","myLocalFile")
12 text = open("myLocalFile").readlines()
The PlateSpin Orchestrate Datagrid 29
novdocx (en) 13 May 2009
30 PlateSpin Orchestrate 2.0 Developer Guide and Reference
Loading...