Create image¶
Overview¶
Creates a virtual machine (VM) image.
Classification¶
- Create
API Operation Object¶
- images
Synchronous / Asynchronous¶
- synchronous
Request¶
HTTP Request Method¶
- POST
HTTP Request Path¶
{api_endpoint}/v2/images
HTTP Request Header¶
Format¶
X-Auth-Token: <token_id>
Content-Type: application/json
- User-Agent, Host, Accept, Content-Length fields are automatically added
HTTP Request Body¶
Format¶
{
"id":"<image_id>",
"name": "<image_name>",
"visibility": "<visibility>",
"tags": [
"<tag>",
<<repeat>>
],
"container_format": "<container_format>",
"disk_format": "<disk_format>",
"min_disk": <minimum_disk_size>,
"min_ram": <minimum_ram_size>,
"protected": <protected_flag>,
"license_switch": "<license_switch_type>",
"<extra_key>": "<extra_value>"
}
- * "<extra_key>": "<extra_value>":the user can add the any number of original properties to the specified image
Request Parameter¶
name | style | format | description | required/optional | default value | action for invalid parameter | response code for invalid parameter |
---|---|---|---|---|---|---|---|
token_id | Header | authentication token string | keystone authentication token | required | - | Terminate | 401 |
image_id | Body | UUID | An identifier for the image (user can specify the id of the creating image, but currently, this parameter does not work normally because of bugs) | optional | unique UUID | Terminate | 400 |
image_name | Body | String (0-255 characters) | Descriptive name for the image | optional | - | Terminate | 400 |
visibility | Body | String (public, private) | Scope of image accessibility | optional | private | Terminate | 400 |
tag | Body | String (0-255 characters) | String related to the image | optional | - | Terminate | 400 |
container_format | Body | String (bare) | Format of the container | optional | - | Terminate | 400 |
disk_format | Body | String (raw, qcow2, iso) | Format of the disk | optional | - | Terminate | 400 |
minimum_disk_size | Body | integer | Amount of disk space (in GB) required to boot image | optional | 0 | Terminate | 400 |
minimum_ram_size | Body | integer | Amount of ram (in MB) required to boot image | optional | 0 | Terminate | 400 |
protected_flag | Body | boolean | If true, image will not be deletable | optional | false | Terminate | 400 |
license_switch_type | Body | String (0-255 characters) |
|
optional | - | Terminate | 400 |
extra_key | Body | String (0-255 characters) | The key of the extra properties | optional | - | Terminate | 400 |
extra_value | Body | text (2^16 - 1 bytes) | The value of the extra properties | optional | - | Terminate | 400 |
Response¶
HTTP Response Header¶
Format¶
HTTP/1.1 <response code> <message> (ex. 201 Created)
Location : <location>
<response_code>: see "HTTP Responses" section
<message>: message based on the response code
- skip auto inserted field such as "X-Openstack-Request-Id", "Content-type", "Content-Length", "Date"
Response Code¶
response code | condition |
---|---|
201 | normal end |
400 | Content-Type does not specify application/json in Header |
- | call with malformed JSON |
- | empty body |
- | specify not uuid in the id |
- | specify 256 or more characters in the image_name |
- | specify invalid value in the visibility (valid value : public, private) |
- | specify 256 or more characters in the tag |
- | specify invalid value in the container_format (valid value : bare) |
- | specify invalid value in the disk_format (valid value : raw, qcow2, iso) |
- | specify not integer value or not positive value in the minimum_disk_size |
- | specify not integer value or not positive value in the minimum_ram_size |
- | specify not boolean value in the protected_flag |
- | specify not text value in the extra_property |
- | specify invalid value in the license_switch_type |
- | when disk_format has been 'iso', can not specified license_switch |
401 | unauthorized |
403 | requested for creating a public image by non-admin user |
- |
|
- |
|
413 | The number of image properties exceeds the limit |
- | The number of image tags exceeds the limit |
500 | specify the valid image_id in request body |
- | specify 2147483648 or more value in the minimum_disk_size |
- | specify 2147483648 or more value in the minimum_ram_size |
- | system error |
HTTP Response Body¶
Format¶
{
"status": "<image_status>",
"name": "<image_name>",
"tags": [
"<tag>",
<<repeat>>
],
"container_format": "<container_format>",
"created_at": "<created_time>",
"disk_format": "<disk_format>",
"locations": [],
"<extra_key>": "<extra_value>",
"updated_at": "<updated_time>",
"visibility": "<visibility>",
"self": "<self>",
"min_disk": <minimum_disk_size>,
"protected": <protected_flag>,
"id": "<image_id>",
"file": "<file>",
"owner": "<owner>",
"min_ram": <minimum_ram_size>,
"schema": "<image_schema>",
"license_switch": "<license_switch_type>",
".is_license": "<is_license>",
".virtual_server.os.pod": "<virtual_server_os_pod>",
".licensed_image_ref": "<image_id>"
}
- * There are multiple set of <extra_key> and <extra_value> which user added
Response Parameter¶
item | format | description |
---|---|---|
location | URL String | URL to access the image file kept in external store |
image_status | String (queued, saving, active, killed, deleted, pending_delete) | Status of the image |
image_name | String (0-255 characters) | Descriptive name for the image |
tag | String (0-255 characters) | String related to the image |
container_format | String (bare) | Format of the container |
created_time | time/date | Date and time of image registration |
disk_format | String (raw, qcow2, iso) | Format of the disk |
extra_key | String (1-255 characters) | The key of the extra properties |
extra_value | text (2^16 - 1 bytes) | The value of the extra properties |
updated_time | time/date | Date and time of the last image modification |
visibility | String (public, private) | Scope of image accessibility |
self | URL String | URL for the virtual machine image |
minimum_disk_size | integer | Amount of disk space (in GB) required to boot image |
protected_flag | boolean | If true, image will not be deletable |
image_id | UUID | An identifier for the image |
file | URL String | URL for the virtual machine image file |
owner | UUID(3) | Owner of the image |
minimum_ram_size | integer | Amount of ram (in MB) required to boot image |
image_schema | URL String | URL for schema of the virtual machine image |
license_switch_type | String (0-255 characters) | Switch destination of the license type |
is_license | String (True, False) | Whether licensed or not |
virtual_server_os_pod | String (0-255 characters) | VM boot destination host aggregate of each type of OS |
image_id | UUID | An identifier for the image |
Sample API Request and Response¶
Sample API Request¶
Request URI¶
https://example.com/v2/images
Request Header¶
X-Auth-Token: ajk3adjiown02
Content-Type: application/json
- User-Agent, Host, Accept, Content-Length fields are automatically added
Request Body¶
{
"id":"<image_id>",
"name": "<image_name>",
"visibility": "<visibility>",
"tags": [
"<tag>",
<<repeat>>
],
"container_format": "<container_format>",
"disk_format": "<disk_format>",
"min_disk": <minimum_disk_size>,
"min_ram": <minimum_ram_size>,
"protected": <protected_flag>,
"<extra_key>": "<extra_value>"
}
- * "<extra_key>": "<extra_value>":the user can add the any number of original properties to the specified image
Sample API Response¶
Response Header¶
HTTP/1.1 201 Created
Location : <location>
<response_code>: see "HTTP Responses" section
<message>: message based on the response code
- skip auto inserted field such as "X-Openstack-Request-Id", "Content-type", "Content-Length", "Date"
Response Body¶
{
"status": "<image_status>",
"name": "<image_name>",
"tags": [
"<tag>",
<<repeat>>
],
"container_format": "<container_format>",
"created_at": "<created_time>",
"disk_format": "<disk_format>",
"locations": [],
"<extra_key>": "<extra_value>",
"updated_at": "<updated_time>",
"visibility": "<visibility>",
"self": "<self>",
"min_disk": <minimum_disk_size>,
"protected": <protected_flag>,
"id": "<image_id>",
"file": "<file>",
"owner": "<owner>",
"min_ram": <minimum_ram_size>,
"schema": "<image_schema>"
}
- * There are multiple set of <extra_key> and <extra_value> which user added
Execution Example¶
HTTP Request¶
POST /v2/images HTTP/1.1
Host: 192.168.11.141:9292
Accept-Encoding: identity
Content-Length: 212
Content-Type: application/json
Accept: */*
X-Auth-Token: 8d1d540bc4cc424783677266ee423802
{"name": "private_admin_admin","visibility": "private","tags": ["tag1","tag2","tag3"],"container_format": "bare","disk_format": "qcow2","min_disk":0,"min_ram":0,"protected":false,"extra1":"extra1","extra2":"extra2","license_switch":"WindowsServer_2012R2_Standard_64_ComLicense"}
HTTP Response¶
HTTP/1.1 201 Created
Content-Length: 586
Content-Type: application/json; charset=UTF-8
Location: http://192.168.11.141:9292/v2/images/b0b25bbd-d4ff-40f5-b966-87870be1b648
X-Openstack-Request-Id: req-fc11c832-4db2-480b-b438-6c190a0efeb3
Date: Wed, 24 Sep 2014 11:16:12 GMT
{"status": "queued", "created_at": "2014-09-24T11:16:12Z", "name": "private_admin_admin", "tags": ["tag1", "tag2", "tag3"], "updated_at": "2014-09-24T11:16:12Z", "container_format": "bare", "min_ram": 0, "disk_format": "qcow2", "locations": [], "visibility": "private", "self": "/v2/images/b0b25bbd-d4ff-40f5-b966-87870be1b648", "extra1": "extra1", "extra2": "extra2", "protected": false, "file": "/v2/images/b0b25bbd-d4ff-40f5-b966-87870be1b648/file", "owner": "014908bf180c4004a6c289d2d95b2285", "min_disk": 0, "id": "b0b25bbd-d4ff-40f5-b966-87870be1b648", "schema": "/v2/schemas/image", "license_switch": "WindowsServer_2012R2_Standard_64_ComLicense", ".is_license": "True", ".virtual_server.os.pod": "windows", ".licensed_image_ref": "b0b25bbd-d4ff-40f5-b966-87870be1b648"}
Error Message Example¶
HTTP Request¶
POST /v2/images HTTP/1.1
User-Agent: curl/7.35.0
Host: 192.168.56.250:9292
X-Auth-Token: bfbda3fe12e546ee92f63c27e9cf138c
Content-type: application/json
Accept: application/json
Content-Length: 216
{"name": "private_admin_admin","visibility": "private","tags": ["tag1","tag2","tag3"],"container_format": "bare","disk_format": "qcow2","min_disk":0,"min_ram":0,"protected":false,"extra1":"extra1","extra2":"extra2","license_switch":"WindowsServer_2012R2_Standard_64_ComLicense"}
HTTP Response¶
HTTP/1.1 400 Bad Request
Content-Length: 53
Content-Type: text/plain; charset=UTF-8
X-Openstack-Request-Id: req-49843bc5-4ed5-4646-87ed-c7877438050c
Date: Thu, 17 Sep 2015 11:29:56 GMT
400 Bad Request
Malformed JSON in request body.