Appendix H: Interfacing with Moab (APIs)

Appendices > Appendix H: Interfacing with Moab (APIs)

Appendix H: Interfacing with Moab (APIs)

Moab provides numerous interfaces allowing it to monitor and manage most services and resources. It also possesses flexible interfaces to allow it to interact with peer services and applications as both a broker and an information service. This appendix is designed to provide a general overview and links to more detailed interface documentation.

H.1 Moab Query and Control APIs
- Allow external portals and services to obtain information about compute resources, workload, and usage statistics.
H.2 Resource Management Interfaces
- Allow Moab to monitor, schedule, and control services and resources.
H.3 Identity and Credential Management Interfaces
- Allow monitoring and active management of user configuration, credentials, policies, and usage information.
H.4 Accounting and Event Interfaces
- Allow import/export of accounting and event information to external entities.
H.5 Discovery/Directory Services
H.6 Job Submission and Management Interface
- Query resource availability, submit, modify, and manage jobs, and query the status of active and completed jobs.
H.7 Grid Services API
- Provide and use information, data, job, and resource management services in a distributed environment.

Moab interfaces to systems providing various services and using various protocols. This appendix is designed to assist users who want to enable Moab in new environments using one of the existing interfaces. It does not cover the steps required to create a new interface.

H.1 Query and Control APIs

The Moab Cluster and Grid Suite provide a (Moab) workload manager server that supports a broad array of client services. These services can be directly accessed via Moab client commands.

H.1.3 CLI (Command Line Interface) XML API

All Moab client commands can report results in XML format to allow the information to be easily integrated into peer services, portals, databases, and other applications. To request that a client command report its output in XML, specify the --format=xml flag as in the following example:

> showq --format=xml
<Data>
<Object>queue</Object>
<cluster LocalActiveNodes="1" LocalAllocProcs="1" LocalIdleNodes="0" LocalIdleProcs="3" LocalUpNodes="1" 
  LocalUpProcs="4" RemoteActiveNodes="0" RemoteAllocProcs="0" RemoteIdleNodes="0" RemoteIdleProcs="0" 
  RemoteUpNodes="0" RemoteUpProcs="0" time="1128451812"></cluster>
<queue count="1" option="active">
<job AWDuration="11672" EEDuration="1128451812" Group="[DEFAULT]" JobID="Moab.2" MasterHost="cw2" PAL="2" 
  QOS="bug3" ReqAWDuration="54000" ReqNodes="1" ReqProcs="1" RsvStartTime="1128451812" RunPriority="0" 
  StartPriority="1" StartTime="1128451812" StatPSDed="11886.580000" StatPSUtl="11886.580000" State="Running" 
  SubmissionTime="1128451812" SuspendDuration="0" User="smith"></job>
</queue>
<queue count="1" option="eligible">
<job EEDuration="1128451812" Group="jacksond" JobID="customer.35" QOS="bug" ReqAWDuration="3600" 
  ReqProcs="1" StartPriority="1" StartTime="0" State="Idle" SubmissionTime="1128451812" SuspendDuration="0" 
  User="johnson"></job>
<queue><queue count="0" option="blocked"></queue>
</Data>

Common Query/Control Services

jobs
- query status - mdiag -j (XML details)
- submit - msub (XML format)
- cancel - mjobctl -c
nodes
- query status - mdiag -n (XML details)
- create resource reservation - mrsvctl -c
- destroy resource reservation - mrsvctl -r

H.2 Resource Management Interfaces

Moab can monitor, schedule, and control services and resources using multiple protocols. These protocols include the following:

LDAP
script/flat file
Resource Manager Specific Interfaces - LSF, SGE, TORQUE, PBSPro, Loadleveler, and so forth

Using the resource manager interfaces, Moab can do the following:

monitor resources (compute host, network, storage, and software license based resources)
- load configuration, architecture, and feature information
- load state, utilization, and workload information
- load policy and ownership information
manage resources

dynamically reconfigure and reprovision resource hardware (processors, memory, etc.)
dynamically reconfigure and reprovision resource software (operating system, application software, file system mounts, etc.)
dynamically reconfigure and reprovision resource security (VPN's, VLAN's, host security, etc.)

monitor workload (batch jobs, interactive jobs, persistent services, dynamic services, distributed services)
- load state, resource requirement, and required environment information
- load user, group, and credential information
- load utilization, resource allocation, and policy information
manage workload
- migrate jobs from one resource to another (intra-cluster and inter-cluster)
- modify jobs for translation and optimization purposes
- suspend, resume, checkpoint, restart, and cancel jobs
query cluster policies and configuration

H.3 Identity and Credential Management Interfaces

Moab's identity and credential management interfaces allow Moab to exchange credential and user configuration, access, policy, and usage information.

H.4 Accounting Interfaces

Moab accounting interfaces allow Moab to export local utilization statistics, events, and accounting information to site specific scripts.

Accounting Interface

H.5 Discovery/Directory Services

Moab can import and export key event information regarding workload, cluster resources, cluster and grid services, and other components of hardware and software infrastructure.

By default, these clients communicate with the scheduler using the U.S. Department of Energy (DOE) Scalable Systems Software socket and wire protocols. These protocols are largely HTML- and XML-based, using PKI, 3DES, MD5, challenge, and other security protocols and are documented within the SSS project pages.

As part of this initiative, the scheduler/client protocol has been extended to support multiple socket level protocol standards in communicating with its clients and peer services. These include SingleUseTCP, SSS-HALF, and HTTP. The client socket protocol can be specified by setting the MCSOCKETPROTOCOL parameter to SUTCP, SSS-HALF, or HTTP. Further protocols are being defined and standardized over time and backwards compatibility will be maintained. Documentation on the SSS-HALF implementation can be found within the DOE's SSS Project Notebooks.

H.6 Job Submission and Management Interface

Moab provides interfaces to enable the following services:

Resource Availability Query
- Determine quantity, state, and configuration of configured resources (idle, busy, and down nodes)
- Determine quantity and configuration of all available resources (idle nodes)
- Determine resources available subject now and in the future for potential job
- Determine best target cluster destination for potential job
- Determine largest/longest job which could start immediately
- Determine estimated start time for potential job
- Determine earliest guaranteed start time for potential job
Reserve Resources
- Reserve specific resources for desired time frame
Submit Job (XML format)
- Submit job to specific cluster
- Submit job to global job queue
Manage Job
- Hold job
- Adjust job priority
- Modify job executable, args, data requirements, job dependencies, duration, hostcount, or other attributes
- Suspend/resume job
- Checkpoint/requeue job
- Cancel job
- Migrate job
- Adjust job quality of service (QoS)
Query Job
- Determine job state, utilization, or output results for idle, active, or completed job
- Determine estimated start time
- Determine guaranteed start time

H.7 Grid Interfaces

Moab provides interfaces to allow interaction with various grid brokers and services. These interfaces allow Moab to provide services as well as utilize services.

Services Utilized

Information Services (import and utilize information service data in making scheduling decisions)
Job Migration
Data Migration
Credential Mapping
Security and Delegation

See Moab Workload Manager for Grids for more information on utilized services.

Services Provided

Information Services (provide resource, workload, and credential information)
Job Migration
Data Migration
Credential Mapping

See Moab Workload Manager Grid Basics for more information on provided services.