Create volume

Overview

Creates a volume.

Classification

  • Create

API Operation Object

  • volumes

Synchronous / Asynchronous

  • asynchronous

Request

HTTP Request Method

  • POST

HTTP Request Path

{api_endpoint}/v2/{tenant_id}/volumes

HTTP Request Header

Format

Accept-Encoding: gzip, deflate, compress(optional)
Accept: application/json
X-Auth-Token: <token_id>
Content-Type: application/json

HTTP Request Body

Format

{
    "volume": {
        "availability_zone": "<availability_zone>",
        "description": "<description>",
        "name": "<display_name>",
        "imageRef": "<image_id>",
        "metadata": <metadata>,
        "size": <volume_size>,
        "snapshot_id": "<snapshot_id>",
        "volume_type": "<volume_type_name>"
    }
}

Request Parameter

Request Parameters
name style format description required/optional default value action for invalid parameter response code for invalid parameter
tenant_id URL UUID(3) The unique identifier of the tenant. required - Terminate 404
token_id Header String(token_id) Keystone admin token required - Terminate 401
description Body String(0-255characters) or null or number(0-255digits) The volume description optional null Terminate 400
display_name Body String(0-255characters) or null or number(0-255digits) The volume name optional null Terminate 400
volume_size Body int(more than 1, Less than the size that is allowed in the Quota) The volume size required - Terminate 400
snapshot_id Body UUID or null To create a volume from an existing snapshot, specify the ID of the existing volume snapshot *1 optional null Terminate 404
image_id Body UUID or null Glance image_id which becomes the source data of volume *1 optional null Terminate 400
volume_type_name Body String or null The volume type name optional Default volume type name *2 Terminate 400
metadata Body Associative array of JSON. ex:{ “key1”: “value1”, “key2”: “value2”} One or more metadata key and value pairs to associate with the volume. optional {} Terminate 400, 500
availability_zone Body availability_zone or null availability_zone name optional Availability zone of this node *3 Terminate 400
  • *1 Specifying simultaneously two or more of the copy source volume ID and image ID and snapshot ID is not allowed.
  • *2 Default volume type is the value of default_volume_type in conf file.
  • *3 Default vaule for availability zone is the value of default_availability_zone in conf file. If not set, the value of storage_availability_zone is used as the default for new volumes.

Response

HTTP Response Header

Format

HTTP/1.1 <response code> <message>       (ex. 202 Accepted)
  • <response_code>: see “HTTP Responses” section

  • <message>: message based on the response code

    • skip auto insert field such as “X-Compute-Request-Id” and “X-Openstack-Request-Id”, “Content-Length”, “Date”

Response Code

Response Codes
response code condition
202 normal end
400 There is no HTTP request body, or there is no volume element in the body
- You specify two or more of the copy source volume ID and snapshot ID and Glance Image ID.
- Glance image is specified, part of the image ID that are separated by / if the URI format can not be obtained.
- Image ID the Glance image is specified, were obtained not in the form of UUID
- Volume ID copy source volume ID is specified, were obtained not in the form of UUID
- Status of the snapshot to snapshot ID is specified, the specified is not available
- Status of the volume copy source volume ID is specified, the specified is not available
- The specified size is not an integer value of 1 or more
- Size specified is smaller than the read snapshot of the original
- Size specified is smaller than the read of the original volume
- Bad Request error is encountered in accessing the Glance
- Size of Glance the specified image size is larger than the volume
- The specified volume type does not match the specified copy source volume
- The specified volume type does not match the specified snapshot
- Availability Zone that has been specified does not exist
- specifies invalid parameter
401 unauthorized(including keystone down)
403 When the snapshot ID is specified, user who requested are not allowed to do get_snapshot operation.
- User who requested are not allowed to do create operation
404 Volume type that has been specified does not exist.
- When the snapshot ID is specified, there is no specified snapshot ID.
- Glance image that has been specified does not exist. Or, because the specified glance image is not public in addition to request_user’s not having authority of admin, user or project does not have ownership of the image.
- When the copy source volume ID is specified, there is no specified copy source volume image.
413 The specified size exceeds the limit value of Quota.
- The specified number of volume exceeded the limit value of Quota.
500 Access to the Glance image that has been specified is not allowed.
- Endpoint information of Glance is incorrect.
- Failed to communicate with the glance-api.
- The specified metadata is malformed JSON.

HTTP Response Body

Format

{
    "volume": {
        "attachments": [],
        "availability_zone": "<availability_zone>",
        "created_at": "<created_at>",
        "description": "<description>",
        "name": "<display_name>",
        "id": "<volume_id>",
        "image_id": "<image_id>",
        "metadata": <metadata>,
        "size": <volume_size>,
        "snapshot_id": "<snapshot_id>",
        "status": "<status>",
        "volume_type": "<volume_type>",
        "source_volid": "<copy_source_volume>",
        "bootable": "<bootable>",
        "encrypted":<encrypted>,
        "user_id":
            "links": [
            {
                "href": "<volume_URL>",
                "rel": "self"
            },
            {
                "href": "<bookmark_URL>",
                "rel": "bookmark"
            }
        ],
       "user_id": "<user_id>"
    }
}

Response Parameter

Response Parameters
item format description
availability_zone String The name of availability zone
created_at time/date Form: “yyyy-mm-ddThh:mm:ss.ssssss”
description String(0-255characters)or null The volume description
display_name String(0-256characters)or null The volume name
volume_id UUID The volume ID
metadata Associative array of JSON. ex:{ “key1”: “value1”, “key2”: “value2”} One or more metadata key and value pairs to associate with the volume.
volume_size int The volume size(GB)
snapshot_id UUID or null (volume) snapshot ID which becomes the source data of volume
status String status of snapshot
volume_type String or null The source volume type
image_id UUID or null Glance image_id which becomes the source data of volume
copy_source_volume UUID or null The volume_id which becomes the source data of volume
bootable false
Is volume bootable
(False is always returned regardless of a specified image’s bootability) false is returned even bootable volume
encrypted true or false State of encryption
volume_URL URL URL of the created volume
bookmark_URL URL URL of the bookmark
user_id String(1-255characters) The owner of the instance

Sample API Request and Response

Sample API Request

Request URI

https://example.com/v2/{tenant_id}/volumes

Request Header

Accept-Encoding: gzip, deflate, compress(optional)
Accept: application/json
X-Auth-Token: ajk3adjiown02
Content-Type: application/json

Request Body

{
    "volume": {
        "availability_zone": "<availability_zone>",
        "description": "<description>",
        "name": "<display_name>",
        "imageRef": "<image_id>",
        "metadata": <metadata>,
        "size": <volume_size>,
        "snapshot_id": "<snapshot_id>",
        "volume_type": "<volume_type_name>"
    }
}

Sample API Response

Response Header

HTTP/1.1 202 Accepted
  • <response_code>: see “HTTP Responses” section

  • <message>: message based on the response code

    • skip auto insert field such as “X-Compute-Request-Id” and “X-Openstack-Request-Id”, “Content-Length”, “Date”

Response Body

{
    "volume": {
        "attachments": [],
        "availability_zone": "<availability_zone>",
        "created_at": "<created_at>",
        "description": "<description>",
        "name": "<display_name>",
        "id": "<volume_id>",
        "image_id": "<image_id>",
        "metadata": <metadata>,
        "size": <volume_size>,
        "snapshot_id": "<snapshot_id>",
        "status": "<status>",
        "volume_type": "<volume_type>",
        "source_volid": "<copy_source_volume>",
        "bootable": "<bootable>",
        "encrypted":<encrypted>,
        "user_id":
            "links": [
            {
                "href": "<volume_URL>",
                "rel": "self"
            },
            {
                "href": "<bookmark_URL>",
                "rel": "bookmark"
            }
        ],
       "user_id": "<user_id>"
    }
}

Execution Example

HTTP Request

POST /v2/88b6f916fc8a4b81b055aa26993bd68e/volumes HTTP/1.1
User-Agent: curl/7.35.0
Host: 192.168.11.67:8776
Accept-Encoding: gzip, deflate, compress
Accept: application/json
X-Auth-Token: 5dadaaa0620c4c64a2ca0306d487706c
Content-Type: application/json
Content-Length: 212

{"volume": {"status": "creating", "project_id": null, "description": null, "availability_zone": null, "attach_status": "detached",  "imageRef": null ,"size": 1, "name": null, "metadata": {}, "volume_type": null}}

HTTP Response

HTTP/1.1 202 Accepted
X-Compute-Request-Id: req-e4a420b1-2841-438d-b194-8ee576ab0cc4
Content-Type: application/json
Content-Length: 668
X-Openstack-Request-Id: req-e4a420b1-2841-438d-b194-8ee576ab0cc4
Date: Tue, 27 May 2014 11:17:42 GMT

{"volume": {"status": "creating", "user_id": "360cdc8902e04d4482ab653082b5b5e4", "attachments": [], "links": [{"href": "http://192.168.11.67:8776/v2/88b6f916fc8a4b81b055aa26993bd68e/volumes/e03ee430-3ec1-48bd-ab89-79f604f037fd", "rel": "self"}, {"href": "http://192.168.11.67:8776/88b6f916fc8a4b81b055aa26993bd68e/volumes/e03ee430-3ec1-48bd-ab89-79f604f037fd", "rel": "bookmark"}], "availability_zone": "nova", "bootable": "false", "encrypted": false, "created_at": "2014-05-27T11:17:42.318311", "description": null, "volume_type": null, "name": null, "source_volid": null, "snapshot_id": null, "metadata": {}, "id": "e03ee430-3ec1-48bd-ab89-79f604f037fd", "size": 1}}

Error Execution Example

HTTP Request

POST /v2/331d0a14a8a34f8996ce2660e0029fef/volumes HTTP/1.1
User-Agent: curl/7.35.0
Host: 192.168.56.250:8776
X-Auth-Token: 150c438fd7234fd095c184ae3b35efad
Content-type: application/json
Accept: application/json
Content-Length: 255

{"volume": {"status": "creating", "project_id": "331d0a14a8a34f8996ce2660e0029fef", "description": null, "availability_zone": null, "attach_status": "detached",  "imageRef": null ,"size": 1, "name": "test-volume", "metadata": null, "volume_type": null, }}

HTTP Response

HTTP/1.1 400 Bad Request
Content-Length: 66
Content-Type: application/json; charset=UTF-8
X-Compute-Request-Id: req-ee0dab3c-613b-4221-9183-dc7a88b63f80
X-Openstack-Request-Id: req-ee0dab3c-613b-4221-9183-dc7a88b63f80
Date: Thu, 17 Sep 2015 08:04:37 GMT

{"badRequest": {"message": "Malformed request body", "code": 400}}