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:
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
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} |
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": "centos5-stateful"
}]
}
Sorting and querying
See the sorting and querying sections of Global URL Parameters.
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/centos5-compute-stateful?api-version=3
------------------------------------
{
"active":true,
"extensions":{
"xcat":{
"os":"centos",
"architecture":"x86_64",
"profile":"compute"
}
},
"features":[],
"hypervisor":false,
"hypervisorType": null,
"id":"4fa197e68ca30fc605dd1cf0",
"name":"centos5-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":"centos5-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.
The HTTP POST method is used to submit Images.
Quick reference
POST http://localhost:8080/mws/rest/images?api-version=3
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": "centos5-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": "centos5-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": "centos5-compute-stateful",
"osType": "linux",
"type": "linkedclone",
"supportsVirtualMachine":true,
"templateName":"centos5-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": "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",
"hypervisorType": "ESX",
"supportsPhysicalMachine":true,
"extensions": {
"xcat": {
"os": "esxi5",
"architecture": "x86_64",
"profile": "base",
"hvType": "esx",
"hvGroupName": "esx5hv",
"vmGroupName": "esx5vm"
}
}
}
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
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/centos5-stateful?api-version=3
------------------------------------
{
"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.
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
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
------------------------------------
{}
Related Topics