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

Request Parameters
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)
Switch destination of the license type
(Valid value, See: List image license switch types API)
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 Codes
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
-
specify read_only properties in request body (each read_only properties also occur the 400 errors when specify the invalid values)
read_only properties : checksum, created_at, direct_url, file, schema, self, size, status, updated_at, virtual_size
-
specify reserved properties in request body (each reserved properties also occur the 400 errors when specify the invalid values)
reserved properties : deleted, deleted_at, is_public, locations, owner
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

Response Parameters
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.