4 Resources
The sections below show the MWS resources and the HTTP methods defined on them. The prefix for these resources depends on how themws.war file is deployed. A typical prefix would be
http://localhost:8080/mws. Using this example, one absolute resource
URI would be http://localhost:8080/mws/rest/jobs.
4.1 Access Control Lists
This section describes behavior of the ACL Rules (Access Control List Rules) object in Moab Web Services. It contains the URLs, request bodies, and responses delivered to and from Moab Web Services.The ACL API contains the type and description of all fields in the ACL Rules object. It also contains details regarding which fields are valid during PUT and POST actions.
Supported Methods
ACLs are not directly manipulated through a single URL, but with sub-URLs of the other objects such as Virtual Containers and Reservations.
| Resource | GET | PUT | POST | DELETE |
|---|---|---|---|---|
| /rest/reservations/rsvId/acl-rules/aclId | Create or Update ACLs | Delete ACL | ||
| /rest/vcs/vcId/acl-rules/aclId | Create or Update ACLs | Delete ACL |
4.1.1 Getting ACLs
Although ACL Rules cannot be retrieved directly using the GET method on any of theacl-rules resources, ACL Rules are attached to supported
objects when querying for them. Each supported object contains a field
named aclRules, which is a collection of the ACL Rules defined on
that object.Supported Objects
The following is a list of objects that will return ACL Rules when queried:4.1.2 Creating or Updating ACLs
The HTTP PUT method is used to create or update ACL Rules. The request body can contain one or more ACL Rules. If an ACL Rule with the sametype
and value exists, then it will be overwritten.Quick Reference
PUT http://localhost/mws/rest/reservations/<rsvId>/acl-rules PUT http://localhost/mws/rest/vcs/<vcId>/acl-rules
4.1.2.1 Create or Update ACL
URLs and Parameters
PUT http://localhost/mws/rest/reservations/<objectId>/acl-rules PUT http://localhost/mws/rest/vcs/<objectId>/acl-rules
| Parameter | Required | Type | Valid Values | Description |
|---|---|---|---|---|
| objectId | Yes | String | - | The unique identifier of the object. |
Request Body
The request body below shows all the fields that are available for the PUT method, along with some sample values.JSON Request Body
{"aclRules": [{
"affinity": "POSITIVE",
"comparator": "LEXIGRAPHIC_EQUAL",
"type": "USER",
"value": "ted"
}]}Sample Response
This message may not match the message returned from Moab exactly, but is given as an example of the structure of the response.
JSON Response
{"messages":["Virtual container 'vc1' successfully modified"]}Samples
Create or update multiple ACLs on a single object:PUT http://localhost/mws/rest/reservations/system.21/acl-rules
{"aclRules": [
{
"affinity": "POSITIVE",
"comparator": "LESS_THAN_OR_EQUAL",
"type": "DURATION",
"value": "3600"
},
{
"affinity": "POSITIVE",
"comparator": "LEXIGRAPHIC_EQUAL",
"type": "USER",
"value": "ted"
}
]}Restrictions
- ACL Rules cannot be added to or updated on Standing Reservations.
- The affinity and comparator fields are ignored for Virtual Containers.
4.1.3 Deleting ACLs
The HTTP DELETE method is used to remove ACL Rules.Quick Reference
ACL Rules cannot be removed from Standing Reservations.
DELETE http://localhost/mws/rest/reservations/<rsvId>/acl-rules/<aclId> DELETE http://localhost/mws/rest/vcs/<vcId>/acl-rules/<aclId>
4.1.3.1 Delete ACL
URLs and Parameters
DELETE http://localhost/mws/rest/reservations/<objectId>/acl-rules/<aclId> DELETE http://localhost/mws/rest/vcs/<objectId>/acl-rules/<aclId>
| Parameter | Required | Type | Valid Values | Description |
|---|---|---|---|---|
| objectId | Yes | String | - | The unique identifier of the object from which to remove the ACL Rule. |
| aclId | Yes | String | - | A string representing the ACL Rule, with the format type:value. |
Sample Response
This message may not match the message returned from Moab exactly, but is given as an example of the structure of the response.
JSON Response
{"messages":["Successfully modified virtual container 'vc1'"]}Restrictions
- ACL Rules cannot be removed from Standing Reservations.
4.2 Accounts
This section describes behavior of the Accounts object in Moab Web Services. It contains the URLs, request bodies, and responses delivered to and from Moab Web Services.This resource refers to Moab Accounting Manager accounts, not Moab Workload Manager accounts.
The Account API contains the type and description of fields that all Accounts have in common.
Supported Methods
| Resource | GET | PUT | POST | DELETE |
|---|---|---|---|---|
| /rest/accounts | Get all accounts | |||
| /rest/accounts/id | Get specified account |
4.2.1 Getting Accounts
The HTTP GET method is used to retrieve Accounts information.Quick Reference
GET http://localhost/mws/rest/accounts
4.2.1.1 Get All Accounts
URLs and Parameters
GET http://localhost/mws/rest/accounts?proxy-user=<USER>[&custom-fields=Department][&query={"deleted":false}][&sort={"requestId":-1}]
| Parameter | Required | Valid Values | Description | Example |
|---|---|---|---|---|
| proxy-user | Yes | String | Perform action as defined MAM user. | proxy-user=amy |
| custom-fields | No | Comma-Separated String | Includes custom MAM account attributes. | custom-fields=Department |
| query | No | JSON | Query for specific results. | query={"deleted":false} |
| sort | No | JSON | Sort the results. Use 1 for ascending and -1 for descending. | sort={"requestId":-1} |
The query parameter does not support the full Mongo query syntax. Only querying for a simple,
non-nested JSON object is allowed.See Global URL Parameters for available URL parameters.Sample Response
GET http://localhost/mws/rest/accounts?proxy-user=amy&fields=name,description
{
"totalCount": 2,
"resultCount": 2,
"results": [
{
"id": "biology",
"description": "Biology Dept."
},
{
"id": "chemistry",
"description": "Chemistry Dept."
}
]
}4.2.1.2 Get Single Account
URLs and Parameters
GET http://localhost/mws/rest/accounts/<id>| Parameter | Required | Type | Valid Values | Description |
|---|---|---|---|---|
| id | Yes | String | - | The unique identifier of the object. |
Sample Responses
GET http://localhost/mws/rest/accounts/chemistry?proxy-user=amy
{
"id": "chemistry",
"active": true,
"organization": "",
"description": "Chemistry Dept",
"creationTime": "2012-04-11 06:56:11 MDT",
"modificationTime": "2012-04-11 06:56:11 MDT",
"deleted": false,
"requestId": 94,
"transactionId": 283,
"users": [
{
"id": "amy",
"active": true,
"admin": false
},
{
"id": "bob",
"active": true,
"admin": false
},
{
"id": "dave",
"active": true,
"admin": false
}
]
}4.3 Diagnostics
This section describes additional REST calls that are available for performing diagnostics on Moab Web Services.Supported Methods
| Resource | GET | PUT | POST | DELETE |
|---|---|---|---|---|
| /rest/diag/about | Get version information |
4.3.1 Version and Build Information
The HTTP GET method is used to retrieve version and build information.Quick Reference
GET http://localhost/mws/rest/diag/about
URLs and Parameters
GET http://localhost/mws/rest/diag/about
Sample Response
The response contains the application version, build number, build date, and revision.{
"version":"7.0",
"build":"100",
"buildDate":"2012-01-01_16-00-00",
"revision":"1000"
}4.4 Events
This section describes the URLs, request bodies, and responses delivered to and from Moab Web Services for handling eventsThe Event API contains the type and description of all fields in the Event object. It also contains details regarding which fields are valid during POST actions.
Supported Methods
| Resource | GET | PUT | POST | DELETE |
|---|---|---|---|---|
| /rest/events | Get all events | Create event | ||
| /rest/events/id | Get specified event |
Configuration
Logging events to a flat file requires that you make a few changes to the configuration in the log4j section of the mws-config.groovy file so that events will be logged to the events.log file, and all other Moab Web Services logging information will be sent to the mws.log file.Causing events.log to Roll Based on a Time Window
You can specify how often the events.log file rolls. The following example illustrates the configuration changes you will need make to mws-config.groovy to cause the events.log file to roll based on a time window. (In this example, mws-config.groovy is configured so that events.log rolls daily at midnight.)Daily rolling events.log configuration in mws-config.groovy
log4j = {
def eventAppender = new org.apache.log4j.rolling.RollingFileAppender(name: 'events', layout: pattern(conversionPattern: "%m%n"))
def rollingPolicy = new org.apache.log4j.rolling.TimeBasedRollingPolicy(fileNamePattern: '/tmp/events.%d{yyyy-MM-dd}', activeFileName: '/tmp/events.log')
rollingPolicy.activateOptions()
eventAppender.setRollingPolicy(rollingPolicy) appenders {
appender eventAppender rollingFile name: 'rootLog',
file: '/tmp/mws.log',
maxFileSize: '1GB'
} root {
warn 'rootLog'
} trace additivity:false, events:'com.ace.mws.events.EventFlatFileWriter'
}Monthly event logs
def rollingPolicy = new org.apache.log4j.rolling.TimeBasedRollingPolicy(fileNamePattern: '/tmp/events.%d{yyyy-MM}', activeFileName: '/tmp/events.log')Hourly event logs
def rollingPolicy = new org.apache.log4j.rolling.TimeBasedRollingPolicy(fileNamePattern: '/tmp/events.%d{yyyy-MM-dd_HH:00}', activeFileName: '/tmp/events.log')Configuring events.log to Roll Based on File Size Threshold
You can also configure the events.log file to roll when the log size exceeds a specified threshold. The following example illustrates the configuration changes you will need to make to mws-config.groovy to cause the events.log file to roll on a size threshold. (In this example, mws-config.groovy is configured so that events.log rolls when its size exceeds 50 MB.)mws-config.groovy configuration that rolls events.log based on file size
log4j = {
appenders {
rollingFile name: 'events',
file: '/tmp/events.log',
maxFileSize: '50MB',
maxBackupIndex:10 rollingFile name: 'rootLog',
file: '/tmp/mws.log',
maxFileSize: '1GB'
} root {
warn 'rootLog'
} trace additivity:false, events:'com.ace.mws.events.EventFlatFileWriter'
}Additivity
The additivity attribute of the EventFlatFileWriter logger can be either "true" or "false". If you specify "true", events will be logged to the events.log file and the mws.log file. If you specify "false", events will be logged to the events.log file only. (All other Moab Web Services logging information will be logged to the mws.log file, as configured by the rootLog appender.)To log events to the mws.log file in addition to the events.log file, make this configuration: additivity:true. For example:Logging events to both events.log and mws.log
trace additivity:true, events:'com.ace.mws.events.EventFlatFileWriter'Deleting Old Events
By default, MWS will hold event data in MongoDB indefinitely. However, if disk space is limited, you may want to regularly delete old, unneeded events from MongoDB. This section contains some examples of how you can do this.Let's say that you want to delete events that are older than 90 days. You could run this script. (There are 86,400,000 milliseconds in a day, so in this example,90*86400000 corresponds to 90 days in milliseconds.)Delete events older than 90 days
$ mongo
MongoDB shell version: 2.0.1
connecting to: test
> use mws
> db.event.remove({eventTime:{$lt:new Date(new Date().getTime()-90*86400000)}})
> exitdeleteOldEvents.sh
#!/bin/bash
printf 'use mws_dev\ndb.event.remove({eventTime:{$lt:new Date(new Date().getTime()-90*86400000)}})\nexit' | mongo$crontab -e) so that old
events are automatically deleted on a certain day of the week (for example, every Sunday at 2:00 a.m.), you would add an entry like this:cron table entry to delete old events
00 02 * * 0 /root/deleteOldEvents.sh
4.4.1 Getting Events
The HTTP GET method is used to retrieve Event information. Queries for all objects and a single object are available.Quick Reference
GET http://localhost/mws/rest/events[?query={"field":"value"}&sort={"field":<1|-1>}]
GET http://localhost/mws/rest/events/<id>4.4.1.1 Get All Events
URLs and Parameters
GET http://localhost/mws/rest/events[?query={"field":"value"}&sort={"field":<1|-1>}]| Parameter | Required | Valid Values | Description | Example |
|---|---|---|---|---|
| query | No | JSON | Query for specific results. | query={"status":"failure"} |
| sort | No | JSON | Sort the results. Use 1 for ascending and -1 for descending. | sort={"id":-1} |
Sample Response
GET http://localhost:8080/mws/rest/events
{
"totalCount":3,
"resultCount":3,
"results":[
{
"details":{ },
"errorMessage":{
"errorCode":"542",
"message":"Cannot communicate with XCAT resource manager",
"originator":"XCAT"
},
"eventCategory":"failure",
"eventTime":"2012-01-27 15:18:32 MST",
"eventType":"rmfailure",
"facility":"rm",
"primaryObject":{
"serialization":null,
"type":"rm",
"id":"xcat"
},
"sourceComponent":"MWM",
"status":"failure",
"id":"4faddab8c4aa264506f8ac3d"
},
{
"details":{ },
"eventCategory":"start",
"eventTime":"2012-01-27 15:18:31 MST",
"eventType":"schedcyclestart",
"facility":"scheduler",
"sourceComponent":"MWM",
"status":"success",
"id":"4faddab8c4aa264506f8ac3c"
},
{
"details":{
"alpha":"lorem ipsum dolor sit amet",
"bravo":"2",
"charlie":"consectetur adipisicing elit, sed do"
},
"eventCategory":"start",
"eventTime":"2012-01-27 15:18:30 MST",
"eventType":"jobstart",
"facility":"job",
"initiatedBy":{
"proxyUser":"bob",
"user":"tomcat6"
},
"primaryObject":{
"serialization":"\n <job JobID="moab.849" ReqAWDuration="100000" User="bob" />\n ",
"type":"job",
"id":"moab.849"
},
"relatedObjects":[
{
"type":"vm",
"id":"vm56"
},
{
"type":"service",
"id":"lamp.211"
}
],
"sourceComponent":"MWM",
"status":"success",
"id":"4faddab8c4aa264506f8ac3b"
}
]
}Querying Events
It is possible to query events by one or more fields based on MongoDB query syntax. The following contains examples of simple and complex event queries and event queries by date.Simple Queries
To see only events that are of type "jobsubmit":http://localhost/mws/rest/events?query={"eventType":"jobsubmit"}http://localhost/mws/rest/events?query={"eventType":"jobsubmit","status":"failure"}http://localhost/mws/rest/events?query={"facility":"job"}http://localhost/mws/rest/events?query={"eventCategory":"start"}More Complex Queries
You can query on embedded JSON objects within the event JSON. For example, to see events associated with proxyUser bob:http://localhost/mws/rest/events?query={"initiatedBy.proxyUser":"bob"}http://localhost/mws/rest/events?query={"initiatedBy.proxyUser":{"$ne":"bob"}}$in operator.
For example, to see events that relate to either alice, bob, or charlie:http://localhost/mws/rest/events?query={"initiatedBy.proxyUser":{"$in":["alice","bob","charlie"]}}Querying Events by Date
To see events created before January 27, 2012 at 12:08 a.m. MST:http://localhost/mws/rest/events?query={"eventTime":{"$lt":"2012-01-27 12:08:00 MST"}}http://localhost/mws/rest/events?query={"eventTime":{"$lte":"2012-01-27 12:08:00 MST"}}http://localhost/mws/rest/events?query={"eventTime":{"$gt":"2012-01-27 12:04:00 MST"}}http://localhost/mws/rest/events?query={"eventTime":{"$gte":"2012-01-27 12:04:00 MST"}}http://localhost/mws/rest/events?query={"eventTime":{"$gte":"2012-01-27 12:04:00 MST","$lte":"2012-01-27 12:08:00 MST"}}http://localhost/mws/rest/events?query={"initiatedBy.proxyUser":"bob","eventTime":{"$gte":"2012-01-27 12:04:00 MST","$lte":"2012-01-27 12:08:00 MST"}}http://localhost/mws/rest/events?query={"initiatedBy.proxyUser":"bob","eventType":"jobsubmit","eventTime":{"$gte":"2012-01-27 12:04:00 MST","$lte":"2012-01-27 12:08:00 MST"}}Sorting
See the sorting section of Global URL ParametersLimiting the Number of Results
If you want to limit the number of results of events, you can use themax parameter. For
example, to see only 10 "vmmigrate" events:http://localhost/mws/rest/events?query={"eventType":"vmmigrate"}&sort={"eventTime":1}&max=10max with offset, as follows:http://localhost/mws/rest/events?query={"eventType":"vmcreate"}&sort={"eventTime":-1}&max=51&offset=60Retrieving a Subset of Fields
To cause only certain fields to return for each event, use thefields parameter. For example, to
show only the eventTime field for each event:http://localhost/mws/rest/events?max=3&fields=eventTime
{
"totalCount": 187,
"resultCount": 3,
"results": [
{"eventTime": "2012-03-05 10:01:59 MST"},
{"eventTime": "2012-03-05 10:02:00 MST"},
{"eventTime": "2012-03-05 10:02:01 MST"}
]
}http://localhost/mws/rest/events?fields=name,type,status
{
"totalCount": 187,
"resultCount": 3,
"results": [
{
"eventTime": "2012-03-05 10:01:59 MST",
"eventType": "jobsubmit",
"status": "failure"
},
{
"eventTime": "2012-03-05 10:02:00 MST",
"eventType": "jobstart",
"status": "success"
},
{
"eventTime": "2012-03-05 10:02:01 MST",
"eventType": "vmmigrate",
"status": "success"
}
]
}4.4.1.2 Get Single Event
URLs and Parameters
GET http://localhost/mws/rest/events/<id>| Parameter | Required | Type | Valid Values | Description |
|---|---|---|---|---|
| id | Yes | String | - | The unique identifier of the object. |
Sample Response
JSON Response
{
"details": {
"attribute": "walltime",
"modifier": "increase",
"value": "200000"
},
"eventCategory": "job",
"eventTime": "2012-01-27 00:07:00 MST",
"eventType": "jobmodify",
"facility": "baseline",
"initiatedBy": {
"proxyUser": "bob",
"user": "viewpoint"
},
"primaryObject": {
"serialization": null,
"type": "job",
"id": "moab.900"
},
"sourceComponent": "MWM",
"status": "success",
"id": "4fa46081c4aa5b896ac4b757"
}4.4.2 Creating Events
The HTTP POST method is used to create an Event.Quick Reference
POST http://localhost/mws/rest/events
4.4.2.1 Create Event
URLs and Parameters
POST http://localhost/mws/rest/events
Request Body
POST http://localhost/mws/rest/events
<Events> <Event eventTime="2012-01-27T15:18:30.000-07:00" eventType="jobstart" eventCategory="start" sourceComponent="MWM" status="success" facility="job"> <InitiatedBy user="tomcat6" proxyUser="bob" /> <PrimaryObject objectType="job" objectID="moab.849"> <Serialization> <![CDATA[<job JobID="moab.849" ReqAWDuration="100000" User="bob" />]]> </Serialization> </PrimaryObject> <RelatedObjects> <RelatedObject objectType="vm" objectID="vm56" /> <RelatedObject objectType="service" objectID="lamp.211" /> </RelatedObjects> <Details> <Detail name="alpha">lorem ipsum dolor sit amet</Detail> <Detail name="bravo">2</Detail> <Detail name="charlie">consectetur adipisicing elit, sed do</Detail> </Details> </Event> <Event eventTime="2012-01-27T15:18:31.000-07:00" eventType="schedcyclestart" eventCategory="start" sourceComponent="MWM" status="success" facility="scheduler" /> <Event eventTime="2012-01-27T15:18:32.000-07:00" eventType="rmfailure" eventCategory="failure" sourceComponent="MWM" status="failure" facility="rm"> <PrimaryObject objectType="rm" objectID="xcat" /> <ErrorMessage originator="XCAT" errorCode="542">Cannot communicate with XCAT resource manager</ErrorMessage> </Event> </Events>
Unlike most other URLs, the events URL accepts XML, instead of JSON.
Sample Response
If the request was successful, the response will be an object with an id property containing the ID of the newly created events. On failure, the response is an error message.JSON Response
[{"id":"4fadd83bc4aa366464599e1a"},{"id":"4fadd83bc4aa366464599e1b"},{"id":"4fadd83bc4aa366464599e1c"}]2012-01-27T15:18:30.000-07:00 type="jobstart" category="start" sourceComponent="MWM" status="success" facility="job" initiatedBy.user="tomcat6" initiatedBy.proxyUser="bob" primaryObject.type="job" primaryObject.id="moab.849" relatedObject.0.type="service" relatedObject.0.id="lamp.211" relatedObject.1.type="vm" relatedObject.1.id="vm56" detail.alpha="lorem ipsum dolor sit amet" detail.bravo="2" detail.charlie="consectetur adipisicing elit, sed do" primaryObject.serialization="<job JobID=\"moab.849\" ReqAWDuration=\"100000\" User=\"bob\" />" 2012-01-27T15:18:31.000-07:00 type="schedcyclestart" category="start" sourceComponent="MWM" status="success" facility="scheduler" 2012-01-27T15:18:32.000-07:00 type="rmfailure" category="failure" sourceComponent="MWM" status="failure" facility="rm" primaryObject.type="rm" primaryObject.id="xcat" error.originator="XCAT" error.code="542" error.message="Cannot communicate with XCAT resource manager"
Note that " (double quote) characters in the input have been replaced by \" characters in the output. (For other character restrictions, see the "Restrictions" section below.)
Restrictions
Special characters, such as newline, carriage return, and " (double quote) are encoded in the output of events.log to make events.log easy to parse with scripts and third party tools. For example, if the input XML contains:<ErrorMessage>RM says, "Cannot provision vm21"</ErrorMessage>
error.message="RM says, \"Cannot provision vm21\""| Character | Escape Sequence | |
|---|---|---|
| " (double quote) | \" | |
| \ (backslash) | \\ | |
| newline | \n | |
| carriage return | \r | |
| tab | \t |
- Detail names can only contain alpha-numeric characters, colons (:), underscores (_), and dashes (-).
- primaryObject.serialization, error.message, and detail values (for example detail.someName="some value") can contain any printable ASCII character. Single quotes (') and double quotes (") cannot be contained in any other field.
- A single event cannot contain more than more than 50 details. If an event has more than 50 details, the excess details will be ignored.
4.5 Funds
This section describes behavior of the Fund object and all related objects in Moab Web Services. It contains the URLs, request bodies, and responses delivered to and from Moab Web Services.The Fund API, FundBalance API, FundStatement API, and FundStatementSummary API contain the type and description of all fields in the Fund object as well as related objects and reports given in the URLs below.
Supported Methods
| Resource | GET | PUT | POST | DELETE |
|---|---|---|---|---|
| /rest/funds | Get all funds | |||
| /rest/funds/id | Get specified fund | |||
| /rest/funds/balances | Get all fund balances | |||
| /rest/funds/reports/statement | Get fund statement | |||
| /rest/funds/reports/statement/summary | Get fund statement summary |
4.5.1 Getting Funds
The HTTP GET method is used to retrieve Fund information.Quick Reference
GET http://localhost/mws/rest/funds?proxy-user=<USER>[&active=true][&custom-fields=health][&filter={"project":"chemistry"}][&filter-type=NonExclusive][&query={"priority":"2"}][&sort={"id":-1}] GET http://localhost/mws/rest/funds/<id>?proxy-user=<USER>[&active=true][&custom-fields=health][&filter={"project":"chemistry"}][&filter-type=NonExclusive] GET http://localhost/mws/rest/funds/balances?proxy-user=<USER>[&custom-fields=health][&filter={"project":"chemistry"}][&filter-type=NonExclusive] GET http://localhost/mws/rest/funds/reports/statement?proxy-user=<USER>[&filter=<FILTER>][&filter-type=<FILTER-TYPE>][&start-time=<DATE-STRING>][&end-time=<DATE-STRING>][&context=<CONTEXT>] GET http://localhost/mws/rest/funds/reports/statement/summary?proxy-user=<USER>[&filter=<FILTER>][&filter-type=<FILTER-TYPE>][&start-time=<DATE-STRING>][&end-time=<DATE-STRING>]
4.5.1.1 Get All Funds
URLs and Parameters
GET http://localhost/mws/rest/funds?proxy-user=<USER>[&active=true][&custom-fields=health][&filter={"project":"chemistry"}][&filter-type=NonExclusive][&query={"priority":"2"}][&sort={"id":-1}]
| Parameter | Required | Valid Values | Description | Example |
|---|---|---|---|---|
| proxy-user | Yes | String | Perform action as defined MAM user. | proxy-user=amy |
| active | No | Boolean | Lists only active or non-active allocations of the fund. The fund amount becomes the sum of the active/inactive allocations. | active=true |
| custom-fields | No | Comma-Separated String | Includes custom MAM fund attributes. | custom-fields=health |
| filter | No | JSON | Query funds based on defined MAM filter. | filter={"project":"chemistry"} |
| filter-type | No | String | Query funds based on defined MAM filter type. | filter-type=NonExclusive |
| query | No | JSON | Query for specific results. | query={"priority":"2","allocation.active":"false"} |
| sort | No | JSON | Sort the results. Use 1 for ascending and -1 for descending. | sort={"id":-1} |
The query parameter does not support the full Mongo query syntax. Only querying for a simple,
non-nested JSON object is allowed.See Global URL Parameters for available URL parameters.Sample Response
GET http://localhost/mws/rest/funds?proxy-user=amy&fields=id,name,allocations,constraints
{
"totalCount": 1,
"resultCount": 1,
"results": [ {
"id": 2,
"name": 1204,
"allocations": [ {
"id": 2,
"startTime": "-infinity",
"endTime": "2012-02-02 09:34:42 MST",
"amount": 9060000,
"creditLimit": 0,
"deposited": 9060000,
"active": true,
"description": ""
}],
"fundConstraints": [ {
"id": 2,
"name": "CostCenter",
"value": 1204
}]
}]
}4.5.1.2 Get Single Fund
URLs and Parameters
GET http://localhost/mws/rest/funds/<id>?proxy-user=<USER>[&active=true][&custom-fields=health][&filter={"project":"chemistry"}][&filter-type=NonExclusive]
| Parameter | Required | Type | Valid Values | Description |
|---|---|---|---|---|
| id | Yes | String | - | The unique identifier of the object. |
| proxy-user | Yes | String | Perform action as defined MAM user. | proxy-user=amy |
| active | No | Boolean | Lists only active or non-active allocations of the fund. The fund amount becomes the sum of the active/inactive allocations. | active=true |
| custom-fields | No | Comma-Separated String | Includes custom MAM fund attributes. | custom-fields=health |
| filter | No | JSON | Query funds based on defined MAM filter. | filter={"project":"chemistry"} |
| filter-type | No | String | Query funds based on defined MAM filter type. | filter-type=NonExclusive |
Sample Responses
Fund sample response
{
"id": 2,
"name": 1204,
"priority": 0,
"description": "R&D for Manufacturing",
"creationTime": "2012-02-02 09:34:42 MST",
"amount": 9060000,
"deposited": 9060000,
"creditLimit": 0,
"allocations": [ {
"id": 2,
"startTime": "-infinity",
"endTime": "infinity",
"amount": 9060000,
"creditLimit": 0,
"deposited": 9060000,
"active": true,
"description": ""
}],
"fundConstraints": [ {
"id": 2,
"name": "CostCenter",
"value": 1204
}]
}4.5.1.3 Get All Fund Balances
URLs and Parameters
GET http://localhost/mws/rest/funds/balances?proxy-user=<USER>[&custom-fields=health][&filter={"project":"chemistry"}][&filter-type=NonExclusive]
| Parameter | Required | Valid Values | Description | Example |
|---|---|---|---|---|
| proxy-user | Yes | String | Perform action as defined MAM user. | proxy-user=amy |
| custom-fields | No | Comma-Separated String | Includes custom MAM fund attributes. | custom-fields=health |
| filter | No | JSON | Query funds based on defined MAM filter. | filter={"project":"chemistry"} |
| filter-type | No | String | Query funds based on defined MAM filter type. | filter-type=NonExclusive |
Sample Response
The fund balances resource is an aggregation of fund data. See the FundBalance API page for more details.GET http://localhost/mws/rest/funds/balances?proxy-user=amy
{
"totalCount": 2,
"resultCount": 2,
"results": [
{
"id": 2,
"name": 1204,
"priority": 0,
"description": "R&D for Manufacturing",
"creationTime": "2012-02-02 09:34:42 MST",
"amount": 9060000,
"deposited": 9060000,
"creditLimit": 0,
"reserved": 0,
"allocations": [
{
"id": 2,
"amount": 9060000,
"creditLimit": 0,
"deposited": 9060000
}
],
"fundConstraints": [
{
"id": 2,
"name": "CostCenter",
"value": 1204
}
],
"balance": 9060000,
"available": 9060000,
"allocated": 9060000,
"used": 0,
"percentRemaining": 100,
"percentUsed": 0
},
{
"id": 5,
"name": "",
"priority": 0,
"description": "",
"creationTime": "2012-04-03 09:25:47 MDT",
"amount": 901290219001,
"deposited": 901290219021,
"creditLimit": 30,
"reserved": 84018308897.68,
"allocations": [
{
"id": 6,
"amount": 901290219001,
"creditLimit": 30,
"deposited": 901290219021
}
],
"fundConstraints": [],
"balance": 817271910103.32,
"available": 817271910133.32,
"allocated": 901290219051,
"used": 20,
"percentRemaining": 100,
"percentUsed": 0
}
]
}4.5.1.4 Get Fund Statement
URLs and Parameters
GET http://localhost/mws/rest/funds/reports/statement?proxy-user=<USER>[&filter=<FILTER>][&filter-type=<FILTER-TYPE>][&start-time=<DATE-STRING>][&end-time=<DATE-STRING>][&context=<CONTEXT>]
| Parameter | Required | Valid Values | Description | Example |
|---|---|---|---|---|
| proxy-user | Yes | String | Perform action as defined MAM user. | proxy-user=amy |
| filter | No | JSON | Query funds based on defined MAM filter. | filter={"project":"chemistry"} |
| filter-type | No | String | Query funds based on defined MAM filter type. | filter-type=NonExclusive |
| start-time | No | Date, -infinity, or now | Filter allocations and transaction after a start time. | start-time=2012-04-03 15:24:39 MDT |
| end-time | No | Date, -infinity, or now | Filter allocations and transactions before an end time. | end-time=2012-04-03 15:24:39 MDT |
| context | No | hpc or cloud | The context to use in Moab Accounting Manager. | context=hpc |
TheSee Global URL Parameters for available URL parameters.contextparameter overrides the default context set for MAM using themam.contextconfiguration parameter. See the Configuration page for more information on this parameter.
Sample Response
The fund statement report provides a snapshot of the current funds. See the FundStatement API for more details.GET http://localhost/mws/rest/funds/reports/statement?proxy-user=amy&fields=startBalance,endBalance
{
"startBalance":1234.01,
"endBalance":1000
}4.5.1.5 Get Fund Statement Summary
URLs and Parameters
GET http://localhost/mws/rest/funds/reports/statement/summary?proxy-user=<USER>[&filter=<FILTER>][&filter-type=<FILTER-TYPE>][&start-time=<DATE-STRING>][&end-time=<DATE-STRING>]
| Parameter | Required | Valid Values | Description | Example |
|---|---|---|---|---|
| proxy-user | Yes | String | Perform action as defined MAM user. | proxy-user=amy |
| filter | No | JSON | Query funds based on defined MAM filter. | filter={"project":"chemistry"} |
| filter-type | No | String | Query funds based on defined MAM filter type. | filter-type=NonExclusive |
| start-time | No | Date, -infinity, or now | Filter allocations and transaction after a start time. | start-time=2012-04-03 15:24:39 MDT |
| end-time | No | Date, -infinity, or now | Filter allocations and transactions before an end time. | end-time=2012-04-03 15:24:39 MDT |
Sample Response
The fund statement summary is slightly different from the typical fund statement in that the transactions are provided as summaries grouped byobject and action. See the
FundStatementSummary API for more details.GET http://localhost/mws/rest/funds/reports/statement/summary?proxy-user=amy&fields=totalCredits,totalDebits,transactions.action,transactions.amount,transactions.count
{
"totalCredits":200.02,
"totalDebits":-100,
"transactions":[ {
"action":"Deposit",
"amount":200.02,
"count":2
}, {
"action":"Charge",
"amount":-100,
"count":1
}
]
}4.6 Images
This section describes behavior of the Image resource in Moab Web Services. An image resource is used to track the different types of operating systems and hypervisors available in the data center. It also tracks which virtual machines are available on the hypervisors. This section describes the URLs, request bodies, and responses delivered to and from Moab Web Services.The Image API contains the type and description of all fields in the Image object. It also contains details regarding which fields are valid during PUT and POST actions.
Supported Methods
| Resource | GET | PUT | POST | DELETE |
|---|---|---|---|---|
| /rest/images | Get All Images | Create Image | ||
| /rest/images/id | Get Specified Image | Modify Image | Delete Image | |
| /rest/images/name | Get Specified Image | Modify Image | Delete Image |
4.6.1 Getting Images
The HTTP GET method is used to retrieve Image information. You can query all objects or a single object.Quick Reference
GET http://localhost/mws/rest/images[?query={"field":"value"}&sort={"field":<1|-1>}]
GET http://localhost/mws/rest/images/<id>
GET http://localhost/mws/rest/images/<name>4.6.1.1 Get All Images
URLs and Parameters
GET http://localhost/mws/rest/images[?query={"field":"value"}&sort={"field":<1|-1>}]| Parameter | Required | Valid Values | Description | Example |
|---|---|---|---|---|
| query | No | JSON | Queries for specific results. | query={"type":"stateful","osType":"linux"} |
| sort | No | JSON | Sort the results. Use 1 for ascending and -1 for descending. | sort={"name":-1} |
Sample Response
GET http://localhost/mws/rest/images?fields=id,name
{
"totalCount": 1,
"resultCount": 1,
"results": [ {
"id": "4fa197e68ca30fc605dd1cf0",
"name": "centos5-stateful"
}]
}Sorting and Querying
See the sorting and querying sections of Global URL Parameters.4.6.1.2 Get Single Image
URLs and Parameters
GET http://localhost/mws/rest/images/<id> GET http://localhost/mws/rest/images/<name>
| Parameter | Required | Type | Valid Values | Description |
|---|---|---|---|---|
| id | Yes | String | - | The unique identifier of the Image. |
| name | Yes | String | - | The name of the Image. |
You must specify either id or name, but you do not have to specify both.
Sample Response
GET http://localhost/mws/rest/images/centos5-compute-stateful
{
"active":true,
"extensions":{
"xcat":{
"os":"centos",
"architecture":"x86_64",
"profile":"compute"
}
},
"features":[],
"hypervisor":false,
"id":"4fa197e68ca30fc605dd1cf0",
"name":"centos5-compute-stateful",
"osType":"linux",
"supportsPhysicalMachine":false,
"supportsVirtualMachine":true,
"templateName":"",
"type":"stateful",
"version":0,
"virtualizedImages":[]
}
The version field contains the current version of the database entry and does not
reflect the version of the operating system. See Modify Image for more
information.
4.6.2 Creating Images
The HTTP POST method is used to submit Images.Quick Reference
POST http://localhost/mws/rest/images
4.6.2.1 Create Single Image
URLs and Parameters
POST http://localhost/mws/rest/images
Request Body
Three fields are required to submit an image: name, hypervisor, and osType. Each image must also support provisioning to either a physical machine or a virtual machine by using the supportsPhysicalMachine or supportsVirtualMachine fields.The name field must contain only letters, digits, periods, dashes, and underscores.The array of virtualized images are themselves objects that contain image IDs or names. For more information on available fields and types, see the Image API.The following is an example of the most basic image that can be created:
POST http://localhost/mws/rest/images
{
"name": "centos5-stateful",
"osType": "linux",
"hypervisor": false,
"supportsVirtualMachine":true
}xcat and must contain certain fields.
These extension keys are documented in the Image API. See the following
examples of creating images with xCAT-specific provisioning information below.Sample Response
If the request was successful, the response body is the new image that was created exactly as shown in Get Single Image. On failure, the response is an error message.Samples
The virtualizedImages field only accepts input when the image is a hypervisor and expects an array of image IDs or names, as shown in the following example:Example payload of hypervisor with 2 vms
{
"hypervisor":true,
"name":"esx5-stateful",
"osType":"linux",
"supportsPhysicalMachine":true,
"type":"stateful",
"virtualizedImages": [
{"id": "4fa197e68ca30fc605dd1cf0"},
{"name": "centos5-stateful"}
]
}linkedclone in order to set the templateName field.)VM Utilizing a Cloned Template
{
"active": true,
"hypervisor": false,
"name": "centos5-compute-stateful",
"osType": "linux",
"type": "linkedclone",
"supportsVirtualMachine":true,
"templateName":"centos5-compute"
}xCAT Virtual Machine Image
{
"active": true,
"features": [],
"hypervisor": false,
"name": "centos5-compute-stateful",
"osType": "linux",
"type": "stateful",
"supportsVirtualMachine":true,
"extensions": {
"xcat": {
"os": "centos",
"architecture": "x86_64",
"profile": "compute"
}
}
}xCAT Hypervisor Image
{
"active": true,
"features": [],
"hypervisor": true,
"name": "esxi5-base-stateless",
"osType": "linux",
"virtualizedImages": [
{"name": "centos5-compute-stateless"}
],
"type": "stateless",
"supportsPhysicalMachine":true,
"extensions": {
"xcat": {
"os": "esxi5",
"architecture": "x86_64",
"profile": "base",
"hvType": "esx",
"hvGroupName": "esx5hv",
"vmGroupName": "esx5vm"
}
}
}4.6.3 Modifying Images
The HTTP PUT method is used to modify Images.Quick Reference
PUT http://localhost/mws/rest/images/<id> PUT http://localhost/mws/rest/images/<name>
4.6.3.1 Modify Single Image
URLs and Parameters
PUT http://localhost/mws/rest/image/<id> PUT http://localhost/mws/rest/image/<name>
| Parameter | Required | Type | Valid Values | Description |
|---|---|---|---|---|
| id | Yes | String | - | The unique identifier of the Image. |
| name | Yes | String | - | The name of the Image. |
- You must specify either id or name, but you do not have to specify both.
- The name field must contain only letters, digits, periods, dashes, and underscores.
Example Request
PUT http://locahost/mws/rest/image/centos5-stateful
{
"name": "centos5-stateful",
"type": "stateful",
"hypervisor": false,
"osType": "linux",
"virtualizedImages": []
}The version field contains the current version of the database entry and does not reflect the version of the operating system. This field cannot be updated directly. However, if version is included in the modify request, it will be used to verify that another client did not update the object in between the time the data was retrieved and the modify request was delivered.
Sample Response
If the request was successful, the response body is the modified image as shown in Get Single Image. On failure, the response is an error message.4.6.4 Deleting Images
The HTTP DELETE method is used to delete Images.Quick Reference
DELETE http://localhost/mws/rest/images/<id> DELETE http://localhost/mws/rest/images/<name>
4.6.4.1 Delete Single Image
URLs and Parameters
DELETE http://localhost/mws/rest/image/<id> DELETE http://localhost/mws/rest/image/<name>
| Parameter | Required | Type | Valid Values | Description |
|---|---|---|---|---|
| id | Yes | String | - | The unique identifier of the Image. |
| name | Yes | String | - | The name of the Image. |
Only one of id or name are required.
Sample Response
JSON Response
{}4.7 Jobs
This section describes behavior of the Job object in Moab Web Services. It contains the URLs, request bodies, and responses delivered to and from Moab Web Services.The Job API contains the type and description of all fields in the Job object. It also contains details regarding which fields are valid during PUT and POST actions.
Supported Methods
| Resource | GET | PUT | POST | DELETE |
|---|---|---|---|---|
| /rest/jobs | Get all jobs | Submit new job | ||
| /rest/jobs/active | Get all active jobs | |||
| /rest/jobs/complete | Get all complete jobs | |||
| /rest/jobs/id | Get specified job | Modify job | Cancel job | |
| /rest/jobs/active/id | Get specified active job | |||
| /rest/jobs/complete/id | Get specified complete job |
4.7.1 Getting Job Information
The HTTP GET method is used to retrieve Job information. Queries for all objects and a single object are available.Quick Reference
GET http://localhost/mws/rest/jobs/<id>4.7.1.1 Get All Jobs
URLs and Parameters
GET http://localhost/mws/rest/jobs
Sample Response
JSON Response
{
"totalCount": 1,
"resultCount": 1,
"results": [ {
"id": "...",
…
}]
}Samples
GET http://localhost/mws/rest/jobs?fields=id,state,flags
{
"totalCount": 3,
"resultCount": 3,
"results": [
{
"id": "job.1",
"state": "IDLE",
"flags": ["PREEMPTABLE"]
},
{
"id": "job.2",
"state": "RUNNING",
"flags": []
},
{
"id": "job.3",
"state": "REMOVED",
"flags": [
"PREEMPTABLE",
"RESTARTABLE"
]
}
]
}Known Issues
- Some jobs are not returned if
DisplayFlags UseBlockingis set in themoab.cfgfile.
4.7.1.2 Get All Active Jobs
URLs and Parameters
GET http://localhost/mws/rest/jobs/active
Sample Response
Same as Get All.4.7.1.3 Get All Complete Jobs
URLs and Parameters
GET http://localhost/mws/rest/jobs/complete
Sample Response
Same as Get All.Known Issues
This query can take a long time and slow down the Moab Workload Manager, especially on systems with many completed jobs. Avoid this query if possible.4.7.1.4 Get Single Job
URLs and Parameters
GET http://localhost/mws/rest/jobs/<id>| Parameter | Required | Type | Valid Values | Description |
|---|---|---|---|---|
| id | Yes | String | - | The unique identifier of the object. |
Sample Response
JSON Response
{
"account": "account",
"activeDuration": 150,
"allocatedNodes": [{"id": "node01"}],
"allocatedVMs": [{"id": "vm1"}],
"blockReason": {
"message": "Check valid user",
"type": "BADUSER"
},
"bypass": 5,
"commandFile": "/tmp/test.sh",
"commandLineArguments": "-x -v",
"completionCode": 0,
"completionDate": "2011-11-08 13:18:47 MST",
"dedicatedProcessorSeconds": 1.5,
"destinationRmJobId": "1000011",
"earliestStartDate": "2011-11-08 13:18:47 MST",
"earliestStartDateRequested": "2011-11-08 13:18:47 MST",
"effectivePartitionAccessList": ["ALL"],
"effectiveQueueDuration": 600,
"emailNotifyTypes": ["END"],
"emailNotifyUsers": ["[email protected]"],
"environmentVariables": {"var1": "val1"},
"expectedState": "IDLE",
"flags": ["RESTARTABLE"],
"genericAttributes": ["attr1"],
"group": "group",
"holds": ["USER"],
"hosts": ["host1"],
"id": "Moab.1",
"initialWorkingDirectory": "/tmp",
"latestCompletedDateRequested": "2011-11-08 13:18:47 MST",
"masterHost": "masterHost",
"memoryRequested": 1024,
"messages": [ {
"creationTime": null,
"expireTime": null,
"index": 0,
"message": "Message one",
"messageCount": 0,
"author": "moab",
"priority": 0
}],
"name": "myJob",
"os": "linux",
"partitionAccessList": ["ALL"],
"qos": "QOS1",
"qosRequested": "QOS1",
"queue": "BATCH",
"queueStatus": "ACTIVE",
"durationRequested": 300,
"requirements": [ {
"allocatedNodes": [{"id": "node01"}],
"allocatedPartition": "",
"genericResources": {
"resource1": 10,
"resource2": 30
},
"nodeAccessPolicy": null,
"preferredNodeFeatures": [],
"requiredArchitecture": "",
"requiredClass": "",
"requiredDiskPerTask": 0,
"requiredMemoryPerTask": 0,
"requiredNetwork": "",
"requiredNodeCountMinimum": 0,
"requiredNodeDisk": 0,
"requiredNodeFeatures": [],
"requiredNodeMemory": 0,
"requiredNodeProcessors": 0,
"requiredNodeSwap": 0,
"requiredPartition": "",
"requiredProcessorCountMinimum": 4,
"requiredProcessorsPerTask": 0,
"requiredSwapPerTask": 0,
"tasksPerNode": 0
}],
"reservationRequested": "rsv.1",
"reservationStartDate": "2011-11-08 13:18:47 MST",
"rmExtension": "x=PROC=4",
"rmName": "torque",
"rmStandardErrorFilePath": "/tmp/error.out",
"rmStandardInputFilePath": "/tmp/input.in",
"rmStandardOutputFilePath": "/tmp/output.out",
"runPriority": 5,
"sourceRmJobId": "1000011",
"standardErrorFilePath": "/tmp/job.error.out",
"standardOutputFilePath": "/tmp/job.output.out",
"startCount": 1,
"startDate": "2011-11-08 13:18:47 MST",
"startPriority": 2,
"state": "COMPLETED",
"submitDate": "2011-11-08 13:18:47 MST",
"submitHost": "admin-node",
"suspendDuration": 60,
"systemPriority": 6,
"userPriority": 5,
"user": "saadmin",
"variables": {"var1": "val1"},
"virtualContainers": [{"id":"vc1"}],
"vmUsagePolicy": "CREATEVM"
}4.7.1.5 Get Single Active Job
URLs and Parameters
GET http://localhost/mws/rest/jobs/active/<id>| Parameter | Required | Type | Valid Values | Description |
|---|---|---|---|---|
| id | Yes | String | - | The unique identifier of the object. |
Sample Response
Same as Get Single.4.7.1.6 Get Single Active Job
URLs and Parameters
GET http://localhost/mws/rest/jobs/complete/<id>| Parameter | Required | Type | Valid Values | Description |
|---|---|---|---|---|
| id | Yes | String | - | The unique identifier of the object. |
Sample Response
Same as Get Single.4.7.2 Submitting Jobs
The HTTP POST method is used to submit Jobs.Quick Reference
POST http://localhost/mws/rest/jobs[?proxy-user=<username>]Restrictions
- The user given in
usermust have read access to the file given incommandFile. - No more than one virtual container can be specified in the request. The virtual container must already exist.
- The
userandgroupproperties are used to submit a job as the specified user belonging to the specified group. - Job
variableshave the following restrictions: variablenames cannot contain equals (=), semicolon (;), colon (:), plus (+), question mark (?), caret (^), backslash (\), or white space.variablevalues cannot contain semicolon (;), colon (:), plus (+), or caret (^).- When submitting jobs, the only supported hold type is
USER. - The proxy-user parameter is ignored unless you set
ENABLEPROXY=TRUEin themoab.cfgfile. Example:
ADMINCFG[1] USERS=root,ted ENABLEPROXY=TRUE
4.7.2.1 Submit Job with Host List
URLs and Parameters
POST http://localhost/mws/rest/jobs[?proxy-user=<username>]| Parameter | Required | Type | Valid Values | Description |
|---|---|---|---|---|
| proxy-user | No | String | - | Perform the action as this user. |
Request Body
To submit a job with a specified host list, only two fields are required:commandFile and hosts.The request body below shows all the fields that are available during job submission.JSON Request Body (specified host list)
{
"account": "project name",
"commandFile": "/tmp/myscript.sh",
"commandLineArguments": "-x",
"earliestStartDateRequested": "2011-09-26 16:28:20 MDT",
"emailNotifyTypes": ["END"],
"emailNotifyUsers": ["[email protected]"],
"environmentRequested": true,
"environmentVariables": {
"SHELL": "/bin/bash",
"LC_ALL": "en_US.utf8"
},
"flags": [
"SUSPENDABLE",
"BESTEFFORT"
],
"group": "wheel",
"holds": ["USER"],
"hosts": [
"node2",
"node3"
],
"initialWorkingDirectory": "/tmp",
"name": "job name",
"os": "Ubuntu",
"qosRequested": "highprio",
"queue": "priority",
"durationRequested": 3600,
"requirements": [ {
"genericResources": {
"resource1": 10,
"resource2": 30
},
"nodeAccessPolicy": "SHARED",
"requiredArchitecture": "x86_64",
"requiredDiskPerTask": 500,
"requiredMemoryPerTask": 1024,
"requiredNodeFeatures": ["bluray"],
"requiredPartition": "cs",
"requiredProcessorsPerTask": 3,
"requiredSwapPerTask": 600,
"tasksPerNode": 8
}],
"reservationRequested": "grid.3",
"standardErrorFilePath": "/home/jacob/err",
"standardOutputFilePath": "/home/jacob/out",
"submitHost": "admin-node",
"templateList": [
"template1",
"template2"
],
"user": "jacob",
"userPriority": 25,
"variables": {
"var1": "val1",
"var2": "val2"
},
"virtualContainers": [{"id": "vc1"}],
"vmUsagePolicy": "REQUIREPM"
}Sample Response
The response of this task is one of three possibilities:- An object with a single
messagesproperty containing a list of error messages on failure
{"messages":["Could not create job - invalid requirements"]}- An object with an
idproperty containing the ID of the newly created job
{"id":"Moab.1"}- An object with an
idproperty and avirtualContainerslist containing the ID of the newly created virtual container
{"id":"Moab.1","virtualContainers":[{"id":"vc1"}]}The virtual container will only be reported when a new virtual container has been created by Moab for the job.
4.7.2.2 Submit Job with Node Count
URLs and Parameters
POST http://localhost/mws/rest/jobs[?proxy-user=<username>]| Parameter | Required | Type | Valid Values | Description |
|---|---|---|---|---|
| proxy-user | No | String | - | Perform the action as this user. |
Request Body
To submit a job with a specified node count, only two fields are required:commandFile and requiredProcessorCountMinimum (in the requirements array).The request body below shows all the fields that are available during job submission.JSON Request Body (specified node count)
{
"account": "project name",
"commandFile": "/tmp/myscript.sh",
"commandLineArguments": "-x",
"earliestStartDateRequested": "2011-09-26 16:28:20 MDT",
"emailNotifyTypes": ["END"],
"emailNotifyUsers": ["[email protected]"],
"environmentRequested": true,
"environmentVariables": {
"SHELL": "/bin/bash",
"LC_ALL": "en_US.utf8"
},
"flags": [
"SUSPENDABLE",
"BESTEFFORT"
],
"group": "wheel",
"holds": ["USER"],
"initialWorkingDirectory": "/tmp",
"name": "job name",
"os": "Ubuntu",
"qosRequested": "highprio",
"queue": "priority",
"durationRequested": 3600,
"requirements": [ {
"genericResources": {
"resource1": 10,
"resource2": 30
},
"nodeAccessPolicy": "SHARED",
"requiredArchitecture": "x86_64",
"requiredDiskPerTask": 500,
"requiredMemoryPerTask": 1024,
"requiredNodeFeatures": ["bluray"],
"requiredPartition": "cs",
"requiredProcessorCountMinimum": 4,
"requiredProcessorsPerTask": 3,
"requiredSwapPerTask": 600,
"tasksPerNode": 8
}],
"reservationRequested": "grid.3",
"standardErrorFilePath": "/home/jacob/err",
"standardOutputFilePath": "/home/jacob/out",
"submitHost": "admin-node",
"templateList": [
"template1",
"template2"
],
"user": "jacob",
"userPriority": 25,
"variables": {
"var1": "val1",
"var2": "val2"
},
"virtualContainers": [{"id": "vc1"}],
"vmUsagePolicy": "REQUIREPM"
}Sample Response
The response of this task is the same as submitting a job with a host list.4.7.2.3 Examples of Job Submission
This section includes some sample job submission requests.Submit job to run on node2 and node3
POST http://localhost/mws/rest/jobs
{
"commandFile": "/tmp/test.sh",
"group": "adaptive",
"hosts": [ "node2", "node3" ]
"initialWorkingDirectory": "/tmp",
"user": "adaptive",
}Submit job that requires 20 processors
POST http://localhost/mws/rest/jobs
{
"commandFile": "/tmp/test.sh",
"group": "adaptive",
"initialWorkingDirectory": "/tmp",
"requirements": [{"requiredProcessorCountMinimum": "20"}]
"user": "adaptive",
}Submit job to run after a certain time
POST http://localhost/mws/rest/jobs
{
"commandFile": "/tmp/test.sh",
"earliestStartDateRequested": "2012-08-26 16:28:20 MDT",
"group": "adaptive",
"initialWorkingDirectory": "/tmp",
"requirements": [{"requiredProcessorCountMinimum": "20"}]
"user": "adaptive",
}Submit job based on msub example
Given this msub command:
msub -l nodes=3:ppn=2,walltime=1:00:00,pmem=100 script2.pbs.cmd
POST http://localhost/mws/rest/jobs
{
"user": "adaptive",
"group": "adaptive",
"initialWorkingDirectory": "/home/adaptive",
"commandFile": "/home/adaptive/script2.pbs.cmd",
"requirements": [ {
"requiredProcessorCountMinimum": 6,
"tasksPerNode": 2,
"requiredMemoryPerTask": 100
}],
"durationRequested": 3600
}
- To emulate what
msubdoes, makecommandFilean absolute path, and adduser,group, andinitialWorkingDirectory.- As shown above,
nodes=3:ppn=2is equivalent to settingrequiredProcessorCountMinimumto 6 andtasksPerNodeto 2.
4.7.3 Modifying Jobs
The HTTP PUT method is used to modify Jobs.Quick Reference
PUT http://localhost/mws/rest/jobs/<id>[/<modifyAction>][?proxy-user=<username>]
Restrictions
- The proxy-user parameter is ignored unless you set
ENABLEPROXY=TRUEin themoab.cfgfile. Example:
ADMINCFG[1] USERS=root,ted ENABLEPROXY=TRUE
4.7.3.1 Modify Job Attributes
URLs and Parameters
PUT http://localhost/mws/rest/jobs/<id>[?proxy-user=<username>]
| Parameter | Required | Type | Valid Values | Description |
|---|---|---|---|---|
| id | Yes | String | - | The unique identifier of the object. |
| proxy-user | No | String | - | Perform the action as this user. |
Request Body
The request body below shows all the fields that are available when modifying a Job, along with some sample values.JSON Request Body
{
"account": "engineering",
"earliestStartDateRequested": "2011-08-24 15:02:00",
"flags": [
"RESTARTABLE",
"SUSPENDABLE"
],
"holds": ["USER"],
"messages": [
{"message": "First message"},
{"message": "Second message"}
],
"name": "EngineeringJob",
"qosRequested": "NORMAL",
"queue": "BATCH",
"durationRequested": 600,
"requirements": [{"requiredPartition": "msm"}],
"reservationRequested": "rsv.1",
"trigger": "triggerString",
"userPriority": 10,
"variables": {
"var1": "val1",
"var2": "val2"
}
}Sample Response
These messages may not match the messages returned from Moab exactly, but are given as an example of the structure of the response.
Not all messages are shown for the above request body.
JSON Response
{
"messages":[
"Account modified successfully",
"Messages modified successfully",
"Variables modified successfully"
]
}Restrictions
- Old messages are not removed from jobs; only new messages are added.
- Job
variableshave the restrictions documented in Submitting Jobs
4.7.3.2 Perform Actions on Job
URLs and Parameters
PUT http://localhost/mws/rest/jobs/<id>/<modifyAction>[?proxy-user=<username>]
| Parameter | Required | Type | Valid Values | Description |
|---|---|---|---|---|
| id | Yes | String | - | The unique identifier of the object. |
| modifyAction | Yes | String | cancel | Attempts to cancel the job. |
| checkpoint | Attempts to checkpoint the job. Note that the OS must support checkpointing for this to work. | |||
| execute | Executes the job if possible. | |||
| hold | Attempts to hold the job using the holds set in the request body. | |||
| requeue | Attempts to requeue the job. | |||
| resume | Attemps to resume the job. | |||
| suspend | Attempts to suspend the job. | |||
| unhold | Attempts to release the holds set in the request body. | |||
| proxy-user | No | String | - | Perform the action as this user. |
Performing a cancel function on a job is equivalent to deleting a job.See Global URL Parameters for available URL parameters.
Request Body
Request bodies are only required for holding or unholding jobs. All other actions do not require request bodies of any kind.JSON Request Body to Add Holds to a Job
{
"holds": ["USER"]
}JSON Request Body to Remove Holds from a Job
{
"holds": ["USER"]
}If no holds are specified when unholding a job, all holds will be removed. This is equivalent to specifyingholdsas a list with a single element ofALL.
Sample Response
This message may not match the message returned from Moab exactly, but is given as an example of the structure of the response.
JSON Response
{
"messages":[
"Job modified successfully"
]
}4.7.4 Deleting (Canceling) Jobs
The HTTP DELETE method is used to cancel Jobs.Quick Reference
DELETE http://localhost/mws/rest/jobs/<id>[?proxy-user=<username>]
Restrictions
- The proxy-user parameter is ignored unless you set
ENABLEPROXY=TRUEin themoab.cfgfile. Example:
ADMINCFG[1] USERS=root,ted ENABLEPROXY=TRUE
4.7.4.1 Cancel Job
URLs and Parameters
DELETE http://localhost/mws/rest/jobs/<id>[?proxy-user=<username>]
| Parameter | Required | Type | Valid Values | Description |
|---|---|---|---|---|
| id | Yes | String | - | The unique identifier of the object. |
| proxy-user | No | String | - | Perform the action as this user. |
Sample Response
JSON Response for successful DELETE
{}
Additional information about the DELETE can be found in the HTTP response header X-MWS-Message.
4.8 Job Templates
This section describes behavior of the Job Template object in Moab Web Services. It contains the URLs, request bodies, and responses delivered to and from Moab Web Services.The Job Template API contains the type and description of all fields in the Job Template object. It also contains details regarding which fields are valid during PUT and POST actions.
Supported Methods
| Resource | GET | PUT | POST | DELETE |
|---|---|---|---|---|
| /rest/job-templates | Get all job templates | |||
| /rest/job-templates/id | Get specified job template |
4.8.1 Getting Job Templates
The HTTP GET method is used to retrieve Job Template information. Queries for all objects and a single object are available.Quick Reference
GET http://localhost/mws/rest/job-templates/<id>4.8.1.1 Get All Job Templates
URLs and Parameters
GET http://localhost/mws/rest/job-templates
Sample Response
GET http://localhost/mws/rest/job-templates?fields=id
{
"totalCount": 14,
"resultCount": 14,
"results": [
{"id": "DEFAULT"},
{"id": "genericVM"},
{"id": "genericVM-setup"},
{"id": "genericVM-destroy"},
{"id": "genericVM-migrate"},
{"id": "genericPM"},
{"id": "genericPM-setup"},
{"id": "genericPM-destroy"},
{"id": "OSStorage"},
{"id": "OSStorage-setup"},
{"id": "OSStorage-destroy"},
{"id": "extraStorage"},
{"id": "extraStorage-setup"},
{"id": "extraStorage-destroy"}
]
}4.8.1.2 Get Single Job Template
URLs and Parameters
GET http://localhost/mws/rest/job-templates/<id>| Parameter | Required | Type | Valid Values | Description |
|---|---|---|---|---|
| id | Yes | String | - | The unique identifier of the object. |
Sample Response
JSON Response
{
"account": "account",
"args": "arg1 arg2",
"commandFile": "/tmp/script",
"description": "description",
"genericSystemJob": true,
"id": "genericVM",
"inheritResources": false,
"jobDependencies": [ {
"name": "genericVM-setup",
"type": "JOBSUCCESSFULCOMPLETE"
}],
"jobFlags": ["VMTRACKING"],
"jobTemplateFlags": ["SELECT"],
"jobTemplateRequirements": [ {
"architecture": "x86_64",
"diskRequirement": 500,
"genericResources": {"tape": 3},
"nodeAccessPolicy": "SINGLEJOB",
"operatingSystem": "Ubuntu 10.04.3",
"requiredDiskPerTask": 200,
"requiredFeatures": ["dvd"],
"requiredMemoryPerTask": 1024,
"requiredProcessorsPerTask": 2,
"requiredSwapPerTask": 512,
"taskCount": 4
}],
"priority": 20,
"qos": "qos",
"queue": "queue",
"durationRequested": 600,
"select": true,
"trigger": null,
"version": 0,
"vmUsagePolicy": "REQUIREPM"
}4.9 Metric Types
This section describes behavior of the Metric Type object in Moab Web Services. It contains the URLs, request bodies, and responses delivered to and from Moab Web Services.The MetricType API contains the type and description of all fields in the Metric Type object.
Supported Methods
| Resource | GET | PUT | POST | DELETE |
|---|---|---|---|---|
| /rest/metric-types | Get all metric types |
4.9.1 Getting Metric Types
The HTTP GET method is used to retrieve Metric Type information.Quick Reference
GET http://localhost/mws/rest/metric-types
4.9.1.1 Get All Metric Types
URLs and Parameters
GET http://localhost/mws/rest/metric-types
Sample Response
GET http://localhost/mws/rest/metric-types?fields=id
{
"totalCount": 9,
"resultCount": 9,
"results": [
{"id": "vmcount"},
{"id": "watts"},
{"id": "pwatts"},
{"id": "temp"},
{"id": "cpu"},
{"id": "mem"},
{"id": "io"},
{"id": "ccores"},
{"id": "threads"}
]
}4.10 Nodes
This section describes behavior of the Node object in Moab Web Services. It contains the URLs, request bodies, and responses delivered to and from Moab Web Services.The Node API contains the type and description of all fields in the Node object. It also contains details regarding which fields are valid during PUT and POST actions.
Supported Methods
| Resource | GET | PUT | POST | DELETE |
|---|---|---|---|---|
| /rest/nodes | Get all nodes | |||
| /rest/nodes/id | Get specified node | Modify node |
4.10.1 Getting Nodes
The HTTP GET method is used to retrieve Node information. Queries for all objects and a single object are available.Quick Reference
GET http://localhost/mws/rest/nodes/<id>4.10.1.1 Get All Nodes
URLs and Parameters
GET http://localhost/mws/rest/nodes
Sample Response
GET http://localhost/mws/rest/nodes?fields=id
{
"totalCount": 3,
"resultCount": 3,
"results": [
{"id": "node1"},
{"id": "node2"},
{"id": "node3"}
]
}4.10.1.2 Get Single Node
URLs and Parameters
GET http://localhost/mws/rest/nodes/<id>| Parameter | Required | Type | Valid Values | Description |
|---|---|---|---|---|
| id | Yes | String | - | The unique identifier of the object. |
Sample Response
JSON Response
{
"accessPolicy": null,
"aliases": [],
"architecture": "",
"availableClasses": [],
"availableDisk": -1,
"availableEndDate": null,
"availableGenericResources": {},
"availableMemory": -1,
"availableProcessors": -1,
"availableStartDate": null,
"availableSwap": -1,
"blockReason": "",
"comments": "",
"configuredClasses": [],
"cpuLoad": 0,
"dynamic": false,
"externalLoad": 0,
"features": [],
"flags": [
"VM_CREATE_ENABLED",
"RM_DETECTED"
],
"genericEvents": [],
"genericMetrics": {},
"genericResources": {},
"hypervisorType": "",
"iOLoad": 0,
"id": "",
"index": -1,
"jobs": [{"id": "Moab.1"}],
"lastStateUpdateDate": null,
"lastUpdateDate": null,
"maxIOIn": 0,
"maxIOLoad": 0,
"maxIOOut": 0,
"maxJob": 0,
"maxJobPerUser": 0,
"maxLoad": 0,
"maxPEPerJob": 0,
"maxPageIn": 0,
"maxPageOut": 0,
"maxProc": 0,
"maxProcPerClass": 0,
"messages": [],
"network": "",
"networkAddress": "",
"networkLoad": 0,
"nextOS": "",
"operations": [],
"os": "",
"osList": [],
"overcommit": null,
"partition": "",
"power": null,
"powerPolicy": null,
"powerSelected": null,
"priority": 0,
"priorityFunction": "",
"procSpeed": 0,
"profilingEnabled": false,
"rack": 0,
"reservationCount": 0,
"reservations": [],
"rmAccessList": "",
"size": 1,
"slot": 0,
"speed": 1,
"speedWeight": 1,
"state": null,
"substate": "",
"taskCount": -1,
"totalActiveTime": 0,
"totalAvailableTime": 0,
"totalDisk": -1,
"totalMemory": -1,
"totalProcessors": -1,
"totalStatsTime": 0,
"totalSwap": -1,
"totalUpTime": 0,
"type": "",
"variables": {},
"version": 0,
"virtualMachines": [{"id": "vm1"}],
"vmOsList": []
}4.10.2 Modifying Nodes
The HTTP PUT method is used to modify Nodes.Quick Reference
PUT http://localhost/mws/rest/nodes/<id>[?proxy-user=<username>]
Restrictions
- The proxy-user parameter is ignored unless you set
ENABLEPROXY=TRUEin themoab.cfgfile. Example:
ADMINCFG[1] USERS=root,ted ENABLEPROXY=TRUE
4.10.2.1 Modify Node
URLs and Parameters
PUT http://localhost/mws/rest/nodes/<id>[?proxy-user=<username>]
| Parameter | Required | Type | Valid Values | Description |
|---|---|---|---|---|
| id | Yes | String | - | The unique identifier of the object. |
| proxy-user | No | String | - | Perform the action as this user. |
Request Body
The request body below shows all the fields that are available when modifying a Node, along with some sample values.Sample JSON Request Body to Modify a Node
{
"genericEvents": [ {
"name": "event1",
"message": "Sample message"
}],
"genericMetrics": {
"metric1": 3,
"metric2": 5
},
"messages": [
"message1",
"message2"
],
"os": "linux",
"partition": "local",
"power": "off|on",
"state": "Busy",
"variables": {
"var1": "val1",
"var2": "val2"
}
}Sample Response
This message may not match the message returned from Moab exactly, but is given as an example of the structure of the response.
JSON Response
{"messages":[
"Successfully modified os to 'linux'",
"Successfully powered node off"
]}4.11 Pending Actions
This section describes behavior of the Pending Action object in Moab Web Services. It contains the URLs, request bodies, and responses delivered to and from Moab Web Services.The Pending Action API contains the type and description of all fields in the Pending Action object. It also contains details regarding which fields are valid during PUT and POST actions.
Supported Methods
| Resource | GET | PUT | POST | DELETE |
|---|---|---|---|---|
| /rest/pending-actions | Get all pending actions |
4.11.1 Getting Pending Actions
The HTTP GET method is used to retrieve Pending Action information.Quick Reference
GET http://localhost/mws/rest/pending-actions
4.11.1.1 Get All Pending Actions
URLs and Parameters
GET http://localhost/mws/rest/pending-actions
Sample Response
GET http://localhost/mws/rest/pending-actions
{
"totalCount": 1,
"resultCount": 1,
"results": [ {
"failureDetails": "",
"hosts": ["hv3"],
"id": "vmcreate-27",
"maxDurationInSeconds": 3600,
"migrationDestination": "",
"migrationSource": "",
"motivation": "requested by root",
"pendingActionState": "RUNNING",
"pendingActionType": "VMCREATE",
"requester": "root",
"serviceId": "Rhel55Vm.200",
"startTime": "2011-11-15 21:57:55 MST",
"substate": "installing",
"targetOS": "",
"topLevelServiceId": "Lamp.132",
"vmId": "vm8"
}]
}Generic vs Non-Generic Types
If generic job templates are used in Moab, MWS may be configured to translate pending actions with the generic type to the proper type such asVMCREATE. This is done in the configuration file.
The Quickstart Guide provides the default mappings
for this feature, as well as an example of adding a custom mapping from
a custom template name to the correct type.The default mappings are shown in the table below. The available pending
action types may be seen on the
PendingActionType API
page.| Template Name | Mapped Type |
|---|---|
| genericVM-setup | VMCREATE |
| genericVM-migrate | VMMIGRATE |
| genericVM-destroy | VMDESTROY |
| OSStorage-setup | VMSTORAGE |
| OSStorage-destroy | VMSTORAGEDESTROY |
| extraStorage-setup | STORAGE |
| extraStorage-destroy | STORAGEDESTROY |
| genericPM-setup | OSPROVISION |
When generic mappings are used, MWS will match the first template mapping that the pending action ID ends with. For example, an ID ofTo enable mapping for a custom template name such asMoab.1.genericVM-setupwill map the type toVMCREATE.
myCustomVM-setup,
simply add the following line to the MWS configuration file. The value of
the pending action type is case insensitive.
mws.pendingActions.mappings["myCustomVM-setup"] = "vmcreate"
mws.pendingActions.displayGeneric
setting as shown below. A false value will prevent generic pending
actions from being displayed, while a true value will display all
pending actions. By default this value is true.
mws.pendingActions.displayGeneric = false4.12 Plugins
This section describes behavior of the Plugin object in Moab Web Services. It contains the URLs, request bodies, and responses delivered to and from Moab Web Services.The PluginInstance API page contains the type and description of all fields in the Plugin object. It also contains details regarding which fields are valid during PUT and POST actions.
Supported Methods
| Resource | GET | PUT | POST | DELETE |
|---|---|---|---|---|
| /rest/plugins | Get all plugins | Create new plugin | ||
| /rest/plugins/id | Get specified plugin | Modify plugin | Delete plugin | |
| /rest/plugins/id/poll | Trigger Plugin Poll | |||
| /rest/plugins/id/services/serviceName | Access Web Service | Access Web Service | Access Web Service | Access Web Service |
4.12.1 Getting Plugins
The HTTP GET method is used to retrieve Plugin information. Queries for all objects and a single object are available.Quick Reference
GET http://localhost/mws/rest/plugins
GET http://localhost/mws/rest/plugins/<id>4.12.1.1 Get All Plugins
URLs and Parameters
GET http://localhost/mws/rest/plugins
Sample Response
GET http://localhost/mws/rest/plugins?fields=id
{
"totalCount": 3,
"resultCount": 3,
"results": [
{"id": "plugin1"},
{"id": "plugin2"},
{"id": "plugin3"}
]
}4.12.1.2 Get Single Plugin
URLs and Parameters
GET http://localhost/mws/rest/plugins/<id>| Parameter | Required | Type | Valid Values | Description |
|---|---|---|---|---|
| id | Yes | String | - | The unique identifier of the object. |
Sample Response
JSON Response
{
"id":"plugin1",
"pluginType":"Native",
"pollInterval":30,
"autoStart":true,
"config":{
"getJobs":"exec:///opt/moab/tools/workload.query.pl"
},
"state":"STARTED",
"nextPollDate":"2011-12-02 17:28:52 MST",
"lastPollDate":"2011-12-02 17:28:22 MST"
}4.12.2 Creating Plugins
The HTTP POST method is used to create Plugins.Quick Reference
POST http://localhost/mws/rest/plugins
4.12.2.1 Create Plugin
URLs and Parameters
POST http://localhost/mws/rest/plugins
Request Body
When creating a plugin, theid and pluginType fields are required. The request body below shows all
fields that are available when creating a Plugin, along with some sample values.JSON Request Body
{
"id":"plugin1",
"pluginType":"Native",
"pollInterval":30,
"autoStart":true,
"config":{
"getJobs":"exec:///opt/moab/tools/workload.query.pl"
}
}Sample Response
JSON Response for successful POST
{"id": "plugin1"}Restrictions
While it is possible to create a plugin with arbitrary nested configuration, such as:… "config":{ "nestedObject":{ "property1":"value1", "property2":"value2" }, "nestedList:["listItem1", "listItem2"] }
4.12.3 Modifying Plugins
The HTTP PUT method is used to modify Plugins. Additionally, the POST method may be used to trigger an immediate poll of a Plugin.Quick Reference
PUT http://localhost/mws/rest/plugins/<id> POST http://localhost/mws/rest/plugins/<id>/poll
4.12.3.1 Modify Plugin
URLs and Parameters
PUT http://localhost/mws/rest/plugins/<id>| Parameter | Required | Type | Valid Values | Description |
|---|---|---|---|---|
| id | Yes | String | - | The unique identifier of the object. |
Request Body
The request body below shows all the fields that are available when modifying a Plugin, along with some sample values.JSON Request Body for Plugin Modification
{
"state":"STARTED",
"pollInterval":30,
"autoStart":true,
"config":{
"getJobs":"exec:///opt/moab/tools/workload.query.pl"
},
"state":"STARTED"
}Sample Response
JSON Response
{"messages":["Plugin plugin1 updated", "Started Plugin 'plugin1'"]}4.12.3.2 Trigger Plugin Poll
URLs and Parameters
POST http://localhost/mws/rest/plugins/<id>/poll| Parameter | Required | Type | Valid Values | Description |
|---|---|---|---|---|
| id | Yes | String | - | The unique identifier of the object. |
Trigger Poll
This resource call will trigger an immediate poll of the specified plugin. It is equivalent to the same operation on the Monitoring and Lifecycle Controls page.Request Body
No request body is required.Sample Response
JSON Response
{"messages":["Polled Plugin with ID 'myPlugin'"]}4.12.4 Deleting Plugins
The HTTP DELETE method is used to delete Plugins.Quick Reference
DELETE http://localhost/mws/rest/plugins/<id>4.12.4.1 Delete Plugin
URLs and Parameters
DELETE http://localhost/mws/rest/plugins/<id>| Parameter | Required | Type | Valid Values | Description |
|---|---|---|---|---|
| id | Yes | String | - | The unique identifier of the object. |
Sample Response
JSON Response for successful DELETE
{}
Additional information about a successful DELETE can be found in the HTTP response header X-MWS-Message.
JSON Response for an unsuccessful DELETE
{"messages":["Plugin plugin1 could not be deleted", "Error message describing the problem"]}4.12.5 Accessing Plugin Web Services
All HTTP methods can be used to access Plugin Web Services. However, some services only support specific methods. Check the specific plugin type documentation for more information.Quick Reference
GET http://localhost/mws/rest/plugins/<id>/services/<serviceName> POST http://localhost/mws/rest/plugins/<id>/services/<serviceName> PUT http://localhost/mws/rest/plugins/<id>/services/<serviceName> DELETE http://localhost/mws/rest/plugins/<id>/services/<serviceName>
4.12.5.1 Access a Plugin Web Service
URLs and Parameters
GET http://localhost/mws/rest/plugins/<id>/services/<serviceName> POST http://localhost/mws/rest/plugins/<id>/services/<serviceName>
| Parameter | Required | Type | Valid Values | Description |
|---|---|---|---|---|
| id | Yes | String | - | The unique identifier of the object. |
| serviceName | Yes | String | - | The name of the web service, either in CamelCase or hyphenated. |
Web Service IDs
Translation is done to map CamelCase web service names to hyphenated names in the URL. For example, a web service method namednotifyEvent on a plugin with a name of notifications may be
called with the following URLs:// CamelCase /rest/plugins/notifications/services/notifyEvent// Hyphenated /rest/plugins/notifications/services/notify-event
HTTP Method and Request Body
Because plugin Custom Web Services do not need to distinguish which HTTP method is used, it is recommended to use GET and POST when making requests to access web services unless documented otherwise. The request body and output may vary for each web service called. See the plugin type documentation for the requested plugin for available web services, request parameters, and expected output.4.13 Plugin Types
This section describes behavior of the Plugin Type object in Moab Web Services. It contains the URLs, request bodies, and responses delivered to and from Moab Web Services.The PluginType API page contains the type and description of all fields in the Plugin Type object. It also contains details regarding which fields are valid during PUT and POST actions.
Supported Methods
| Resource | GET | PUT | POST | DELETE |
|---|---|---|---|---|
| /rest/plugin-types | Get all plugin types | Create or update plugin type | ||
| /rest/plugin-types/id | Get specified plugin type |
4.13.1 Getting Plugin Types
The HTTP GET method is used to retrieve Plugin Type information. Queries for all objects and a single object are available.Quick Reference
GET http://localhost/mws/rest/plugin-types/<id>4.13.1.1 Get All Plugin Types
URLs and Parameters
GET http://localhost/mws/rest/plugin-types
Sample Response
GET http://localhost/mws/rest/plugin-types?fields=id
{
"totalCount": 2,
"resultCount": 2,
"results": [
{"id": "MSM"},
{"id": "Native"}
]
}4.13.1.2 Get Single Plugin Type
URLs and Parameters
GET http://localhost/mws/rest/plugin-types/<id>| Parameter | Required | Type | Valid Values | Description |
|---|---|---|---|---|
| id | Yes | String | - | The unique identifier of the object. |
Sample Response
JSON Response
{
"author": "Adaptive Computing Enterprises, Inc.",
"description": "Polls a VMware® vCenter™ Server for information on the hypervisors and virtual machines it manages.",
"documentationLink": "",
"email": "",
"id": "VCenter",
"initialPlugins": { },
"instances": [
{"id":"vcenter"}
],
"issueManagementLink": "",
"license": "APACHE",
"mwsVersion": "7.1.2 > *",
"pollMethod": true,
"scmLink": "",
"title": "VCenter",
"version": "1.0",
"webServices": [ ],
"website": "http://www.adaptivecomputing.com"
}4.13.2 Creating or Updating Plugin Types
The HTTP PUT method is used to create or update Plugin Types. TheContent-Type HTTP
header is used to determine if the request contains a single class file as plaintext or
the binary data of a JAR file. Each request is explained in the following sections.Quick Reference
PUT http://localhost/mws/rest/plugin-types[?reload-plugins=false]
There is a known issue with dynamically updating plugin types with typed field injection. See the Add or Update Plugin Types section for more information.
4.13.2.1 Update Plugin Type (File)
URLs and Parameters
PUT http://localhost/mws/rest/plugin-types[?reload-plugins=false]
| Parameter | Required | Valid Values | Description |
|---|---|---|---|
| reload-plugins | No | true or false | Reloads all plugins of this type on successful update. Defaults to true. |
Request Body
This function is idempotent, meaning it will create the Plugin Type if it does not exist or update it if it does. The request body is the actual contents of the class file to upload. This web service is an exception to most as it requires a content type ofapplication/x-groovy or text/plain.If theapplication/x-groovyortext/plaincontent types are not used in the request, it will be interpreted as JSON, resulting in a failure.
Plaintext upload
package testimport com.ace.mws.plugins.* import com.ace.mws.plugins.exceptions.*class UploadPlugin { static author = "Adaptive Computing" static description = "A sample plugin class" String id public void configure() throws InvalidPluginConfigurationException { def myConfig = config def errors = [] if (!myConfig.arbitraryKey) errors << "Missing arbitraryKey!" if (errors) throw new InvalidPluginConfigurationException(errors) } public def customService(Map params) { return params } }
If using the curl library to perform plugin type uploading, the equivalent of the command-line
option --data-binary must be used to send the request body. Otherwise compilation errors may be encountered
when uploading the plugin type.Sample Response
The response of this task is the same as the Get All Plugin Types task. The reason that the return of this task is a list is to accommodate the possibility of uploading multiple plugin types in a single JAR file as explained in the next section.4.13.2.2 Update Plugin Type (JAR)
URLs and Parameters
PUT http://localhost/mws/rest/plugin-types?jar-filename=<filename.jar>[&reload-plugins=false]| Parameter | Required | Valid Values | Description |
|---|---|---|---|
| jar-filename | Yes | String | The filename of the JAR file that is being uploaded. |
| reload-plugins | No | true or false | Reloads all plugins of this type on successful update. Defaults to true. |
Request Body
This function is idempotent, meaning it will create the Plugin Types if they do not exist or update them if they do. The request body is the binary contents of the JAR file to upload. This web service is an exception to most as it requires a content type ofapplication/x-jar.
If the application/x-jar content type is not used in the request, it will be interpreted as JSON,
resulting in a failure.
If using the curl library to perform plugin type uploading, the equivalent of the command-line
option --data-binary must be used to send the request body. Otherwise compilation errors may be encountered
when uploading the plugin type.Sample Response
The response of this task is the same as the Get All Plugin Types task. Note that when using a JAR file, multiple plugin types may be uploaded in the same request.4.14 Policies
This section describes behavior of the Policies object in Moab Web Services. It contains the URLs, request bodies, and responses delivered to and from Moab Web Services.The Policy API contains the type and description of fields that all Policies have in common.
Supported Policies
| Name | Id |
|---|---|
| Auto VM Migration | auto-vm-migration |
| Hypervisor Allocation Overcommit | hv-allocation-overcommit |
| Node Allocation | node-allocation |
| Migration Exclusion List | migration-exclusion-list |
Supported Methods
| Resource | GET | PUT | POST | DELETE |
|---|---|---|---|---|
| /rest/policies | Get all policies | |||
| /rest/policies/id | Get specified policy | Modify specified policy |
4.14.1 Getting Policies
The HTTP GET method is used to retrieve Policies information.Quick Reference
GET http://localhost/mws/rest/policies
4.14.1.1 Get All Policies
URLs and Parameters
GET http://localhost/mws/rest/policies
| Parameter | Required | Valid Values | Description | Example |
|---|---|---|---|---|
| query | No | JSON | Query for specific results. | query={"state":"DISABLED","conflicted":"false"} |
| sort | No | JSON | Sort the results. Use 1 for ascending and -1 for descending. | sort={"id":-1} |
Sample Response
GET http://localhost/mws/rest/policies?fields=id,state,conflicted
{
"totalCount": 2,
"resultCount": 2,
"results": [ {
"conflicted": false,
"state": "DISABLED",
"id": "auto-vm-migration"
},{
"conflicted": false,
"state": "DISABLED",
"id": "hv-allocation-overcommit"
},{
"conflicted": false,
"state": "DISABLED",
"id": "node-allocation"
},{
"conflicted": false,
"state": "DISABLED",
"id": "migration-exclusion-list"
}]
}4.14.1.2 Get Single Policy
URLs and Parameters
GET http://localhost/mws/rest/policies/<id>| Parameter | Required | Type | Valid Values | Description |
|---|---|---|---|---|
| id | Yes | String | - | The unique identifier of the object. |
Sample Responses
Auto VM Migration
{
"conflicted": false,
"description": "Controls how virtual machines are automatically migrated.",
"id": "auto-vm-migration",
"name": "Auto VM Migration",
"potentialConflicts": [],
"priority": 1,
"state": "DISABLED",
"tags": [],
"types": [],
"version": 0,
"genericMetricThresholds":{
"GMETRIC1":1.3
},
"processorUtilizationThreshold":0.5,
"memoryUtilizationThreshold":0.4
}Hypervisor Allocation Overcommit
{
"conflicted": false,
"description": "Controls how hypervisors are overallocated with regards to processors and memory.",
"id": "hv-allocation-overcommit",
"name": "Hypervisor Allocation Overcommit",
"potentialConflicts": [],
"priority": 2,
"state": "DISABLED",
"tags": [],
"types": [],
"version": 0,
"processorAllocationLimit":29.5,
"memoryAllocationLimit":1.2
}Node Allocation
{
"conflicted": false,
"description": "Controls how nodes are selected for workload placement.",
"id": "node-allocation",
"name": "Node Allocation",
"potentialConflicts": [],
"priority": 3,
"state": "DISABLED",
"tags": [],
"types": [],
"version": 0,
"nodeAllocationAlgorithm": "CustomPriority",
"customPriorityFunction": "100*RSVAFFINITY - GMETRIC[numvms]"
}Migration Exclusion List
{
"conflicted": false,
"description": "Controls which machines are excluded from automatic live migration operations.",
"hvExclusionList": ["blade05", "blade02"],
"name": "Migration Exclusion List",
"potentialConflicts": [],
"priority": 100,
"state": "DISABLED",
"tags": [],
"types": [],
"version": 1,
"vmExclusionList": ["vm1", "vm5"],
"id": "migration-exclusion-list"
}4.14.2 Modifying Policies
The HTTP PUT method is used to modify Policies.Quick Reference
PUT http://localhost/mws/rest/policies/<id>4.14.2.1 Modify Policy
URLs and Parameters
PUT http://localhost/mws/rest/policies/<id>[?change-mode=set]| Parameter | Required | Type | Valid Values | Description |
|---|---|---|---|---|
| id | Yes | String | - | The unique identifier of the object. |
Additional URL parameters
URL parameters for modifying a Migration Exclusion Lists Policy.| Migration Exclusion Lists Parameter | Required | Valid Values | Description |
|---|---|---|---|
| change-mode | No | set(Default) | Replace the existing exclusion list(s) with the given one. |
| add | Add the given VMs/HVs to the existing exclusion list(s). | ||
| remove | Remove the given VMs/HVs from the existing exclusion list(s). |
Request Body
In general, the fields shown in the Policy API are not available for modification. However, thestate field may be modified to a valid
Policy State. All other fields listed in the specific
API pages may be modified unless documented otherwise.The request body below shows all the fields that are available when
modifying a Auto VM Migration Policy, along with some sample values.JSON Request Body for Auto VM Migration Policy
{
"genericMetricThresholds": {
"GENERICTHRESHOLD": 5
},
"memoryUtilizationThreshold": 0.5,
"processorUtilizationThreshold": 0.4
}JSON Request Body for Auto VM Migration Policy
{
"nodeAllocationAlgorithm" : "CustomPriority",
"customPriorityFunction" : "100*RSVAFFINITY - GMETRIC[numvms]"
}JSON Request Body for Migration Exclusion Lists Policy
{
"vmExclusionList" : ["vm1","vm3","vm5"],
"hvExclusionList" : ["hv2","hv3","hv6"]
}Sample Response
JSON Response
{
"messages": ["Policy auto-vm-migration updated"]
}Samples
Enable the Auto VM Migration Policy and set values.PUT http://localhost/mws/rest/policies/auto-vm-migration
{
"state": "enabled",
"migrationAlgorithmType": "overcommit",
"processorUtilizationThreshold": 0.5,
"memoryUtilizationThreshold": 0.4
}As noted in the Auto VM Migration API documentation, if thestateis set to ENABLED, then themigrationAlgorithmTypemust not be set to NONE.
Restrictions
All Policies
- Fields cannot be modified while the policy is disabled. Enable the policy to modify the field.
Auto VM Migration
- Arbitrary metrics can be added to genericMetricThresholds, but they cannot be removed once added.
- The migrationAlgorithmType field cannot be modified while the policy is disabled. Enable the policy to modify the field.
- Moab is configured with a default limit of 10 generic metrics. If this limit is reached, such as when arbitrary metrics are added to genericMetricThresholds, the metric will not be reported.
- To increase this limit, set the
MAXGMETRICproperty in the Moab configuration file.
4.15 Quotes
This section describes behavior of the Quotes object in Moab Web Services. It contains the URLs, request bodies, and responses delivered to and from Moab Web Services.The Quote API contains the type and description of fields that all Quotes have in common.
Supported Methods
| Resource | GET | PUT | POST | DELETE |
|---|---|---|---|---|
| /rest/quotes/standard/quote | Quoting resources |
4.15.1 Quoting Resources
Quick Reference
POST http://localhost/mws/rest/quotes/standard/quote?object-type=<OBJECTTYPE>&proxy-user=<USER>&charge-duration=<CHARGEDURATION>
4.15.1.1 Quote Single Job or Service
URLs and Parameters
POST http://localhost/mws/rest/quotes/standard/quote?object-type=<OBJECTTYPE>&proxy-user=<USER>&charge-duration=<CHARGEDURATION>
| Parameter | Required | Type | Valid Values | Description |
|---|---|---|---|---|
| proxy-user | Yes | String | Perform action as defined MAM user. | proxy-user=amy |
| charge-duration | Yes | Integer | The charge duration of the job in seconds. | charge-duration=6400 |
| object-type | Yes | String | The object to quote. It can be job or service. | object-type=job |
| itemize | No | Boolean | Returns the composite charge information in the response data. | itemize=true |
| rate | No | JSONArray | Uses the specified charge rates in the quote. The specified rates override the standard and quote rates. If the guarantee field is set to true, these charge rates will be saved and used when this quote is referenced in a charge action. | rate=[{"type":"VBR","name":"Memory","rate":1},{"type":"VBR","name":"Processors","rate":1}] |
| guarantee | No | Boolean | Guarantees the quote and returns a quote id to secure the current charge rates. This results in the creation of a quote record and a permanent usage record. This parameter is mutually exclusive with the cost-only parameter. | guarantee=true |
| grace-duration | No | Integer | The guaranteed quote grace period in seconds. If the quote duration is specified but not the quote end time, the quote endtime will be calculated as the quote start time plus the quote duration plus the grace duration. | grace-duration=6400 |
| cost-only | No | Integer | Returns the cost, ignoring all balance and validity checks. This parameter is mutually exclusive with the guarantee parameter. | cost-only=true |
| description | No | String | The guaranteed quote description. | description="ABC Coupon Rate" |
| start-time | No | Date | The guaranteed quote start time in the format yyyy-MM-dd HH:mm:ss z, -Infinity, Infinity, or Now. | start-time="2012-04-09 13:49:40 MDT" |
| end-time | No | Date | The guaranteed quote end time in the format yyyy-MM-dd HH:mm:ss z, -Infinity, Infinity, or Now. | end-time="2012-04-09 14:49:40 MDT" |
Request Body
The request body below shows all of the fields in a Job that could affect the quote.POST http://localhost/mws/rest/quotes/standard/quote?object-type=job
{
"id": "Moab.1"
"user": "amy",
"group": "group",
"rmName": "machine1",
"templateList": [
"genericVm"
],
"account": "biology",
"qosRequested": "QOS1",
"variables": {
"imageName": "centos5.5-stateless",
"topLevelServiceId": "myService.1",
"serviceId": "vmService.1",
"vmid": "VmService.1",
"pmid": "VmService.1"
},
"requirements": [
{
"requiredProcessorsPerTask": 2,
"genericResources": {
"gold": 100,
"os": 500
},
"requiredNodeCountMinimum": 1,
"requiredMemoryPerTask": 1024,
"requiredClass": "batch"
}
]
}POST http://localhost/mws/rest/quotes/standard/quote?object-type=service
{
"name":"service.1",
"user": "amy",
"account": "chemistry"
"attributes":{
"moab":{
"job":{
"resources":{
"procs":1,
"mem":2048,
"OS":500,
"gold":100
},
"variables":{
"Var1": 1524
},
"image":"centos5.5-stateless",
"template":"genericVM",
}
}
}
}Sample Responses
If the quote is not guaranteed
JSON Response
{
"instance": "Moab.1",
"amount": 600
}If the quote is guaranteed
JSON Response
{
"id": 1,
"usageRecord": 2,
"instance": "Moab.1",
"amount": 600
}If the quote is guaranteed and itemized
JSON Response
{
"details": [
{
"name": "Processors",
"value": "2",
"duration": 300,
"rate": 1,
"scalingFactor": 1,
"amount": 600,
"details": "2 [Processors] * 1 [ChargeRate{VBR}{Processors}] * 300 [Duration]"
},
{
"name": "Memory",
"value": "1024",
"duration": 300,
"rate": 1,
"scalingFactor": 1,
"amount": 307200,
"details": "1024 [Memory] * 1 [ChargeRate{VBR}{Memory}] * 300 [Duration]"
}
],
"id": 20,
"instance": "Moab.1",
"usageRecord": 20,
"amount": 307800
}If the quote is on a service
JSON Response
{
"services": [
{
"details": [
{
"name": "Processors",
"value": "22",
"duration": 30,
"rate": 1,
"scalingFactor": 1,
"amount": 660,
"details": "22 [Processors] * 1 [ChargeRate{VBR}{Processors}] * 30 [Duration]"
},
{
"name": "Memory",
"value": "32343242",
"duration": 30,
"rate": 1,
"scalingFactor": 1,
"amount": 970297260,
"details": "32343242 [Memory] * 1 [ChargeRate{VBR}{Memory}] * 30 [Duration]"
}
],
"id": 120,
"instance": "myVmWorkflow",
"usageRecord": 157,
"amount": 970297920
},
{
"details": [ {
"name": "Storage",
"value": "2500",
"duration": 30,
"rate": 1.157E-7,
"scalingFactor": 1,
"amount": 0,
"details": "2500 [Storage] * 1.157e-07 [ChargeRate{VBR}{Storage}] * 30 [Duration]"
}],
"id": 122,
"instance": "myExtraStorageWorkflow",
"usageRecord": 159,
"amount": 0
},
{
"details": [
{
"name": "Processors",
"value": "0",
"duration": 30,
"rate": 1,
"scalingFactor": 1,
"amount": 0,
"details": "0 [Processors] * 1 [ChargeRate{VBR}{Processors}] * 30 [Duration]"
},
{
"name": "Memory",
"value": "0",
"duration": 30,
"rate": 1,
"scalingFactor": 1,
"amount": 0,
"details": "0 [Memory] * 1 [ChargeRate{VBR}{Memory}] * 30 [Duration]"
}
],
"id": 123,
"instance": "myPmWorkflow",
"usageRecord": 160,
"amount": 0
}
],
"amount": 970297920
}Restrictions
- The details field is only available with MAM version 7.1.0 or later.
4.16 Reports
This section describes behavior of the reporting framework in Moab Web Services. It contains the URLs, request bodies, and responses delivered to and from Moab Web Services.The Report, Sample, and Datapoint API contains the type and description of all fields in the Report, Sample, and Datapoint objects. They also contains details regarding which fields are valid during PUT and POST actions.
Supported Methods
| Resource | GET | PUT | POST | DELETE |
|---|---|---|---|---|
| /rest/reports | Get all reports | Create Reports | Deleting Reports | |
| /rest/reports/name | Get single report with data | |||
| /rest/reports/id | Get single report with data | |||
| /rest/reports/name/datapoints | Get datapoints for report | |||
| /rest/reports/id/datapoints | Get datapoints for report | |||
| /rest/reports/name/samples | Get samples for report | Create sample(s) for report | ||
| /rest/reports/id/samples | Get samples for report | Create sample(s) for report |
4.16.1 Getting Reports
The HTTP GET method is used to retrieve Report information. Queries for all reports with no attached data and a single report with associated data are available.Quick Reference
GET http://localhost/mws/rest/reports[?query={"field":"value"}&sort={"field":<1|-1>}]
GET http://localhost/mws/rest/reports/<id>
GET http://localhost/mws/rest/reports/<name>4.16.1.1 Get All Reports (No Data Included)
URLs and Parameters
GET http://localhost/mws/rest/reports[?query={"field":"value"}&sort={"field":<1|-1>}]| Parameter | Required | Valid Values | Description | Example |
|---|---|---|---|---|
| query | No | JSON | Queries for specific results. | query={"reportSize":4} |
| sort | No | JSON | Sort the results. Use 1 for ascending and -1 for descending. | sort={"name":-1} |
Sample Response
JSON Response
{
"totalCount": 1,
"resultCount": 1,
"results": [ {
"id": "3efe5c670be86ba8560397ff",
"name": "cpu-util"
…
}]
}No datapoints are returned when querying for all reports. To view the consolidated datapoints, the Get Single Report API call must be used.
Samples
GET http://localhost/mws/rest/reports?fields=id,name
{
"totalCount": 3,
"resultCount": 3,
"results": [
{
"id": "3efe5c670be86ba8560397ff",
"name": "cpu-util"
},
{
"id": "3efe5c670be86ba856039800",
"name": "cpu-temp"
},
{
"id": "3efe5c670be86ba856039801",
"name": "cpu-load"
}
]
}4.16.1.2 Get Single Report (Includes Data)
URLs and Parameters
GET http://localhost/mws/rest/reports/<id> GET http://localhost/mws/rest/reports/<name>
| Parameter | Required | Type | Valid Values | Description |
|---|---|---|---|---|
| id | Yes | String | - | The unique identifier of the report. |
| name | Yes | String | - | The name of the report. |
Only one of id or name are required.
Sample Response
In the example below, the first datapoint has anull data element, which means that the minimumSampleSize
configured for the report was not met when consolidating the datapoint. The second datapoint contains
actual data.JSON Response
{
"consolidationFunction": "average",
"datapointDuration": 15,
"datapoints": [
{
"endDate": "2011-12-02 17:28:22 MST",
"startDate": "2011-12-02 17:28:22 MST",
"firstSampleDate": null,
"lastSampleDate": null,
"data": null
},
{
"endDate": "2011-12-02 17:28:23 MST",
"startDate": "2011-12-02 17:28:37 MST",
"firstSampleDate": "2011-12-02 17:28:23 MST",
"lastSampleDate": "2011-12-02 17:28:30 MST",
"data": {
"utilization": 99.89,
"time": 27.433333333333337
}
}
],
"description": "Example of CPU utilization reporting",
"id": "3efe5c670be86ba8560397ff",
"keepSamples": false,
"minimumSampleSize": 1,
"name": "cpu-util",
"reportSize": 2
}4.16.1.3 Get Datapoints For Single Report
URLs and Parameters
GET http://localhost/mws/rest/reports/<id>/datapoints[?query={"field":"value"}&sort={"field":<1|-1>}] GET http://localhost/mws/rest/reports/<name>/datapoints[?query={"field":"value"}&sort={"field":<1|-1>}]
| Parameter | Required | Type | Valid Values | Description |
|---|---|---|---|---|
| id | Yes | String | - | The unique identifier of the report. |
| name | Yes | String | - | The name of the report. |
| query | No | JSON | Queries for specific results. | query={"data.test":true} |
| sort | No | JSON | Sort the results. Use 1 for ascending and -1 for descending. | sort={"startDate":-1} |
Only one of id or name are required.
Sample Response
This function is exactly the same as requesting a single report with only the datapoints returned. No report metadata (i.e. description, minimumSampleSize, etc.) is returned.JSON Response
{
"resultCount":1,
"totalCount":1,
"results":[
{
"endDate": "2011-12-02 17:28:22 MST",
"startDate": "2011-12-02 17:28:22 MST",
"firstSampleDate": null,
"lastSampleDate": null,
"data": null
},
{
"endDate": "2011-12-02 17:28:37 MST",
"startDate": "2011-12-02 17:28:37 MST",
"firstSampleDate": "2011-12-02 17:28:23 MST",
"lastSampleDate": "2011-12-02 17:28:23 MST",
"data": {
"utilization": 99.89,
"time": 27.433333333333337
}
}
]
}4.16.2 Getting Samples For Reports
The HTTP GET method is used to retrieve Sample information.Quick Reference
GET http://localhost/mws/rest/reports/<id>/samples[?query={"field":"value"}&sort={"field":<1|-1>}] GET http://localhost/mws/rest/reports/<name>/samples[?query={"field":"value"}&sort={"field":<1|-1>}]
4.16.2.1 Get Samples For Report
URLs and Parameters
GET http://localhost/mws/rest/reports/<id>/samples[?query={"field":"value"}&sort={"field":<1|-1>}] GET http://localhost/mws/rest/reports/<name>/samples[?query={"field":"value"}&sort={"field":<1|-1>}]
| Parameter | Required | Type | Valid Values | Description |
|---|---|---|---|---|
| id | Yes | String | - | The unique identifier of the report. |
| name | Yes | String | - | The name of the report. |
| query | No | JSON | Queries for specific results. | query={"agent":"cpu-monitor"} |
| sort | No | JSON | Sort the results. Use 1 for ascending and -1 for descending. | sort={"agent":-1} |
Only one of id or name are required.
Sample Response
JSON Response
{
"totalCount": 1,
"resultCount": 1,
"results": [ {
"timestamp": "2011-12-02 17:28:37 MST"
"data":{
"cpu1":2.3,
"cpu2":1.2,
"cpu3":0.0,
"cpu4":12.1
},
…
}]
}4.16.3 Creating Reports
The HTTP POST method is used to create Reports. Operations are available to create reports with or without historical datapoints.Quick Reference
POST http://localhost/mws/rest/reports
4.16.3.1 Create Report
URLs and Parameters
POST http://localhost/mws/rest/reports
Request Body
To create a report, several fields are required as documented in the Report API.The request body below shows all the fields that are available during report creation.JSON Request Body
{
"name":"cpu-util",
"description":"An example report on cpu utilization",
"consolidationFunction":"average",
"datapointDuration":15,
"minimumSampleSize":1,
"reportSize":2,
"keepSamples":true,
"datapoints":[
{
"startDate":"2011-12-01 19:16:57 MST",
"endDate":"2011-12-01 19:16:57 MST",
"data":{
"time":30,
"util":99.98
}
}
]
}Sample Response
{
"messages":["Report cpu-util created"],
"id":"3efe5c670be86ba8560397ff",
"name":"cpu-util"
}Samples
POST http://localhost/mws/rest/reports (Minimal report without datapoints)
{
"name":"cpu-util",
"datapointDuration":15,
"reportSize":2
}4.16.4 Creating Samples
The HTTP POST method is used to create Samples for Reports.Quick Reference
POST http://localhost/mws/rest/reports
4.16.4.1 Create Samples For Report
URLs and Parameters
GET http://localhost/mws/rest/reports/<id>/samples GET http://localhost/mws/rest/reports/<name>/samples
| Parameter | Required | Type | Valid Values | Description |
|---|---|---|---|---|
| id | Yes | String | - | The unique identifier of the report. |
| name | Yes | String | - | The name of the report. |
Only one of id or name are required.
Request Body
To create samples for a report, simply send data and an optional timestamp to the URL above.The request body below shows all the fields that are available during sample creation. Note that thedata field can contain arbitrary JSON.JSON Request Body
{
"timestamp":"2011-12-01 19:16:57 MST",
"agent":"my agent",
"data":{
"cpu1":2.3,
"cpu2":1.2,
"cpu3":0.0,
"cpu4":12.1
}
}Sample Response
{"messages":["1 sample(s) created for report cpu-util"]}4.16.5 Deleting Reports
The HTTP DELETE method is used to delete Reports.Quick Reference
DELETE http://localhost/mws/rest/reports/<id> DELETE http://localhost/mws/rest/reports/<name>
4.16.5.1 Delete Report
URLs and Parameters
DELETE http://localhost/mws/rest/reports/<id> DELETE http://localhost/mws/rest/reports/<name>
| Parameter | Required | Type | Valid Values | Description |
|---|---|---|---|---|
| id | Yes | String | - | The unique identifier of the report. |
| name | Yes | String | - | The name of the report. |
Only one of id or name are required.
Sample Response
JSON Response
{"messages":["Report cpu-util deleted"]}4.17 Reservations
This section describes behavior of the Reservation object in Moab Web Services. It contains the URLs, request bodies, and responses delivered to and from Moab Web Services.The Reservation API contains the type and description of all fields in the Reservation object. It also contains details regarding which fields are valid during PUT and POST actions.
Supported Methods
| Resource | GET | PUT | POST | DELETE |
|---|---|---|---|---|
| /rest/reservations | Get all reservations | Create reservation | ||
| /rest/reservations/id | Get specified reservation | Modify reservation | Release reservation |
4.17.1 Getting Reservations
The HTTP GET method is used to retrieve Reservation information. Queries for all objects and a single object are available.Quick Reference
GET http://localhost/mws/rest/reservations/<id>Restrictions
- Only admin or user reservations are returned with this call.
4.17.1.1 Get All Reservations
URLs and Parameters
GET http://localhost/mws/rest/reservations
Sample Response
GET http://localhost/mws/rest/reservations?fields=id
{
"totalCount": 3,
"resultCount": 3,
"results": [
{"id": "system.1"},
{"id": "system.2"},
{"id": "system.3"}
]
}4.17.1.2 Get Single Reservation
URLs and Parameters
GET http://localhost/mws/rest/reservations/<id>| Parameter | Required | Type | Valid Values | Description |
|---|---|---|---|---|
| id | Yes | String | - | The unique identifier of the object. |
Sample Response
JSON Response
{
"accountingAccount": "",
"accountingGroup": "",
"accountingQOS": "",
"accountingUser": "root",
"aclRules": [ {
"affinity": "NEUTRAL",
"comparator": "LEXIGRAPHIC_EQUAL",
"type": "RESERVATION_ID",
"value": "system.43"
}],
"allocatedNodeCount": 1,
"allocatedProcessorCount": 8,
"allocatedTaskCount": 1,
"allocatedNodes": [
{"id":"node001"}
],
"comments": "",
"creationDate": null,
"duration": 200000000,
"endDate": "2018-03-17 16:49:10 MDT",
"excludeJobs": [
"job1",
"job2"
],
"expireDate": null,
"flags": [
"REQFULL",
"ISACTIVE",
"ISCLOSED"
],
"globalId": "",
"hostListExpression": "",
"id": "system.43",
"idPrefix": "",
"isActive": true,
"isTracked": false,
"label": "",
"maxTasks": 0,
"messages": [],
"owner": {
"name": "adaptive",
"type": "USER"
},
"partitionId": "switchB",
"profile": "",
"requirements": {
"architecture": "",
"featureList": [
"feature1",
"feature2"
],
"featureMode": "",
"memory": 0,
"nodeCount": 0,
"nodeIds": ["node001:1"],
"os": "",
"taskCount": 1
},
"reservationGroup": "",
"resources": {"PROCS": 0},
"startDate": "2011-11-14 20:15:50 MST",
"statistics": {
"caps": 0,
"cips": 2659.52,
"taps": 0,
"tips": 0
},
"subType": "Other",
"taskCount": 0,
"trigger": null,
"triggerIds": [],
"uniqueIndex": "",
"variables": {}
}4.17.2 Creating Reservations
The HTTP POST method is used to create Reservations.Quick Reference
POST http://localhost/mws/rest/reservations
4.17.2.1 Create Reservation
URLs and Parameters
POST http://localhost/mws/rest/reservations
Request Body
The request body below shows all the fields that are available when creating a Reservation, along with some sample values.JSON Request Body
{
"accountingAccount": "",
"accountingGroup": "",
"accountingQOS": "",
"accountingUser": "root",
"aclRules": [ {
"affinity": "POSITIVE",
"comparator": "LEXIGRAPHIC_EQUAL",
"type": "GROUP",
"value": "staff"
}],
"comments": "",
"duration": 200000000,
"endDate": "2018-03-17 16:49:10 MDT",
"excludeJobs": [
"job1",
"job2"
],
"flags": [
"SPACEFLEX",
"ACLOVERLAP",
"SINGLEUSE"
],
"hostListExpression": "",
"idPrefix": "",
"label": "myreservation",
"owner": {
"name": "adaptive",
"type": "USER"
},
"partitionId": "",
"profile": "",
"requirements": {
"architecture": "",
"featureList": [
"feature1",
"feature2"
],
"memory": 0,
"os": "",
"taskCount": 1
},
"reservationGroup": "",
"resources": {
"PROCS": 2,
"MEM": 1024,
"DISK": 1024,
"SWAP": 1024,
"other1": 17,
"other2": 42
},
"startDate": "2011-11-14 20:15:50 MST",
"subType": "Other",
"trigger": {
"eventType":"START",
"actionType":"EXEC",
"action":"date"
},
"variables": {
"var1": "val1",
"var2": "val2"
}
}Create reservation if no conflicting reservations are found.
This is equivalent to mrsvctl -c -h node01 -E.JSON Request Body
{
"flags": [
"DEDICATEDRESOURCE"
],
"hostListExpression": "node01"
}Sample Response
JSON Response for successful POST
{"id": "system.44"}4.17.3 Modifying Reservations
The HTTP PUT method is used to modify Reservations.Quick Reference
PUT http://localhost/mws/rest/reservations/<id>?change-mode=<add|remove|set>
4.17.3.1 Modify Reservation
URLs and Parameters
PUT http://localhost/mws/rest/reservations/<id>?change-mode=<add|remove|set>
| Parameter | Required | Type | Valid Values | Description |
|---|---|---|---|---|
| id | Yes | String | - | The unique identifier of the object. |
| change-mode | Yes | String | add | Add the given variables to the variables that already exist. |
| remove | Delete the given variables from the variables that already exist. | |||
| set | Replace all existing variables with the given variables. |
Request Body
The request body below shows all the fields that are available when modifying a Reservation, along with some sample values.JSON Request Body for Reservation Modify
{
"variables": {
"var1": "val1",
"var2": "val2"
}
}Sample Response
This message may not match the message returned from Moab exactly, but is given as an example of the structure of the response.
JSON Response
{"messages":["reservation 'system.43' attribute 'Variable' changed."]}Restrictions
- You can change the ACL Rules on a reservation, but not using this resource. See Create or Update ACLs.
4.17.4 Releasing Reservations
The HTTP DELETE method is used to release Reservations.Quick Reference
DELETE http://localhost/mws/rest/reservations/<id>4.17.4.1 Release Reservation
URLs and Parameters
DELETE http://localhost/mws/rest/reservations/<id>| Parameter | Required | Type | Valid Values | Description |
|---|---|---|---|---|
| id | Yes | String | - | The unique identifier of the object. |
Sample Response
JSON Response for successful DELETE
{}4.18 Resource Types
This section describes behavior of the Resource Type object in Moab Web Services. It contains the URLs, request bodies, and responses delivered to and from Moab Web Services.The ResourceType API contains the type and description of all fields in the Resource Type object.
Supported Methods
| Resource | GET | PUT | POST | DELETE |
|---|---|---|---|---|
| /rest/resource-types | Get all resource types |
4.18.1 Getting Resource Types
The HTTP GET method is used to retrieve Resource Type information.Quick Reference
GET http://localhost/mws/rest/resource-types
4.18.1.1 Get All Resource Types
URLs and Parameters
GET http://localhost/mws/rest/resource-types
Sample Response
GET http://localhost/mws/rest/resource-types?fields=id
{
"totalCount": 1,
"resultCount": 1,
"results": [
{"id": "throttle_migrate"}
]
}4.19 Services
This section describes the behavior of a Service (an interdependent collection of workflows). It is possible for a Service to be composed of multiple Services. This section describes the URLs, request bodys, and responses delivered to and from Moab Web Services for each approach.The Service API contains the type and description of all fields in the Service object. It also contains details regarding which fields are valid during PUT and POST actions.
Supported Methods
| Resource | GET | PUT | POST | DELETE |
|---|---|---|---|---|
| /rest/services | Get all Services | Create Service | ||
| /rest/services/id | Get specified Service | Modify Service | Delete Service |
4.19.1 Getting Service Information
The HTTP GET method is used to retrieve Service information. Queries for all objects and a single object are available.Quick Reference
GET http://localhost/mws/rest/services[?query={"field":"value"}&sort={"field":<1|-1>}[&[show-recursive-vc|show-vc]=true]]
GET http://localhost/mws/rest/services/<id>[?[show-recursive-vc|show-vc]=true]
GET http://localhost/mws/rest/services/<name>[?[show-recursive-vc|show-vc]=true]4.19.1.1 Get All Services
URLs and Parameters
GET http://localhost/mws/rest/services[?query={"field":"value"}&sort={"field":<1|-1>}[&[show-recursive-vc|show-vc]=true]]| Parameter | Required | Valid Values | Description | Example |
|---|---|---|---|---|
| query | No | JSON | Query for specific results. | query={"type":"storage","label":"exlabel"} |
| sort | No | JSON | Sort the results. Use 1 for ascending and -1 for descending. | sort={"account":-1} |
| show-recursive-vc | No | true | Show extended details about the service's virtual container including nested virtual containers and nested jobs. | show-recursive-vc=true |
| show-vc | No | true | Show details about the service's virtual container. | show-vc=true |
Sample Response
GET http://localhost:8080/mws/rest/services?query={user:"bob"}
{
"totalCount": 9,
"resultCount": 3,
"results": [
{
"dateCreated": "2011-12-07 16:03:40 UTC",
"lastUpdated": "2011-12-07 16:03:40 UTC", "name": "bobService.1",
"version": 1,
"type": "container",
"label": null,
"user": "bob",
"account": "bamboo",
"startDateRequested": "2012-14-10 20:51:07 UTC",
"startDateScheduled" : "2012-14-10 20:51:07 UTC",
"status": "A custom status message",
"statusCode": 0,
"includedServices": [
"machine0.1",
"OSStoremachine0.1"
],
"parent": null,
"serviceTemplate": {
"id": "4fbd42cfc4aa4c444cc54112",
"name": "CentosVmPlusStorage"
},
"attributes": {"moab": {
"vc": {"id": "vc56"},
"dependencies": [ {
"service": "machine0.1",
"dependency": ["OSStoremachine0.1"]
}]
}},
"id": "4edff0cc6852f709fa777826"
},
{
"dateCreated": "2011-12-07 16:03:40 UTC",
"lastUpdated": "2011-12-07 16:03:40 UTC",
"name": "machine0.1",
"version": 1,
"type": "vm",
"label": "bobs machine",
"user": "bob",
"account": "bamboo",
"startDateRequested": "2012-14-10 20:51:07 UTC",
"startDateScheduled" : "2012-14-10 20:51:07 UTC",
"status": "A custom status message",
"statusCode": 0,
"includedServices": [],
"parent": "bobService.1",
"serviceTemplate": {
"id": "4fbd42cfc4aa4c444cc54113",
"name": "CentosVm"
},
"attributes": {"moab": {
"vc": {"id": "vc57"},
"job": {
"id": "Moab.24",
"template": "genericVM",
"image": "centos5.5-stateless",
"features": ["vlan3"],
"variables": {"QOS": "High"},
"resources": {
"mem": 2,
"procs": 2,
"disk": 2
}
}
}},
"id": "4edff0cc6852f709fa777827"
},
{
"dateCreated": "2011-12-07 16:03:40 UTC",
"lastUpdated": "2011-12-07 16:03:40 UTC",
"name": "OSStoremachine0.1",
"version": 1,
"type": "storage",
"label": null,
"user": "bob",
"account": "bamboo",
"startDateRequested": "2012-14-10 20:51:07 UTC",
"startDateScheduled" : "2012-14-10 20:51:07 UTC",
"status": "A custom status message",
"statusCode": 0,
"includedServices": [],
"parent": "bobService.1",
"serviceTemplate": {
"id": "4fbd42cfc4aa4c444cc54114",
"name": "OpSysStorage"
},
"attributes": {"moab": {
"vc": {"id": "vc58"},
"job": {
"id": "Moab.23",
"template": "OSStorage",
"resources": {"OS": 200}
}
}},
"id": "4edff0cc6852f709fa777828"
}
]
}Querying Services
It is possible to query services by one or more fields based on MongoDB query syntax.Simple Queries
To see only services that are associated with the user "bob" you can use a query such as the following:http://localhost/mws/rest/services?query={"user":"bob"}http://localhost/mws/rest/services?query={"type":"vm"}http://localhost/mws/rest/services?query={"user":"bob","type":"vm"}http://localhost/mws/rest/services?query={"user":{"$ne":"bob"}}More Complex Queries
When the field values of the desired services are a finite set, you can use the$in operator.
For example, to see services that belong to either bob, alice, or charlie, you can do the following:http://localhost/mws/rest/services?query={"user":{"$in":["alice","bob","charlie"]}}http://localhost/mws/rest/services?query={"attributes.moab.job.resources.procs":3}Conditional Operators
You can perform<, <=, >, >= comparisons using the $lt, $lte, $gt, $gte operators.| Operator | Comparison | |
|---|---|---|
| $lt | < | |
| $lte | <= | |
| $gt | > | |
| $gte | >= |
< 2 processors:http://localhost/mws/rest/services?query={"attributes.moab.job.resources.procs":{"$lt":2}}>= 1024 memory:http://localhost/mws/rest/services?query={"attributes.moab.job.resources.mem":{"$gte":1024}}Querying Services by Date
To see all services created after Febuary 8, 2012 at 1:00 PM Mountain Standard Time (MST):http://localhost/mws/rest/services?query={"dateCreated":{"$gt":"2012-02-08 13:00:00 MST"}}http://localhost/mws/rest/services?query={"dateCreated":{"$lte":"2012-02-08 13:00:00 PST"}}http://localhost/mws/rest/services?query={"dateCreated":{"$lte":"2012-02-08 13:00:00 EST","$gte":"2012-02-08 12:00:00 EST"}}Querying Services by Containing Service
Services can contain other services. When a service is contained within another service, you can find out what its container is by looking at the parent field. A service that is not contained in any other service is called a top level service. If you want to see only top level services you need to query for services with a null parent.In MongoDB syntax you query for services whose parent field have a$type of 10 (with 10
representing null). The following query shows all of bob's top level services:http://localhost/mws/rest/services?query={"user":"bob","parent":{"$type":10}}http://localhost/mws/rest/services?query={"user":"bob","parent":"bobService.1"}Sorting
See the sorting section of Global URL ParametersLimiting the Number of Results
If you want to limit the number of results of services you can use themax parameter. For
example, to see only 10 of bob's services:http://localhost/mws/rest/services?query={"user":"bob"}&sort={"name":1}&max=10max with offset as follows:http://localhost/mws/rest/services?query={"user":"bob"}&sort={"name":1}&max=10&offset=90Retrieving a Subset of Fields
To cause only certain fields to return for each service, use thefields parameter. For example, to
show only the name field for each service:http://localhost/mws/rest/services?fields=name
{
"totalCount": 9,
"resultCount": 3,
"results": [
{"name": "aliceService.1"},
{"name": "machine0.1"},
{"name": "OSStoremachine0.1"}
]
}http://localhost/mws/rest/services?fields=name,type,user
{
"totalCount": 9,
"resultCount": 3,
"results": [
{
"name": "aliceService.1",
"type": "container",
"user": "alice"
},
{
"name": "machine0.1",
"type": "vm",
"user": "alice"
},
{
"name": "OSStoremachine0.1",
"type": "storage",
"user": "alice"
}
]
}4.19.1.2 Get Single Service
URLs and Parameters
GET http://localhost/mws/rest/services/<id>[?[show-recursive-vc|show-vc]=true] GET http://localhost/mws/rest/services/<name>[?[show-recursive-vc|show-vc]=true]
| Parameter | Required | Valid Values | Description | Example |
|---|---|---|---|---|
| id | Yes | String | The unique identifier of the service. | |
| name | Yes | String | The name of the service. | |
| show-recursive-vc | No | true | Show extended details about the service's virtual container including nested virtual containers and nested jobs. | show-recursive-vc=true |
| show-vc | No | true | Show details about the service's virtual container. | show-vc=true |
| Parameter | Required | Type | Valid Values | Description |
|---|
Only one of id or name are required.
Samples
GET http://localhost/mws/rest/services/bobService.1?
{
"dateCreated": "2011-12-07 16:03:40 UTC",
"lastUpdated": "2011-12-07 16:03:40 UTC",
"name": "bobService.1",
"version": 1,
"type": "container",
"label": null,
"user": "bob",
"account": "bamboo",
"startDateRequested": "2012-14-10 20:51:07 UTC",
"startDateScheduled" : "2012-14-10 20:51:07 UTC",
"durationRequested": 86400,
"status": "A custom status message",
"statusCode": 0,
"includedServices": [
"machine0.1",
"OSStoremachine0.1"
],
"parent": null,
"serviceTemplate": {
"id": "4fbd42cfc4aa4c444cc54112",
"name": "CentosVmPlusStorage"
},
"attributes": {"moab": {
"vc": {"id": "vc56"},
"dependencies": [ {
"service": "machine0.1",
"dependency": ["OSStoremachine0.1"]
}]
}},
"id": "4edff0cc6852f709fa777826"
}4.19.2 Creating Services
The HTTP POST method is used to create a Service.Quick Reference
POST http://localhost/mws/rest/services
4.19.2.1 Create Service From Service Template
URLs and Parameters
POST http://localhost/mws/rest/services[?proxy-user=bob]
| Parameter | Required | Valid Values | Description | Example |
|---|---|---|---|---|
| proxy-user | No | String | The name of the user creating the service. | proxy-user=bob |
Simple Case
To create a service from the template named "Rhel54VmPlusStorage":POST http://localhost/mws/rest/services
{
"user": "steve",
"account": "cloud",
"startDateRequested": "2011-11-08 13:18:47 MST",
"durationRequested": 86400,
"data": [
{
"name": "MyRhel54VmPlusStorage",
"serviceTemplate": "Rhel54VmPlusStorage",
}
]
}POST http://localhost/mws/rest/services
{
"user": "steve",
"account": "cloud",
"data": [
{
"name": "MyRhel54VmPlusStorage",
"serviceTemplate": {
"name":"Rhel54VmPlusStorage"
}
}
]
}POST http://localhost/mws/rest/services
{
"user": "steve",
"account": "cloud",
"data": [
{
"name": "MyRhel54VmPlusStorage",
"serviceTemplate": {
"id":"4fbd2d90c4aa4996400bsa5m"
}
}
]
}Extending a Service Template
If you want to create a service from a service template, but wish to extend the service template with some additional variables or generic resources, you can use the extends field. Extending a service template is also helpful when you wish to override certain values, such as the amount of memory or processors the service requires.To extend a service template, you will need to determine the extends path for the service you wish to override. The extends path is the name of the top level service, followed by one or more localNames as described in the includedServices field. All but the last <localName> are nested containers inside the top level container. For example:<top level service name>::<localName>[:<localName>]+
Rhel54VmPlusStorage Service Template
{
"name":"Rhel54VmPlusStorage",
"type":"container",
…
"includedServices":[
{
"localName":"sc1",
"serviceTemplate":"SubContainer1"
}
]
}MyRhel54VmPlusStorage::sc1
SubContainer1 Service Template
{
"name":"SubContainer1",
"type":"container",
…
"includedServices":[
{
"localName":"sc2",
"serviceTemplate":"SubContainer2"
}
]
}MyRhel54VmPlusStorage::sc1:sc2
SubContainer1 Service Template
{
"name":"SubContainer2",
"type":"container",
…
"includedServices":[
{
"localName":"rvm",
"serviceTemplate":"Rhel54Vm"
},
{
"localName":"oss",
"serviceTemplate":"OpSysStorage"
}
]
}MyRhel54VmPlusStorage::sc1:sc2:rvm MyRhel54VmPlusStorage::sc1:sc2:oss
POST http://localhost/mws/rest/services
{
"user": "steve",
"account": "cloud",
"data": [
{
"name": "MyRhel54VmPlusStorage",
"serviceTemplate": "Rhel54VmPlusStorage",
"attributes": {
"sharedData":{ "extraAttribute":"some attribute not in the Rhel54VmPlusStorage template" }
}
},
{
"name": "MyRhel54Vm",
"extends": "MyRhel54VmPlusStorage::sc1:sc2:rvm",
"attributes": {
"moab": {"job": {"variables": {"extraVar": "An additional variable not in the Rhel54Vm template"}}},
"sharedData":{ "extraAttribute":"some attribute not in the Rhel54Vm template" }
} },
{
"name": "MyOsStorage",
"extends": "MyRhel54VmPlusStorage::sc1:sc2:oss",
"attributes": {
"moab": {"job": {"variables": {"extraVar2": "An additional variable not in the OpSysStorage template"}}},
"sharedData":{ "extraAttribute":"some attribute not in the OpSysStorage template" }
}
}
]
}Extending Services and Dependencies in a Container Service
To add a services to a container service that were not in the container's service template you first define the new services in the service request. Then you extend the includedServices field of the container with the newly defined services. This will add the new services to any that are already in the container as defined in the service template. It is only possible to add services to a container. It is not possible to remove services from a container that were defined in the container's service template.For example, say the CentosVmPlusStorage service template contains an OpSysStorage service template and a CentosVm service template.CentosVmPlusStorage Service Template
{
"name":"CentosVmPlusStorage",
"type":"container",
…
"includedServices":[
{
"localName":"oss",
"serviceTemplate":"OpSysStorage"
},
{
"localName":"cvm",
"serviceTemplate":"CentosVm"
}
]
}POST http://localhost/mws/rest/services
{
"user":"bob",
"account":"cloud",
"data":[
{
"name":"BobsCentosVmPlusStorage",
"serviceTemplate":"CentosVmPlusStorage",
"includedServices":[
"NewStorageToAdd1",
"NewStorageToAdd2"
]
},
{
"name":"NewStorageToAdd1",
"serviceTemplate":"ExtraStorage"
},
{
"name":"NewStorageToAdd2",
"serviceTemplate":"ExtraStorage"
}
]
}POST http://localhost/mws/rest/services
{
"user":"bob",
"account":"cloud",
"data":[
{
"name":"BobsCentosVmPlusStorage",
"serviceTemplate":"CentosVmPlusStorage",
"includedServices":[
"NewStorageToAdd1",
"NewStorageToAdd2"
],
"attributes":{
"moab":{
"dependencies":[
{
"service":"BobsCentosVm",
"dependency":[
"NewStorageToAdd1",
"NewStorageToAdd2"
]
}
]
}
}
},
{
"name":"BobsCentosVm",
"extends":"CentosVmPlusStorage:cvm"
},
{
"name":"NewStorageToAdd1",
"serviceTemplate":"ExtraStorage"
},
{
"name":"NewStorageToAdd2",
"serviceTemplate":"ExtraStorage"
}
]
}Extendable Fields
You can only extend certain fields. Below is a table of fields that can be extended:| Extendable Fields | Notes |
|---|---|
| attributes.moab.dependencies | Dependencies can be added but not removed. Only applicable to containers. |
| attributes.moab.job.features | Features can be added but not removed. |
| attributes.moab.job.requestedHosts | Hosts can be added but not removed. |
| attributes.moab.job.resources | Including procs, mem, disk, and any generic resource. |
| attributes.moab.job.variables | Can either change the value of variables in the template or add new variables. |
| attributes.sharedData | A place for arbitrary, site-specific data. |
| image | |
| includedServices | Services can be added but not removed. Only applicable to containers. |
| label |
Sample Response
If the request was successful, the response includes the unique ID of the new Service. On failure, the response is an error message.JSON Response
{"name":"MyRhel54VmPlusStorage.1"}4.19.2.2 Create Custom Service
URLs and Parameters
POST http://localhost/mws/rest/services[?proxy-user=bob]
| Parameter | Required | Valid Values | Description | Example |
|---|---|---|---|---|
| proxy-user | No | String | The name of the user creating the service. | proxy-user=bob |
Request Body
The payload below shows all the fields that are available during service submission.POST http://localhost/mws/rest/services
{
"user":"adaptive",
"account":"cloud",
"startDateRequested": "2011-11-08 13:18:47 MST",
"durationRequested": 86400,
"data":[
{
"name":"myNewService",
"type":"container",
"label":"My New Service",
"includedServices":[
"myVmContainer",
"myNetworkStorageWorkflow",
"myPmContainer"
],
"attributes":{
"moab":{
"dependencies":[
{
"dependency":[
"myNetworkStorageWorkflow"
],
"service":"myVmWorkflow"
}
]
},
"sharedData":{
"extraAttribute":"Some arbitrary value",
"extraAttribute2":"Another arbitrary value"
}
}
},
{
"name":"myVmContainer",
"type":"container",
"includedServices":[
"myVmWorkflow",
"myOsStorageWorkflow"
],
"attributes":{
"moab":{
"dependencies":[
{
"dependency":[
"myOsStorageWorkflow"
],
"service":"myVmWorkflow"
}
]
}
}
},
{
"name":"myVmWorkflow",
"type":"vm",
"includedServices":[ ],
"attributes":{
"moab":{
"job":{
"resources":{
"procs":2,
"mem":2048,
"disk":80
},
"variables":{
"QOS":"Premium"
},
"image":"centos5.5-stateless",
"template":"genericVM",
"requestedHosts":["i16"],
"features":["vlan3"]
}
}
}
},
{
"name":"myOsStorageWorkflow",
"type":"storage",
"includedServices":[ ],
"attributes":{
"moab":{
"job":{
"template":"OSStorage",
"resources":{
"OS":2500
}
}
}
}
},
{
"name":"myNetworkStorageWorkflow",
"type":"storage",
"includedServices":[ ],
"attributes":{
"moab":{
"job":{
"template":"extraStorage",
"resources":{
"gold":500
},
"variables":{
"mount":"/path/to/mount"
}
}
}
}
},
{
"name":"myPmContainer",
"type":"container",
"includedServices":[
"myPmWorkflow"
]
},
{
"name":"myPmWorkflow",
"type":"pm",
"includedServices":[ ],
"attributes":{
"moab":{
"job":{
"resources":{
"procs":2,
"mem":2048,
"disk":100
},
"variables":{
"QOS":"Premium"
},
"image":"centos5.5-stateless",
"template":"genericPM"
}
}
}
}
]
}Sample Response
If the request was successful, the response includes the unique ID of the new Service. On failure, the response is an error message.JSON Response
{"name":"myNewService.1"}4.19.3 Modifying Services
The HTTP PUT method is used to modify Services.Quick Reference
PUT http://localhost/mws/rest/services/<id> PUT http://localhost/mws/rest/services/<name>
4.19.3.1 Modify Service
URLs and Parameters
PUT http://localhost/mws/rest/services/<id> PUT http://localhost/mws/rest/services/<name>
| Parameter | Required | Type | Valid Values | Description |
|---|---|---|---|---|
| id | Yes | String | - | The unique identifier of the Service. |
| name | Yes | String | - | The name of the Service . |
Only one of id or name are required.
Example Request
Only theattributes, status, and statusCode fields may be modified in services.
Note that the status field must be a valid string, and the statusCode field
must be a valid number (long). Any arbitrary string and number may be used to represent
the current state of the service through status and statusCode respectively.PUT http://localhost:8080/mws/rest/services/myStorageService
{
"status": "Done provisioning!",
"statusCode": 200,
"attributes": {
"mount": "/mnt/myMount",
"size": "2500",
"sharedData":{
"extraAttribute":"Some arbitrary value",
"extraAttribute2":"Another arbitrary value"
}
}
}
The moab element of attributes cannot be modified. An error will be returned
if this is attempted.
Sample Response
JSON Response
{
"name": "myStorageService",
"dateCreated": "2012-02-01 14:54:52 UTC",
"lastUpdated": "2012-02-01 14:54:52 UTC",
"type": "storage",
"label": null,
"user": "john",
"account": "corp",
"status": "Done provisioning!",
"statusCode": 200,
"includedServices": [],
"parent": "myVmWithStorage",
"attributes": {
"moab": {
"vc ": {
"id": "vc3"
},
"job": {
"id": "Moab.1",
"template": "extraStorage",
"resources": {
"gold": 2500
}
}
},
"sharedData":{
"extraAttribute":"Some arbitrary value",
"extraAttribute2":"Another arbitrary value"
},
"mount": "/mnt/myMount",
"size": "2500"
},
"id": "4f29b4abe4b03c2f8e3a1a40"
}4.19.4 Deleting Services
The HTTP DELETE method is used to delete Services.Quick Reference
DELETE http://localhost/mws/rest/services/<id> DELETE http://localhost/mws/rest/services/<name>
4.19.4.1 Delete Service
URLs and Parameters
DELETE http://localhost/mws/rest/services/<id>[?proxy-user=bob] DELETE http://localhost/mws/rest/services/<name>[?proxy-user=bob]
| Parameter | Required | Type | Valid Values | Description |
|---|---|---|---|---|
| force-delete | No | Boolean | - | If true MWS will not check service dependencies before deleting it. |
| id | Yes | String | - | The unique identifier of the Service. |
| name | Yes | String | - | The name of the Service. |
| proxy-user | No | String | The name of the user deleting the service. | proxy-user=bob |
Only one of id or name are required.
Sample Response
JSON Response
{}4.20 Service Templates
This section describes the behavior of the Service Template object in Moab Web Services. It contains the URLs, request bodies, and responses delivered to and from Moab Web Services.The Service Template API contains the type and description of all fields in the ServiceTemplate object. It also contains details regarding which fields are valid during PUT and POST actions.
See Create Service From Service Template to create Services from Service Templates.
The Service Template name has the following constraints:
- It must contain only letters, digits, spaces, and these special characters: underscore, comma, hyphen, period, question mark, at sign, tilde, pound sign, square brackets, angle brackets, vertical bar, equals sign, ampersand, parentheses, asterisk, curly braces, grave accent, and dollar sign.
- It cannot have the same form as a MongoDB ID (24 characters of 0-9 and a-f)
- It must be unique in the database.
Supported Methods
| Resource | GET | PUT | POST | DELETE |
|---|---|---|---|---|
| /rest/service-templates | Get all Service Templates | Create ServiceTemplate | ||
| /rest/service-templates/id or name | Get specified Service Template | Modify ServiceTemplate | Cancel Service Template |
4.20.1 Getting Service Templates
The HTTP GET method is used to retrieve Service Template information. Queries for all objects and a single object are available.Quick Reference
GET http://localhost/mws/rest/service-templates[?query={"field":"value"}&sort={"field":<1|-1>}]
GET http://localhost/mws/rest/service-templates/<id>
GET http://localhost/mws/rest/service-templates/<name>4.20.1.1 Get All Service Templates
URLs and Parameters
GET http://localhost/mws/rest/service-templates[?query={"field":"value"}&sort={"field":<1|-1>}]| Parameter | Required | Valid Values | Description | Example |
|---|---|---|---|---|
| query | No | JSON | Query for specific results. | query={"type":"vm","createdBy":"name"} |
| sort | No | JSON | Sort the results. Use 1 for ascending and -1 for descending. | sort={"name":1} |
Sample Response
JSON Response
{
"totalCount": 5,
"resultCount": 5,
"results": [
{
"id": "4f04a93f84ae17912ae2763e",
"label": "Linux ESA",
"type": "vm",
"name": "LinEsaTemplate",
"modified": "2011-07-04 00:00:00 MDT",
"createdBy": "TempName",
"includedServices": [],
"tags": [
"tag0",
"tag1"
],
"attributes": {
"dependencies": {
"service": "tid.1",
"dependency": [
"tid.2",
"tid.3"
]
},
"job": {
"image": "rhel54-stateless",
"resources": {
"procs": 1,
"mem": 1024,
"ipaddress": 1
},
"template": "new-vm",
"variables": {
"foo": "bar"
}
},
"viewpoint": {
"name": "",
"service-description": "",
"form": {
"f0": "zero",
"f1": "one"
},
"access": {}
}
}
},
{
"id": "4f05dd1484ae18e002b22d92",
"label": "Linux ESA",
"type": "vm",
"name": "LinEsa004",
"modified": "2011-07-04 00:00:00 MDT",
"createdBy": "TempName",
"includedServices": [
{
"localName": "SQLServ004",
"serviceTemplate": "LinEsaTemplate"
}
],
"tags": [
"tag0",
"tag1"
],
"attributes": {
"dependencies": {
"service": "tid.1",
"dependency": [
"tid.2",
"tid.3"
]
},
"job": {
"image": "rhel54-stateless",
"resources": {
"procs": 1,
"mem": 1024,
"ipaddress": 1
},
"template": "new-vm",
"variables": {
"foo": "bar"
}
},
"viewpoint": {
"name": "",
"service-description": "",
"form": {
"f0": "zero",
"f1": "one"
},
"access": {}
}
}
},
{
"id": "4f05dd7484ae18e002b22d93",
"label": "Linux ESA",
"type": "vm",
"name": "R",
"modified": "2011-07-04 00:00:00 MDT",
"createdBy": "TempName",
"includedServices": [
{
"localName": "SQLServ004",
"serviceTemplate": "LinEsaTemplate"
}
],
"tags": [
"tag0",
"tag1"
],
"attributes": {
"dependencies": {
"service": "tid.1",
"dependency": [
"tid.2",
"tid.3"
]
},
"job": {
"image": "rhel54-stateless",
"resources": {
"procs": 1,
"mem": 1024,
"ipaddress": 1
},
"template": "new-vm",
"variables": {
"foo": "bar"
}
},
"viewpoint": {
"name": "",
"service-description": "",
"form": {
"f0": "zero",
"f1": "one"
},
"access": {}
}
}
},
{
"id": "4f05e41f84ae18e002b22d94",
"label": "Linux ESA",
"type": "vm",
"name": "5",
"modified": "2011-07-04 00:00:00 MDT",
"createdBy": "TempName",
"includedServices": [
{
"localName": "SQLServ004",
"serviceTemplate": "LinEsaTemplate"
}
],
"tags": [
"tag0",
"tag1"
],
"attributes": {
"dependencies": {
"service": "tid.1",
"dependency": [
"tid.2",
"tid.3"
]
},
"job": {
"image": "rhel54-stateless",
"resources": {
"procs": 1,
"mem": 1024,
"ipaddress": 1
},
"template": "new-vm",
"variables": {
"foo": "bar"
}
},
"viewpoint": {
"name": "",
"service-description": "",
"form": {
"f0": "zero",
"f1": "one"
},
"access": {}
}
}
},
{
"id": "4f05e4a284ae18e002b22d95",
"label": "Linux ESA",
"type": "vm",
"name": "LinEsaServ001",
"modified": "2011-07-04 00:00:00 MDT",
"createdBy": "TempName",
"includedServices": [
{
"localName": "SQLServ004",
"serviceTemplate": "LinEsaTemplate"
}
],
"tags": [
"tag0",
"tag1"
],
"attributes": {
"dependencies": {
"service": "tid.1",
"dependency": [
"tid.2",
"tid.3"
]
},
"job": {
"image": "rhel54-stateless",
"resources": {
"procs": 1,
"mem": 1024,
"ipaddress": 1
},
"template": "new-vm",
"variables": {
"foo": "bar"
}
},
"viewpoint": {
"name": "",
"service-description": "",
"form": {
"f0": "zero",
"f1": "one"
},
"access": {}
}
}
}
]
}Querying Service Templates
It is possible to query service templates by one or more fields based on the MongoDB query syntax.Simple Queries
To see only service templates that are associated with the user "bob", use a query like the following:http://localhost/mws/rest/service-templates?query={"user":"bob"}http://localhost/mws/rest/service-templates?query={"type":"vm"}http://localhost/mws/rest/service-templates?query={"user":"bob","type":"vm"}http://localhost/mws/rest/service-templates?query={"user":{"$ne":"bob"}}More Complex Queries
When the field values of the desired service templates are a finite set, use the$in operator.
For example, to see service templates that belong to either bob, alice, or charlie, do the following:http://localhost/mws/rest/service-templates?query={"user":{"$in":["alice","bob","charlie"]}}http://localhost/mws/rest/service-templates?query={"attributes.moab.job.resources.procs":3}Conditional Operators
You can perform<, <=, >, >= comparisons using the $lt, $lte, $gt, $gte operators.| Operator | Comparison | |
|---|---|---|
| $lt | < | |
| $lte | <= | |
| $gt | > | |
| $gte | >= |
http://localhost/mws/rest/service-templates?query={"attributes.moab.job.resources.procs":{"$lt":2}}http://localhost/mws/rest/service-templates?query={"attributes.moab.job.resources.mem":{"$gte":1024}}Querying Service Templates by Date
To see all service templates modified after July 4, 2011 at 10:30:00 PM Mountain Standard Time (MST):http://localhost/mws/rest/service-templates?query={"modified":{"$gt":"2011-07-04 22:30:00 MST"}}http://localhost/mws/rest/service-templates?query={"modified":{"$lt":"2011-07-06 00:00:00 PST"}}http://localhost/mws/rest/service-templates?query={"modified":{"$gte":"2011-07-05 00:00:00 EST","$lte":"2011-07-05 23:59:00 EST"}}Sorting
See the sorting section in Global URL Parameters.Limiting the Number of Results
To limit the size of the result set, use themax parameter. For
example, to see only 10 of bob's services:http://localhost/mws/rest/service-templates?query={"user":"bob"}&sort={"name":1}&max=10max with offset as follows:http://localhost/mws/rest/service-templates?query={"user":"bob"}&sort={"name":1}&max=10&offset=90Retrieving a Subset of Fields
To retrieve only certain fields, use thefields parameter. For example,
to show only the name field for each service:http://localhost/mws/rest/service-templates?fields=name
{
"totalCount": 9,
"resultCount": 3,
"results": [
{"name": "aliceService.1"},
{"name": "machine0.1"},
{"name": "OSStoremachine0.1"}
]
}http://localhost/mws/rest/service-templates?fields=name,type,user
{
"totalCount": 9,
"resultCount": 3,
"results": [
{
"name": "aliceService.1",
"type": "container",
"user": "alice"
},
{
"name": "machine0.1",
"type": "vm",
"user": "alice"
},
{
"name": "OSStoremachine0.1",
"type": "storage",
"user": "alice"
}
]
}4.20.1.2 Get Single Service Template
URLs and Parameters
GET http://localhost/mws/rest/service-templates/<id> GET http://localhost/mws/rest/service-templates/<name>
| Parameter | Required | Valid Values | Description |
|---|---|---|---|
| id | Yes | String (24 character alphanumeric) | The unique identifier of the service template. |
| name | Yes | String | The name of the service template. |
Only one of id or name is required.
Response
JSON Response
{
"totalCount": 1,
"resultCount": 1,
"results": [ {
"id": "...",
…
}]
}4.20.2 Creating Service Templates
The HTTP POST method is used to create Service Templates.Quick Reference
POST http://localhost/mws/rest/service-templates
4.20.2.1 Create Service Template
URLs and Parameters
POST http://localhost/mws/rest/service-templates
Request Body
The request body below shows some of the fields that are available when creating a Service Template, along with some sample values.JSON Request Body
{
"attributes": {
"moab": {
"dependencies": [
{
"dependency": [
"oss",
"ns"
],
"localName": "rvm"
}
],
"job": {
"features": [
"vlan3"
],
"image": "centos5.5-stateless",
"requestedHosts": [
"i16"
],
"resources": {
"disk": 80,
"mem": 2048,
"procs": 1
},
"template": "genericVM",
"variables": {
"QOS": "Premium"
}
}
}
},
"createdBy": "bob",
"includedServices": [
{
"localName": "rvm",
"serviceTemplate": "Rhel54Vm"
},
{
"localName": "oss",
"serviceTemplate": "OpSysStorage"
},
{
"localName": "ns",
"serviceTemplate": "NetworkStorage"
}
],
"label": "Redhat Enterprise Linux 5.4 VM Plus OS and Network Storage",
"modified": "2011-07-04 00:00:00 MDT",
"name": "Rhel54VmPlusStorage",
"tags": [],
"type": "container"
}includedServices is a key-value pair of the internal service name and the serviceTemplate. The service name is unique for each service container.
Sample Response
JSON Response for successful POST
{"id":"4f06111184ae2bbfa31fa4c7"}If the Service Template name is not unique:
JSON Response
{
"messages": [
"Service template Rhel54Vm could not be created",
"Request has a non-unique service template name 'Rhel54Vm'",
"Please correct the request and try again"
]
}If the Service Template included service local name is not unique to this service template:
JSON Response
{
"messages": [
"Service template CentOS5 could not be created",
"Service template request has a non-unique included service template local name ([SQLServ05])",
"Please correct the request and try again"
]
}
}If the Service Template depends on a non-existent included service:
JSON Response
{
"messages": [
"Service template NSStor34 could not be created",
"Service template requires service template(s) [NewRhel54Vm] which do not exist",
"Please correct the request and try again"
]
}If the Service Template depends on more than one non-existent included service:
JSON Response
{
"messages": [
"Service template NSStor34 could not be created",
"Service template requires service template(s) [NewRhel54Vm, Storage003] which do not exist",
"Please correct the request and try again"
]
}If the Service Template name contains a colon:
JSON Response
{
{
"messages": [
"Service template Rhel54Vm:C could not be created",
"Request contains a colon (:) in the service template name 'Rhel54Vm:C'",
"Please correct the request and try again"
]
}If the Service Template name has the same format as a MongoDB ID (Service Template ID):
JSON Response
{
"messages": [
"Service template 4f2049a684ae6e1d4f09bd71 could not be created",
"Request has a MongoDB Object ID format for the service template name '4f2049a684ae6e1d4f09bd71'",
"Please correct the request and try again"
]
}4.20.3 Modifying Service Templates
The HTTP PUT method is used to modify Service Templates.The modified field is not automatically updated. It will need to be changed
by the user.Quick Reference
PUT http://localhost/mws/rest/service-templates/<id> PUT http://localhost/mws/rest/service-templates/<name>
4.20.3.1 Modify Service Template
URLs and Parameters
PUT http://localhost/mws/rest/service-templates/<id> PUT http://localhost/mws/rest/service-templates/<name>
| Parameter | Required | Valid Values | Description |
|---|---|---|---|
| id | Yes | String (24 character alphanumeric) | The unique identifier of the service template. |
| name | Yes | String | The name of the service template. |
Only one of id or name is required.
Request Body
This is similar to create, except you change the request body to what you need modified.The request body below shows some of the fields that are available when modifying a Service Template, along with some sample values.{
"attributes": {
"dependencies": {
"dependency": [
"tid.2",
"tid.3"
],
"service": "tid.1"
},
"job": {
"image": "rhel54-stateless",
"resources": {
"ipaddress": 1,
"mem": 1024,
"procs": 1
},
"template": "new-vm",
"variables": {
"foo": "bar"
}
},
"viewpoint": {
"access": {},
"form": {
"f0": "zero",
"f1": "one"
},
"name": "",
"service-description": ""
}
},
"createdBy": "Newname",
"includedServices": [],
"modified": "2011-07-04 00:00:00 MDT",
"name": "A",
"tags": [
"database",
"ele45",
"tag56"
],
"type": "RhOs"
}Sample Response
JSON Response for successful PUT
{
"resultCount": 1,
"results": [
{
"attributes": {
"dependencies": {
"dependency": [
"tid.2",
"tid.3"
],
"service": "tid.1"
},
"job": {
"image": "rhel54-stateless",
"resources": {
"ipaddress": 1,
"mem": 1024,
"procs": 1
},
"template": "new-vm",
"variables": {
"foo": "bar"
}
},
"viewpoint": {
"access": {},
"form": {
"f0": "zero",
"f1": "one"
},
"name": "",
"service-description": ""
}
},
"createdBy": "Newname",
"id": "4f0746f684ae23bbd6726852",
"includedServices": [],
"label": "Linux ESA",
"modified": "2011-07-04 00:00:00 MDT",
"name": "RhOs004",
"tags": [
"database",
"ele45",
"tag56"
],
"type": "RhOs"
}
],
"totalCount": 1
}If the Service Template depends on a non-existent included service:
JSON Response
{
"messages": [
"Service template NewR could not be updated",
"Service template requires service template(s) [RhOs045] which do not exist",
"Please correct the request and try again"
]
}If the Service Template depends on more than one non-existent included service:
JSON Response
{
"messages": [
"Service template NewR could not be updated",
"Service template requires service template(s) [Stor45, Stor12] which do not exist",
"Please correct the request and try again"
]
}An attempt to modify the Service Template name to an existing template name:
JSON Response
{
"messages": [
"Service template NewR could not be updated",
"Request has a non-unique service template name 'Stor44'"
]
}4.20.4 Deleting (Canceling) Service Templates
The HTTP DELETE method is used to delete Service Templates.Quick Reference
DELETE http://localhost/mws/rest/service-templates/<id> DELETE http://localhost/mws/rest/service-templates/<name>
4.20.4.1 Cancel Service Template
URLs and Parameters
DELETE http://localhost/mws/rest/service-templates/<id|name>| Parameter | Required | Valid Values | Description |
|---|---|---|---|
| id | Yes | String (24 character alphanumeric) | The unique identifier of the service template. |
| name | Yes | String | The name of the service template. |
Only one of id or name is required.
Response
A successful deletion
JSON Response
{}If the Service Template ID does not exist
JSON Response
{
"messages": [
"Service template not found with ID '4f2049a684ae6e1d4f09bd71'"
]
}If the Service Template name does not exist
JSON Response
{
"messages": [
"Service template not found with ID 'Stor44'"
]
}If other Service Templates depend on the one being deleted
JSON Response
{
"messages": [
"Service template Cent5 could not be deleted",
"Service template 'Cent5' cannot be deleted because Service template '[Cent5]' depends on it "
]
}4.21 Standing Reservations
This section describes behavior of the Standing Reservation object in Moab Web Services. It contains the URLs, request bodies, and responses delivered to and from Moab Web Services.The Standing Reservation API contains the type and description of all fields in the Standing Reservation object. It also contains details regarding which fields are valid during PUT and POST actions.
Supported Methods
| Resource | GET | PUT | POST | DELETE |
|---|---|---|---|---|
| /rest/standing-reservations | Get all standing reservations | |||
| /rest/standing-reservations/id | Get specified standing reservation |
4.21.1 Getting Standing Reservations
The HTTP GET method is used to retrieve Standing Reservation information. Queries for all objects and a single object are available.Quick Reference
GET http://localhost/mws/rest/standing-reservations/<id>4.21.1.1 Get All Standing Reservations
URLs and Parameters
GET http://localhost/mws/rest/standing-reservations
Sample Response
GET http://localhost/mws/rest/standing-reservations?fields=id
{
"totalCount": 3,
"resultCount": 3,
"results": [
{"id": "sr1"},
{"id": "sr2"},
{"id": "sr3"}
]
}4.21.1.2 Get Single Standing Reservation
URLs and Parameters
GET http://localhost/mws/rest/standing-reservations/<id>| Parameter | Required | Type | Valid Values | Description |
|---|---|---|---|---|
| id | Yes | String | - | The unique identifier of the object. |
Sample Response
JSON Response
{
"access": "DEDICATED",
"accounts": ["account1"],
"aclRules": [ {
"affinity": "POSITIVE",
"comparator": "EQUAL",
"type": "USER",
"value": "adaptive",
}],
"chargeAccount": "account2",
"chargeUser": "user2",
"classes": ["class1"],
"clusters": ["cluster1"],
"comment": "comment",
"days": ["Monday"],
"depth": 2,
"disabled": false,
"endOffset": 86415,
"flags": ["ALLOWJOBOVERLAP"],
"groups": ["group1"],
"hosts": ["host1"],
"id": "fast",
"jobAttributes": ["TEMPLATESAPPLIED"],
"maxJob": 2,
"maxTime": 0,
"messages": ["message1"],
"nodeFeatures": ["feature1"],
"os": "Ubuntu 10.04.3",
"owner": {
"name": "root",
"type": "USER"
},
"partition": "ALL",
"period": "DAY",
"procLimit": {
"qualifier": "<=",
"value": 5
},
"psLimit": {
"qualifier": "<=",
"value": 60
},
"qoses": ["qos1"],
"reservationAccessList": [],
"reservationGroup": "group2",
"resources": {
"PROCS": -1,
"tapes": 1
},
"rollbackOffset": 43200,
"startOffset": 347040,
"taskCount": 0,
"tasksPerNode": 0,
"timeLimit": -1,
"triggers": [],
"type": "type1",
"users": ["user1"]
}4.22 Usage Records
This section describes behavior of the Usage Record object in Moab Web Services. It contains the URLs, request bodies, and responses delivered to and from Moab Web Services.The Usage Record API contains the type and description of all fields in the UsageRecord object.
Supported Methods
| Resource | GET | PUT | POST | DELETE |
|---|---|---|---|---|
| /rest/usage-records | Get all usage-records | |||
| /rest/usage-records/id | Get specified usage-record |
4.22.1 Getting Usage Records
The HTTP GET method is used to retrieve Usage Record information.Quick Reference
GET http://localhost/mws/rest/usage-records?proxy-user=<USER>[&custom-fields=QualityOfService][&query={"id":"2"}][&sort={"Stage":-1}] GET http://localhost/mws/rest/usage-records/<id>?proxy-user=<USER>[&custom-fields=QualityOfService]
4.22.1.1 Get All Usage Records
URLs and Parameters
GET http://localhost/mws/rest/usage-records?proxy-user=<USER>[&custom-fields=QualityOfService][&query={"id":"2"}][&sort={"stage":-1}]
| Parameter | Required | Valid Values | Description | Example |
|---|---|---|---|---|
| proxy-user | Yes | String | Perform action as defined MAM user. | proxy-user=amy |
| custom-fields | No | Comma-Separated String | Includes custom MAM usage-record attributes. | custom-fields=QualityOfService |
| query | No | JSON | Query for specific results. | query={"priority":"2","allocation.active":"false"} |
| sort | No | JSON | Sort the results. Use 1 for ascending and -1 for descending. | sort={"stage":-1} |
The query parameter does not support the full Mongo query syntax. Only querying for a simple,
non-nested JSON object is allowed.See Global URL Parameters for available URL parameters.Sample Response
GET http://localhost/mws/rest/usage-records?proxy-user=amy&custom-fields=qualityOfService&fields=id,qualityOfService,type,instance
{
"totalCount": 8,
"resultCount": 2,
"results": [
{
"id": 1,
"qualityOfService": "premium",
"type": "Job",
"instance": "job.123"
},
{
"qualityOfService": "premium",
"id": 2,
"type": "Job",
"instance": "job.1234"
}
]
}4.22.1.2 Get Single Usage Record
URLs and Parameters
GET http://localhost/mws/rest/usage-records/<id>?proxy-user=<USER>[&custom-fields=QualityOfService]
| Parameter | Required | Type | Valid Values | Description |
|---|---|---|---|---|
| id | Yes | String | - | The unique identifier of the object. |
| proxy-user | Yes | String | Perform action as defined MAM user. | proxy-user=amy |
| custom-fields | No | Comma-Separated String | Includes custom MAM usage-record attributes. | custom-fields=QualityOfService |
Sample Responses
GET http://localhost/mws/rest/usage-records/1?proxy-user=amy&custom-fields=qualityOfService
{
"id": 1,
"qualityOfService": "premium",
"type": "Job",
"instance": "job.123",
"charge": 0,
"stage": "Create",
"quote": "",
"user": "doug",
}4.23 Virtual Containers
This section describes behavior of the Virtual Container object in Moab Web Services. It contains the URLs, request bodies, and responses delivered to and from Moab Web Services.The Virtual Container API contains the type and description of all fields in the Virtual Container object. It also contains details regarding which fields are valid during PUT and POST actions.
Supported Methods
| Resource | GET | PUT | POST | DELETE |
|---|---|---|---|---|
| /rest/vcs | Get all Virtual Containers | Create Virtual Container | ||
| /rest/vcs/id | Get specified Virtual Container | Modify Virtual Container | Destroy Virtual Container |
4.23.1 Getting Virtual Containers
The HTTP GET method is used to retrieve Virtual Container information. Queries for all objects and a single object are available.Quick Reference
GET http://localhost/mws/rest/vcs/<id>4.23.1.1 Get All Virtual Containers
URLs and Parameters
GET http://localhost/mws/rest/vcs
Sample Response
GET http://localhost/mws/rest/vcs?fields=id
{
"totalCount": 5,
"resultCount": 5,
"results": [
{"id": "vc3"},
{"id": "vc1"},
{"id": "vc4"},
{"id": "vc5"},
{"id": "vc2"}
]
}4.23.1.2 Get Single Virtual Container
URLs and Parameters
GET http://localhost/mws/rest/vcs/<id>| Parameter | Required | Type | Valid Values | Description |
|---|---|---|---|---|
| id | Yes | String | - | The unique identifier of the object. |
Sample Response
JSON Response
{
"aclRules": [ {
"affinity": "POSITIVE",
"comparator": "LEXIGRAPHIC_EQUAL",
"type": "USER",
"value": "root"
}],
"createDate": "2011-11-15 14:01:40 MST",
"creator": "root",
"description": "vc2",
"flags": ["DESTROYWHENEMPTY"],
"id": "vc2",
"jobs": [
{"id":"Moab.1"}
],
"nodes": [
{"id":"node1"}
],
"owner": {
"name": "root",
"type": "USER"
},
"reservations": [
{"id":"system.1"}
],
"variables": {
"a": "b",
"c": "d"
},
"virtualContainers": [
{"id":"vc3"}
],
"virtualMachines": [
{"id":"vm1"}
]
}4.23.2 Creating Virtual Containers
The HTTP POST method is used to create Virtual Containers.Quick Reference
POST http://localhost/mws/rest/vcs[?proxy-user=<username>]Restrictions
- The proxy-user parameter is ignored unless you set
ENABLEPROXY=TRUEin themoab.cfgfile. Example:
ADMINCFG[1] USERS=root,ted ENABLEPROXY=TRUE
4.23.2.1 Create Virtual Container
URLs and Parameters
POST http://localhost/mws/rest/vcs[?proxy-user=<username>]| Parameter | Required | Type | Valid Values | Description |
|---|---|---|---|---|
| proxy-user | No | String | - | Perform the action as this user. |
Request Body
The request body below shows all the fields that are available when creating a Virtual Container, along with some sample values.JSON Request Body
{
"description": "ted's vc",
"owner": {
"name": "ted",
"type": "USER"
},
"requiredStartDate": "2012-11-08 13:18:47 MST",
"flags": ["HOLDJOBS"],
"virtualContainers": [
{"id": "vc93"},
{"id": "vc94"}
],
}Sample Response
JSON Response for successful POST
{"id": "vc8"}Restrictions
- When creating a Virtual Container, the
creatorfield is set to the value ofproxy-user(if set) orowner.name(if set), withproxy-usertaking precedence. However, setting thecreatorfield works only if you setENABLEPROXY=TRUEin themoab.cfgfile. Example:
ADMINCFG[1] USERS=root,ted ENABLEPROXY=TRUE
- You can set the
creatorfield as shown above, but you can never change it.
4.23.3 Modifying Virtual Containers
The HTTP PUT method is used to modify Virtual Containers.Quick Reference
PUT http://localhost/mws/rest/vcs/<id>?change-mode=<add|remove|set>[&proxy-user=<username>]
Restrictions
- The proxy-user parameter is ignored unless you set
ENABLEPROXY=TRUEin themoab.cfgfile. Example:
ADMINCFG[1] USERS=root,ted ENABLEPROXY=TRUE
4.23.3.1 Modify Virtual Container
URLs and Parameters
PUT http://localhost/mws/rest/vcs/<id>?change-mode=<add|remove|set>[&proxy-user=<username>]
| Parameter | Required | Type | Valid Values | Description |
|---|---|---|---|---|
| id | Yes | String | - | The unique identifier of the object. |
| change-mode | Yes | String | add | Add the given objects (jobs, VMs, etc) to the objects that already exist. |
| remove | Delete the given objects from the objects that already exist. | |||
| set | Modify the attributes of the virtual container itself and not the associated objects. | |||
| proxy-user | No | String | - | Perform the action as this user. |
Request Body
Here are three examples of Virtual Container updates: add objects, remove objects, and update attributes. In each case, the examples below show all the fields that are available, along with some sample values.Add objects with /rest/vcs/vc1?change-mode=add
{
"jobs": [
{"id": "Moab.37"},
{"id": "Moab.38"}
],
"nodes": [
{"id": "node1"},
{"id": "node2"}
],
"reservations": [
{"id": "system.48"},
{"id": "system.49"}
],
"virtualContainers": [
{"id": "vc93"},
{"id": "vc94"}
],
"virtualMachines": [
{"id": "vm2"},
{"id": "vm4"}
]
}Remove objects with /rest/vcs/vc1?change-mode=remove
{
"jobs": [
{"id": "Moab.37"},
{"id": "Moab.38"}
],
"nodes": [
{"id": "node1"},
{"id": "node2"}
],
"reservations": [
{"id": "system.48"},
{"id": "system.49"}
],
"virtualContainers": [
{"id": "vc93"},
{"id": "vc94"}
],
"virtualMachines": [
{"id": "vm2"},
{"id": "vm4"}
]
}Modify VC attributes with /rest/vcs/vc1?change-mode=set
{
"description": "This is a new description.",
"flags": ["HOLDJOBS"],
"owner": {
"name": "ted",
"type": "USER"
},
"variables": {
"a": "b",
"c": "d"
}
}Sample Responses
These messages may not match the messages returned from Moab exactly, but they are given as examples of the structure of the responses.
JSON response for adding objects
{
"messages":[
"job '147' added to VC 'vc3'",
"job 'Moab.1' added to VC 'vc3'"
]
}JSON response for removing objects
{
"messages":[
"job '147' removed from VC 'vc3'",
"job 'Moab.1' removed from VC 'vc3'"
]
}JSON response for updating attributes
{"messages":["VC 'vc3' successfully modified"]}Restrictions
- You can change the ACL Rules on a Virtual Container, but not using this resource. See Create or Update ACLs.
4.23.4 Destroying Virtual Containers
The HTTP DELETE method is used to destroy Virtual Containers.Quick Reference
DELETE http://localhost/mws/rest/vcs/<id>[?proxy-user=<username>]
Restrictions
- The proxy-user parameter is ignored unless you set
ENABLEPROXY=TRUEin themoab.cfgfile. Example:
ADMINCFG[1] USERS=root,ted ENABLEPROXY=TRUE
4.23.4.1 Destroy Virtual Container
URLs and Parameters
DELETE http://localhost/mws/rest/vcs/<id>[?proxy-user=<username>]
| Parameter | Required | Type | Valid Values | Description |
|---|---|---|---|---|
| id | Yes | String | - | The unique identifier of the object. |
| proxy-user | No | String | - | Perform the action as this user. |
Sample Response
JSON Response for successful DELETE
{}4.24 Virtual Machines
This section describes behavior of the Virtual Machine object in Moab Web Services. It contains the URLs, request bodies, and responses delivered to and from Moab Web Services.The Virtual Machine API contains the type and description of all fields in the Virtual Machine object. It also contains details regarding which fields are valid during PUT and POST actions.
Supported Methods
| Resource | GET | PUT | POST | DELETE |
|---|---|---|---|---|
| /rest/vms | Get all VMs | Create VM | ||
| /rest/vms/id | Get specified VM | Modify VM | Destroy VM | |
| /rest/nodes/nodeId/vms | Get all VMs on a Node |
4.24.1 Getting Virtual Machines
The HTTP GET method is used to retrieve Virtual Machine information. Queries for all objects and a single object are available.Quick Reference
GET http://localhost/mws/rest/vms/<id> GET http://localhost/mws/rest/nodes/<nodeId>/vms
4.24.1.1 Get All Virtual Machines
URLs and Parameters
GET http://localhost/mws/rest/vms
Sample Response
GET http://localhost/mws/rest/vms?fields=id
{
"totalCount": 3,
"resultCount": 3,
"results": [
{"id": "vm1"},
{"id": "vm2"},
{"id": "vm3"}
]
}4.24.1.2 Get All Virtual Machines On Node
URLs and Parameters
GET http://localhost/mws/rest/nodes/<nodeId>/vms| Parameter | Required | Type | Valid Values | Description |
|---|---|---|---|---|
| nodeId | Yes | String | - | The ID of the node of interest. |
Sample Response
GET http://localhost/mws/rest/nodes/hv1/vms?fields=id
{
"totalCount": 3,
"resultCount": 3,
"results": [
{"id": "vm1"},
{"id": "vm2"},
{"id": "vm3"}
]
}4.24.1.3 Get Single Virtual Machine
URLs and Parameters
GET http://localhost/mws/rest/vms/<id>| Parameter | Required | Type | Valid Values | Description |
|---|---|---|---|---|
| id | Yes | String | - | The unique identifier of the object. |
Sample Response
JSON Response
{
"aliases": [],
"availableDisk": 1024,
"availableMemory": 512,
"availableProcessors": 0,
"cpuLoad": 0.823,
"description": "",
"effectiveTimeToLive": 0,
"flags": [
"CREATION_COMPLETED",
"CAN_MIGRATE"
],
"genericEvents": [],
"genericMetrics": {"watts": 250},
"id": "vm3",
"job": {"id": "Moab.1"},
"lastMigrationDate": null,
"lastSubstate": "",
"lastSubstateModificationDate": null,
"lastUpdateDate": null,
"migrationCount": 0,
"networkAddress": "10.0.0.5",
"node": {"id": "hv2"},
"osList": [],
"os": "stateless1",
"powerSelectState": "NONE",
"powerState": "ON",
"rack": 0,
"requestedTimeToLive": 0,
"slot": 0,
"startDate": null,
"state": "BUSY",
"substate": "",
"totalDisk": 1024,
"totalMemory": 512,
"totalProcessors": 1,
"trackingJob": {"id": "Moab.5"},
"triggers": [],
"variables": {}
}4.24.2 Creating Virtual Machines
The HTTP POST method is used to create Virtual Machines.Quick Reference
POST http://localhost/mws/rest/vms[?proxy-user=<username>]Restrictions
- The proxy-user parameter is ignored unless you set
ENABLEPROXY=TRUEin themoab.cfgfile. Example:
ADMINCFG[1] USERS=root,ted ENABLEPROXY=TRUE
4.24.2.1 Create Virtual Machine
URLs and Parameters
POST http://localhost/mws/rest/vms[?proxy-user=<username>]| Parameter | Required | Type | Valid Values | Description |
|---|---|---|---|---|
| proxy-user | No | String | - | Perform the action as this user. |
Request Body
The request body below shows all the fields that are available when creating a Virtual Machine, along with some sample values. Note that you can pass in an ID for the Virtual Machine. If you do not, Moab will choose an ID for you.JSON Request Body
{
"totalDisk": 1024,
"totalMemory": 512,
"totalProcessors": 1,
"id": "vm3",
"node": {"id": "hv2"},
"os": "stateless1",
"sovereign":true,
"storage":"os:5'c'%os:10'd'",
"template":"CustomTemplate",
"requestedTimeToLive":10000,
"triggers": [],
"variables": {
"var1": "val1",
"var2": "val2"
}
}Sample Response
JSON Response for successful POST
{"jobId": "vmcreate-25"}The jobId in the response identifies the job that will create the virtual machine.
4.24.3 Modifying Virtual Machines
The HTTP PUT method is used to modify Virtual Machines.Quick Reference
PUT http://localhost/mws/rest/vms/<id>[?proxy-user=<username>]
Restrictions
- The proxy-user parameter is ignored unless you set
ENABLEPROXY=TRUEin themoab.cfgfile. Example:
ADMINCFG[1] USERS=root,ted ENABLEPROXY=TRUE
4.24.3.1 Modify Virtual Machine
URLs and Parameters
PUT http://localhost/mws/rest/vms/<id>[?proxy-user=<username>]
| Parameter | Required | Type | Valid Values | Description |
|---|---|---|---|---|
| id | Yes | String | - | The unique identifier of the object. |
| proxy-user | No | String | - | Perform the action as this user. |
Request Body
The request body below shows all the fields that are available when modifying a Virtual Machine, along with some sample values.JSON Request Body for VM Modify
{
"genericEvents": [],
"genericMetrics": {"watts": 250},
"os": "stateless1",
"powerState": "ON",
"state": "BUSY",
"triggers": [],
"variables": {
"var1": "val1",
"var2": "val2"
}
}Sample Response
This message may not match the message returned from Moab exactly, but is given as an example of the structure of the response.
JSON Response
{"messages":["successfully updated VM variables"]}4.24.3.2 Migrate Virtual Machine
URLs and Parameters
PUT http://localhost/mws/rest/vms/<id>[?proxy-user=<username>]
| Parameter | Required | Type | Valid Values | Description |
|---|---|---|---|---|
| id | Yes | String | - | The unique identifier of the object. |
| proxy-user | No | String | - | Perform the action as this user. |
Request Body
The request body below shows how to migrate a Virtual Machine to a node with ID "hv2".JSON Request Body for VM Migrate to a specific node
{"node": {"id": "hv2"}}JSON Request Body for VM Migrate to any available node
{"node": {"id": "ANY"}}Sample Response
The HTTP response code for this operation is 202 Accepted. See the responses section for more information.
JSON Response
{"jobId": "vm-migrate1"}Restrictions
- If a migration is requested by setting the node as shown in the above examples, any other properties in the same request body will be ignored.
4.24.4 Destroying Virtual Machines
The HTTP DELETE method is used to destroy Virtual Machines.Quick Reference
DELETE http://localhost/mws/rest/vms/<id>[?proxy-user=<username>]
Restrictions
- The proxy-user parameter is ignored unless you set
ENABLEPROXY=TRUEin themoab.cfgfile. Example:
ADMINCFG[1] USERS=root,ted ENABLEPROXY=TRUE
4.24.4.1 Destroy Virtual Machine
URLs and Parameters
DELETE http://localhost/mws/rest/vms/<id>[?proxy-user=<username>]
| Parameter | Required | Type | Valid Values | Description |
|---|---|---|---|---|
| id | Yes | String | - | The unique identifier of the object. |
| proxy-user | No | String | - | Perform the action as this user. |
Sample Response
JSON Response for successful DELETE
{"jobId": "vmdestroy-26"}The jobId in the response identifies the job that will destroy the virtual machine.