5.233 Images

This section describes behavior of the Image object 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 MWS.

The Fields: Images reference 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 Single Image	--
/rest/images/<id>	Get Single Image	Modify Single Image	--	Delete Single Image
/rest/images/<name>	Get Single Image	Modify Single Image	--	Delete Single Image

This topic contains these sections:

Getting Images
- Get All Images
- Get Single Image
Creating Images
- Create Single Image
Modifying Images
- Modify Single Image
Deleting Images
- Delete Single Image

5.233.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:8080/mws/rest/images?api-version=3[&query={"field":"value"}&sort={"field":<1|-1>}]
GET http://localhost:8080/mws/rest/images/<id>?api-version=3
GET http://localhost:8080/mws/rest/images/<name>?api-version=3

5.233.1.A Get All Images

URLs and parameters

GET http://localhost:8080/mws/rest/images?api-version=3[&query={"field":"value"}&sort={"field":<1|-1>}]

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

Parameter

Required

Type

Description

Example

query

JSON

Queries for specific results.

It is possible to query images by one or more fields based on MongoDB query syntax.

query={"type":"stateful","osType":"linux"}

sort

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/images?api-version=3&fields=id,name
------------------------------------

{
  "totalCount": 1,
  "resultCount": 1,
  "results": [  {
    "id": "4fa197e68ca30fc605dd1cf0",
    "name": "centos6-stateful"
  }]
}

Sorting and querying

See the sorting and querying sections of Global URL Parameters.

5.233.1.B Get Single Image

URLs and parameters

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

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.

See Global URL Parameters for available URL parameters.

Sample response

Virtual machine image example:

GET http://localhost:8080/mws/rest/images/centos6-compute-stateful?api-version=3
------------------------------------

{
  "active":true,
  "extensions":{
    "xcat":{
      "os":"centos",
      "architecture":"x86_64",
      "profile":"compute"
    }
  },
  "features":[],
  "hypervisor":false,
  "hypervisorType": null,
  "id":"4fa197e68ca30fc605dd1cf0",
  "name":"centos6-compute-stateful",
  "osType":"linux",
  "supportsPhysicalMachine":false,
  "supportsVirtualMachine":true,
  "templateName":null,
  "type":"stateful",
  "version":0,
  "virtualizedImages":[]
}

Hypervisor image example:

GET http://localhost:8080/mws/rest/images/esxi-4.1-stateful?api-version=3
------------------------------------

{
  "active":true,
  "extensions":{
    "xcat":{
      "hvGroupName":"hvGroup",
      "vmGroupName":"vmGroup",
      "os":"esxi-4.1",
      "architecture":"x86_64",
      "profile":"hv"
    }
  },
  "features":[],
  "hypervisor":true,
  "hypervisorType":"ESX",
  "id":"4fa197e68ca30fc605dd1cf0",
  "name":"centos6-compute-stateful",
  "osType":"linux",
  "supportsPhysicalMachine":true,
  "supportsVirtualMachine":false,
  "templateName":null,
  "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. For more information, see Modify Single Image.

5.233.2 Creating Images

The HTTP POST method is used to submit Images.

Quick reference

POST http://localhost:8080/mws/rest/images?api-version=3

5.233.2.A Create Single Image

URLs and parameters

POST http://localhost:8080/mws/rest/images?api-version=3

See Global URL Parameters for available URL parameters.

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 Fields: Images.

The following is an example of the most basic image that can be created:

POST http://localhost:8080/mws/rest/images?api-version=3
------------------------------------

{
  "name": "centos6-stateful",
  "osType": "linux",
  "hypervisor": false,
  "supportsVirtualMachine":true
}

Note that this example does not provide any information for a provisioning manager (such as xCAT) to actually provision the machine. In order to provide this, you must add an entry to the extensions field that contains provisioning manager-specific information. Each key in the extensions field corresponds to the provisioning manager, and certain properties are required based on this key. For example, the xCAT extension key must be named xcat and must contain certain fields. These extension keys are documented in Fields: Images. 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",
  "hypervisorType":"ESX",
  "virtualizedImages":   [
    {"id": "4fa197e68ca30fc605dd1cf0"},
    {"name": "centos6-stateful"}
  ]
}

The following example shows how to create an image that utilizes a cloned template for a virtual machine. (Note that the type must be set to linkedclone in order to set the templateName field.)

VM Utilizing a Cloned Template
------------------------------------

{
  "active": true,
  "hypervisor": false,
  "name": "centos6-compute-stateful",
  "osType": "linux",
  "type": "linkedclone",
  "supportsVirtualMachine":true,
  "templateName":"centos6-compute"
}

The following are samples of a virtual machine and a hypervisor image that can be provisioned with xCAT:

xCAT Virtual Machine Image
------------------------------------

{
  "active": true,
  "features": [],
  "hypervisor": false,
  "name": "centos6-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": "centos6-compute-stateless"}
  ],
  "type": "stateless",
  "hypervisorType": "ESX",
  "supportsPhysicalMachine":true,
  "extensions": { 
    "xcat": { 
      "os": "esxi5",
      "architecture": "x86_64",
      "profile": "base",
      "hvType": "esx",
      "hvGroupName": "esx5hv",
      "vmGroupName": "esx5vm"
    }
  }
}

5.233.3 Modifying Images

The HTTP PUT method is used to modify Images.

Quick reference

PUT http://localhost:8080/mws/rest/images/<id>?api-version=3
PUT http://localhost:8080/mws/rest/images/<name>?api-version=3

5.233.3.A Modify Single Image

URLs and parameters

PUT http://localhost:8080/mws/rest/images/<id>?api-version=3
PUT http://localhost:8080/mws/rest/images/<name>?api-version=3

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.

See Global URL Parameters for available URL parameters.

Example request

PUT http://locahost/mws/rest/images/centos6-stateful?api-version=3
------------------------------------

{
  "name": "centos6-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.

5.233.4 Deleting Images

The HTTP DELETE method is used to delete Images.

Quick reference

DELETE http://localhost:8080/mws/rest/images/<id>?api-version=3
DELETE http://localhost:8080/mws/rest/images/<name>?api-version=3

5.233.4.A Delete Single Image

URLs and parameters

DELETE http://localhost:8080/mws/rest/images/<id>?api-version=3
DELETE http://localhost:8080/mws/rest/images/<name>?api-version=3

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.

See Global URL Parameters for available URL parameters.

Sample response

JSON Response
------------------------------------

{}