Moab Web Services > Resources > Virtual Containers

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 MWS.

The Fields: Virtual Containers reference section 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 Single Virtual Container	Modifying Virtual Containers	--	Destroy Virtual Container

This topic contains these sections:

Getting Virtual Containers
- Get All Virtual Containers
- Get Single Virtual Container
Creating Virtual Containers
- Create Virtual Container
Modifying Virtual Containers
- Modify Virtual Container
Destroying Virtual Containers
- Destroy Virtual Container

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:8080/mws/rest/vcs/<id>?api-version=3

Get All Virtual Containers

URLs and parameters

GET http://localhost:8080/mws/rest/vcs?api-version=3

See Global URL Parameters for available URL parameters.

Sample response

GET http://localhost:8080/mws/rest/vcs?api-version=3&fields=id
------------------------------------

{
  "totalCount": 5,
  "resultCount": 5,
  "results":   [
    {"id": "vc3"},
    {"id": "vc1"},
    {"id": "vc4"},
    {"id": "vc5"},
    {"id": "vc2"}
  ]
}

Get Single Virtual Container

URLs and parameters

GET http://localhost:8080/mws/rest/vcs/<id>?api-version=3

Parameter	Required	Type	Valid values	Description
id	Yes	String	--	The unique identifier of the object

See Global URL Parameters for available URL parameters.

Sample response

JSON response
------------------------------------

{
  "aclRules": [  {
    "affinity": "POSITIVE",
    "comparator": "LEXIGRAPHIC_EQUAL",
    "type": "USER",
    "value": "root"
  }],
  "createDate": "2011-11-15 14:01:40 UTC",
  "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"}
  ]
}

Creating Virtual Containers

The HTTP POST method is used to create Virtual Containers.

Quick reference

POST http://localhost:8080/mws/rest/vcs?api-version=3[&proxy-user=<username>]

Restrictions

The proxy-user parameter is ignored unless you set ENABLEPROXY=TRUE in the moab.cfg file. For example:

ADMINCFG[1]           USERS=root,ted ENABLEPROXY=TRUE

Create Virtual Container

URLs and parameters

POST http://localhost:8080/mws/rest/vcs?api-version=3[&proxy-user=<username>]

Parameter	Required	Type	Valid values	Description
proxy-user	No	String	--	Perform the action as this user.

See Global URL Parameters for available URL parameters.

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 creator field is set to the value of proxy-user (if set) or owner.name (if set). However, setting the creator field works only if you set ENABLEPROXY=TRUE in the moab.cfg file. Example:

ADMINCFG[1]           USERS=root,ted ENABLEPROXY=TRUE

You can set the creator field (as shown above), but you can never change it.

Modifying Virtual Containers

The HTTP PUT method is used to modify Virtual Containers.

Quick reference

PUT http://localhost:8080/mws/rest/vcs/<id>?api-version=3&change-mode=<add|remove|set>[&proxy-user=<username>]

Restrictions

The proxy-user parameter is ignored unless you set ENABLEPROXY=TRUE in the moab.cfg file. For example:

ADMINCFG[1]           USERS=root,ted ENABLEPROXY=TRUE

Modify Virtual Container

URLs and parameters

PUT http://localhost:8080/mws/rest/vcs/<id>?api-version=3&change-mode=<add|remove|set>[&proxy-user=<username>]

Parameter

Required

Type

Valid values

Description

Yes

String

The unique identifier of the object

change-mode

Yes

String

add

remove

set

If add, add the given objects (jobs, VMs, etc) to the objects that already exist.

If remove, modify the attributes of the virtual container itself and not the associated objects.

If set, perform the action as this user.

proxy-user

String

Perform the action as this user.

See Global URL Parameters for available URL parameters.

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

The proxy-user parameter is ignored unless you set ENABLEPROXY=TRUE in the moab.cfg file. For example:

ADMINCFG[1]           USERS=root,ted ENABLEPROXY=TRUE

Destroying Virtual Containers

The HTTP GET method is used to retrieve <name> information.

Quick reference

DELETE http://localhost:8080/mws/rest/vcs/<id>?api-version=3[&proxy-user=<username>]

Restrictions

The proxy-user parameter is ignored unless you set ENABLEPROXY=TRUE in the moab.cfg file. For example:

ADMINCFG[1]           USERS=root,ted ENABLEPROXY=TRUE

Destroy Virtual Container

URLs and parameters

DELETE http://localhost:8080/mws/rest/vcs/<id>?api-version=3&[&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.

See Global URL Parameters for available URL parameters.

Sample response

JSON response for successful DELETE
------------------------------------

{}