Moab Web Services > Resources > Virtual Machines

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

The Virtual Machine API is new with API version 2. The supported methods table below requires each resource to be accessed with a URL parameter of api-version=3 in order to behave as documented.

In order to access documentation for previous API versions, see Requesting Specific API Versions.

The Fields: Virtual Machines reference section contains the type and description of all fields in the Virtual Machine object. It also contains details regarding which fields are valid during PUT actions.

Supported methods

Resource	GET	PUT	POST	DELETE
/rest/vms	Get All Virtual Machines	--	--	--
/rest/vms/<name>	Get Single Virtual Machine	Modify Virtual Machine	--	Destroy Virtual Machine

This topic contains these sections:

Getting Virtual Machines
- Get All Virtual Machines
- Get Single Virtual Machine
Modifying Virtual Machines
- Modify Virtual Machine
- Migrate Virtual Machine
Destroying Virtual Machines
- Destroy Virtual Machine

Getting Virtual Machines

The HTTP GET method is used to retrieve Virtual Machine information.

Quick reference

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

Get All Virtual Machines

URLs and parameters

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

Parameter	Required	Type	Valid values	Description	Example
query	No	JSON	--	Queries for specific results. It is possible to query by one or more fields based on MongoDB query syntax.	query={"migrationDisabled":true}
sort	No	JSON	--	Sort the results. Use 1 for ascending and -1 for descending.	sort={"name":-1}

See Global URL Parameters for available URL parameters.

Sample response

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

{
  "totalCount": 3,
  "resultCount": 3,
  "results":   [
    {"name": "vm1"},
    {"name": "vm2"},
    {"name": "vm3"}
  ]
}

Get Single Virtual Machine

URLs and parameters

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

Parameter	Required	Type	Valid values	Description
name	Yes	String	--	The name of the object.

See Global URL Parameters for available URL parameters.

The attributes field is only applicable in API version 2 and later, and the MOAB_TENANT field only applies if the VM is attached to a tenant.

Sample response

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

{
  "name": "vm3",
  "attributes":     {
    "MOAB_TENANT": [      {
      "value": "1234567890aabbccddeeff00",
      "displayValue": "ResearchGroup"
  }],
  "description": null,
  "host": {"name": "hv2"},
  "hostnames": [],
  "ipAddress": "10.0.0.5",
  "migrationDisabled": false,
  "lastUpdatedDate": "2012-10-11 17:46:32 UTC",
  "startDate": "2012-09-25 18:12:23 UTC",
  "trackingJob": null,
  "metrics": {"watts": 200},
  "variables": {},
  "resourceManagers": [  {
    "name": "msm",
    "isMaster": true,
    "stateReported": "Active"
  }],
  "operatingSystem":   {
    "image": "stateless1",
    "imageExpected": null,
    "imageLastUpdatedDate": null,
    "imagesAvailable": []
  },
  "states":   {
    "powerState": "On",
    "powerStateExpected": null,
    "powerStateLastUpdatedDate": null,
    "state": "Idle",
    "stateLastUpdatedDate": "2012-10-11 17:15:01 UTC",
    "subState": null,
    "subStateLast": null,
    "subStateLastUpdatedDate": null
  },
  "resources":   {
    "processors":     {
      "configured": 1,
      "dedicated": 0,
      "available": 1
    },
    "memory":     {
      "configured": 512,
      "dedicated": 0,
      "available": 512
    },
    "disk":     {
      "configured": 1024,
      "dedicated": 0,
      "available": 1024
    },
    "swap":     {
      "configured": 0,
      "dedicated": 0,
      "available": 0
    }
  },
  "triggers": [],
  "virtualContainers": []
}

Modifying Virtual Machines

The HTTP PUT method is used to modify Virtual Machines.

Quick reference

PUT http://localhost:8080/mws/rest/vms/<name>?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

Modify Virtual Machine

URLs and parameters

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

Parameter	Required	Type	Valid values	Description
name	Yes	String	--	The name of the object.
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 modifying a Virtual Machine, along with some sample values.

JSON request body for VM modify
------------------------------------

{
  "metrics": {"pwatts": 211},
  "migrationDisabled": true,
  "operatingSystem": {"image": "esx4.1"},
  "states":   {
    "powerState": "On",
    "state": "Running"
  },
  "triggers": [{"name": "trigger_id"}],
  "variables":   {
    "key": "value",
    "arbitrary text key": "more 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 updated VM variables"]}

Migrate Virtual Machine

URLs and parameters

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

Parameter	Required	Type	Valid values	Description
name	Yes	String	--	The name of the object.
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 how to migrate a Virtual Machine to a host (hypervisor) with name "hv2".

JSON request body for VM Migrate to a specific host
------------------------------------

{"host": {"name": "hv2"}}

The request body below shows how to migrate a Virtual Machine to any available host by using the destination name of ANY, which for this operation is a reserved word.

JSON request body for VM Migrate to any available host
------------------------------------

{"host": {"name": "ANY"}}

Sample response

The HTTP response code for this operation is 202 Accepted. See the Responses and Return Codes section for more information.

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

{"jobId": "vm-migrate1"}

Restrictions

If a migration is requested by setting the host as shown in the above examples, any other properties in the same request body will be ignored.

Destroying Virtual Machines

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

Quick reference

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

Destroy Virtual Machine

URLs and parameters

Code example (replace with your own content)

Parameter	Required	Type	Valid values	Description
name	Yes	String	--	The name 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
------------------------------------

{"jobId": "vmdestroy-26"}

The jobId in the response identifies the job that will destroy the virtual machine.