Create server¶
Overview¶
Creates a server.
Classification¶
- Create
API Operation Object¶
- servers
Synchronous / Asynchronous¶
- asynchronous
Request¶
HTTP Request Method¶
- POST
HTTP Request Path¶
{api_endpoint}/v2/{project_id}/servers
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¶
{
"server": {
"OS-DCF:diskConfig": "<disk_config>",
"flavorRef": "<flavor_id>",
"imageRef": "<image_id>",
"max_count": <min_count>,
"min_count": <max_count>,
"name": "<instance_name>",
"availability_zone": "<availability_zone>",
"config_drive": "<config_drive>",
"key_name": "<key_name>",
"user_data": "<user_data>",
"block_device_mapping": [
{
"volume_id": "<volume_id>",
"delete_on_termination": <delete_flag>,
"device_name": "<device_name>"
},
<<repeat>>
],
"block_device_mapping_v2": [
{
"no_device": "<no_device(bdm_v2)>",
"device_name": "<device_name(bdm_v2)>",
"source_type": "<source_type(bdm_v2)>",
"destination_type": "<destination_type(bdm_v2)>",
"guest_format": "<guest_format(bdm_v2)>",
"uuid": "<uuid(bdm_v2)>",
"boot_index": "<boot_index(bdm_v2)>",
"volume_size": <volume_size(bdm_v2)>,
"device_type": "<device_type(bdm_v2)>",
"disk_bus": "<disk_bus(bdm_v2)>",
"delete_on_termination": <delete_on_termination(bdm_v2)>
},
<<repeat>>
],
"metadata": {
"<metadata_key>": "<metadata_value>",
<<repeat>>
},
"networks": [
{
"uuid": "<network_id>",
"fixed_ip": "<fixed_ip>"
},
{
"port": "<port_id>"
}
<<repeat>>
],
}
}
Request Parameter¶
| name | style | format | description | required/optional | default value | action for invalid parameter | response code for invalid parameter |
|---|---|---|---|---|---|---|---|
| project_id | URL | UUID(3) | Project id | required | - | Terminate | 400, 404 |
| token_id | Header | authentication token string | keystone authentication token | required | - | Terminate | 401 |
| disk_config | Body | String (AUTO or MANUAL) | Auto: a single partition which is expanded to the size of the flavor selected | optional | MANUAL | Terminate | 400 |
| flavor_id | Body | String(1-255 characters) | flavor id | required | - | Terminate | 400 |
| image_id | Body | UUID | image ID | optional (if block_device_mapping_v2 attribute is not specified, it is required) | - | Terminate | 400 |
| min_count | Body | int (1-limit of quota) | requested minim count of instance | optional | 1 | Terminate | 400, 403 |
| max_count | Body | int (1-limit of quota) | requested maximum count of instance | optional | min_count | Terminate | 400 |
| instance_name | Body | String(1-255 characters) | instance name | required | - | Terminate | 400 |
| availability_zone | Body | String(1-255 characters) | availability zone | optional | default availability zone | Terminate | 400 |
| config_drive | Body | boolean/UUID(2) | Enables metadata injection in a server through a configuration drive | optional | - | Terminate | 400 |
| key_name | Body | String(1-255 characters) | key name | optional | - | Terminate | 400 |
| user_data | Body | String(Base64 encoded) | user data | optional | - | Terminate | 400 |
| volume_id | Body | UUID | volume id | optional (if block_device_mapping attribute is specified, it is required) | - | Terminate | 400 |
| delete_flag | Body | boolean/String('t','true', 'on', 'y', 'yes', '1','f', 'false', 'off', 'n', 'no', '0') | true: delete block device if instance is deleted false: not delete block device even if instance is deleted | optional | false | Terminate | 400 |
| device_name | Body | String (^/dev/x{0,1}[a-z]{0,1}d{0,1})([a-z]+)[0-9]*$ | device name on Guest OS | optional | /dev/vdb | Terminate | 400 |
| no_device(bdm_v2) | Body | boolean/String('t','true', 'on', 'y', 'yes', '1','f', 'false', 'off', 'n', 'no', '0') | disable the specified block_device_mapping_2 Note: unavailable | optional | - | - | - |
| device_name(bdm_v2) | Body | String (^/dev/x{0,1}[a-z]{0,1}d{0,1})([a-z]+)[0-9]*$ | device name on Guest OS | optional | /dev/vdb | Terminate | 400 |
| source_type(bdm_v2) | Body | 'blank', 'snapshot', 'volume', 'image' | Type of attach source.・Attach Volume = 'volume' ・Attach Snapshot = 'snapshot' ・Attach Image = 'image' ・Attach swap or ephemeral = 'blank' | optional (if block_device_mapping_2 attribute is specified , it is required) | - | Terminate | 400 |
| destination_type(bdm_v2) | Body | 'local', 'volume' | Type of attach source. ・Attach Volume = 'volume' ・Attach Snapshot = 'volume' ・Attach Image = 'local' or None ・Attach swap or ephemeral = 'local' or None Note: If the combination of source_type and destination_type is invalid, not mapped.", "optional (if block_device_mapping_2 attribute is specified, and if source_type(bdm_v2) is "volume" or "snapshot", it is required) | local | - | - | |
| guest_format(bdm_v2) | Body | String(1-255 characters) | Specifies the guest server disk file system format.・Attach swap = 'swap' ・Attach ephemeral = not 'swap' | optional | - | - | - |
| uuid(bdm_v2) | Body | UUID | Describes the volume source type for the volume. ・Attach Volume = Volume UUID ・Attach Snapshot = Snapshot UUID ・Attach Image = Image UUID ・Attach swap or ephemeral = None or Omission Note: not specify the uuid of attach already Volume | optional (if block_device_mapping_2 attribute is specified, and if source_type(bdm_v2) is "volume" or "snapshot" or "image", it is required) | - | Terminate | 400 |
| boot_index(bdm_v2) | Body | int (0-Number of mapping device) | Indicates a number designating the boot order of the device. | optional(if block_device_mapping_2 attribute is specified , it is required) | - | Terminate | 400 |
| volume_size(bdm_v2) | Body | int (0-Maximum value for the 'swap' or 'ephemeral' of flavor that is assigned to the VM) | Size(GB) of the volume(image, snapshot)or ephemeral. also size(MB) of the swap. | optional | 0 | ||
| device_type(bdm_v2) | Body | String('disk', 'cdrom', 'floppy', 'mmc') or None | device type on Guest OS | optional | disk | - | - |
| disk_bus(bdm_v2) | Body | String('ide', 'usb', 'virtio', 'scsi') or None | disk bus type | optional | hypervisor driver chooses a suitable default | - | - |
| delete_on_termination(bdm_v2) | Body | boolean/String('t','true', 'on', 'y', 'yes', '1','f', 'false', 'off', 'n', 'no', '0') | true: delete block device if instance is deleted false: not delete block device even if instance is deleted | optional | false | Terminate | 400 |
| metadata_key | Body | String(1-255 characters) | key for metadata Server Metadata | optional | - | Terminate | 400 |
| metadata_value | Body | String(1-255 characters) | value for metadata Server Metadata | optional | - | Terminate | 400 |
| network_id | Body | UUID | network id | optional (if a tenant has more than two networks, it is required) | default network | Terminate | 400 |
| fixed_ip | Body | String(IP address) | fixed ip | optional | - | Terminate | 400 |
| port_id | Body | UUID | port id | optional(if networks attribute is specified and network_id isn't specified, it is required) | - | Terminate | 400 |
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 "Content-Length", "Date"
Response Code¶
| response code | condition |
|---|---|
| 202 | normal end |
| 400 | not found server entity in body |
| - | not found name attribute in body |
| - | not found flavorRef attribute in body |
| - | specify invalid block device name |
| - | specify invalid instance_name (empty or more than 255 caharactors) |
| - | specify invalid flavor_id |
| - | specify invalid image_Ref |
| - | specify invalid port |
| - | specify invalid network uuid |
| - | specify invalid fixed_ip |
| - | specify invalid max_count |
| - | specify invalid min_count |
| - | min_count > max_count |
| - | can't attach volume if min_count >1 or max_count>1 |
| - | can't specify port if min_count >1 or max_count >1 |
| - | specify invalid availability_zone |
| - | fixed ip is in-use |
| - | max_count cannot be greater than 1 if an fixed_ip is specified |
| - | specify invalid metadata |
| - | userdata is too large |
| - | flavor's memory is too small for requested image(min_ram) |
| - | flavor's disk is too small for requested image(min_disk) |
| - | image is not active |
| - | not found a specified network id |
| - | not found a specified image id |
| - | not found a specified port id |
| - | not found a specified flavor id |
| - | source_type is 'blank' and volume_id is not None |
| - | source_type is not 'blank' and volume_id is None |
| - | boot_index is not be converted to an integer |
| - | block_device_mapping and block_device_mapping_v2 is both exist in body |
| - | if source type is volume,snapshot,image there is not found uuid entity in body |
| - | if source type is volume, uuid isn't a volume id |
| - | if source type is snapshot, uuid isn't a snapshot id |
| - | if source type is image, uuid isn't a image id |
| - | specified swap size is over the limit swap size of flavor for VM |
| - | specified ephemeral size is over the limit swap size of flavor for VM |
| - | multiple swap devices are specified in block_device_mapping_v2 |
| - | order of bootindex incorrect on multiple devices of block_device_mapping_v2 |
| - | If attach a volume in the BDM or BDMv2, Volume must be the same availability zone with the VM. |
| 401 | unauthorized |
| 403 | TooManyInstances |
| - | Maximum number of ports exceeded |
| - | Maximum number of metadata items exceeded |
| - | min_count > instance limit of quota. |
| 404 | not found a specified project |
| 409 | port is in-use |
| 500 | glance-api process is stopped |
| - | glance-registry process is stopped |
| - | cinder-api process is stopped |
| - | neutron server process is stopped |
HTTP Response Body¶
Format¶
{
"server": {
"OS-DCF:diskConfig": "<disk_config>",
"adminPass": "<admin_pass>",
"id": "<instance_id>",
"links": [
{
"href": "<instance_url>",
"rel": "self"
},
{
"href": "<bookmark_url>",
"rel": "bookmark"
}
],
"security_groups": [
{
"name": "<security_group_name>"
}
]
}
}
Response Parameter¶
| item | format | description |
|---|---|---|
| disk_config | String (AUTO or MANUAL) | Auto: a single partition which is expanded to the size of the flavor selected |
| admin_pass | String | adminstrator password |
| instance_id | UUID | instance id |
| instance_url | URL | instance url |
| bookmark_url | URL | bookmark url |
| security_group_name | String(1-255 characters) | securiy group name of instance |
Sample API Request and Response¶
Sample API Request¶
Request URI¶
https://example.com/v2/{project_id}/servers
Request Header¶
Accept-Encoding: gzip, deflate, compress (optional)
Accept: application/json
X-Auth-Token: ajk3adjiown02
Content-Type: application/json
Request Body¶
{
"server": {
"OS-DCF:diskConfig": "<disk_config>",
"flavorRef": "<flavor_id>",
"imageRef": "<image_id>",
"max_count": <min_count>,
"min_count": <max_count>,
"name": "<instance_name>",
"availability_zone": "<availability_zone>",
"config_drive": "<config_drive>",
"key_name": "<key_name>",
"user_data": "<user_data>",
"block_device_mapping": [
{
"volume_id": "<volume_id>",
"delete_on_termination": <delete_flag>,
"device_name": "<device_name>"
},
<<repeat>>
],
"block_device_mapping_v2": [
{
"no_device": "<no_device(bdm_v2)>",
"device_name": "<device_name(bdm_v2)>",
"source_type": "<source_type(bdm_v2)>",
"destination_type": "<destination_type(bdm_v2)>",
"guest_format": "<guest_format(bdm_v2)>",
"uuid": "<uuid(bdm_v2)>",
"boot_index": "<boot_index(bdm_v2)>",
"volume_size": <volume_size(bdm_v2)>,
"device_type": "<device_type(bdm_v2)>",
"disk_bus": "<disk_bus(bdm_v2)>",
"delete_on_termination": <delete_on_termination(bdm_v2)>
},
<<repeat>>
],
"metadata": {
"<metadata_key>": "<metadata_value>",
<<repeat>>
},
"networks": [
{
"uuid": "<network_id>",
"fixed_ip": "<fixed_ip>"
},
{
"port": "<port_id>"
}
<<repeat>>
],
}
}
Sample API Response¶
Response Header¶
HTTP/1.1 202 OK
<response_code>: see "HTTP Responses" section
<message>: message based on the response code
- skip auto insert field such as "X-Compute-Request-Id" and "Content-Length", "Date"
Response Body¶
{
"server": {
"OS-DCF:diskConfig": "<disk_config>",
"adminPass": "<admin_pass>",
"id": "<instance_id>",
"links": [
{
"href": "<instance_url>",
"rel": "self"
},
{
"href": "<bookmark_url>",
"rel": "bookmark"
}
],
"security_groups": [
{
"name": "<security_group_name>"
}
]
}
}
Execution Example 1. create server¶
HTTP Request¶
POST /v2/fd57c99ad0d7491fa496a3ac9a44eb7c/servers HTTP/1.1
User-Agent: curl/7.35.0
Host: 192.168.150.51:8774
Accept-Encoding: gzip, deflate, compress
Accept: application/json
X-Auth-Token: 734732012f404526926dc7e1d9e846ff
Content-Type: application/json
Content-Length: 130
{"server": {"flavorRef": "1CPU-4GB","name": "Testvm1","imageRef": "a3bf7a3d-f842-4bb7-b005-cbe8e42fc843"}}
HTTP Response¶
HTTP/1.1 202 Accepted
Location: http://192.168.150.51:8774/v2/fd57c99ad0d7491fa496a3ac9a44eb7c/servers/74f4aba6-64df-4004-b886-a4fb3461cf73
Content-Type: application/json
Content-Length: 444
X-Compute-Request-Id: req-24aaea55-849f-482b-9870-3464a80153db
Date: Sun, 21 Sep 2014 05:37:45 GMT
{"server": {"security_groups": [{"name": "default"}], "OS-DCF:diskConfig": "MANUAL", "id": "74f4aba6-64df-4004-b886-a4fb3461cf73", "links": [{"href": "http://192.168.150.51:8774/v2/fd57c99ad0d7491fa496a3ac9a44eb7c/servers/74f4aba6-64df-4004-b886-a4fb3461cf73", "rel": "self"}, {"href": "http://192.168.150.51:8774/fd57c99ad0d7491fa496a3ac9a44eb7c/servers/74f4aba6-64df-4004-b886-a4fb3461cf73", "rel": "bookmark"}], "adminPass": "vffeEYsLvR5H"}}
Execution Example 2. create server with VMHA disabled¶
HTTP Request¶
POST /v2/fd57c99ad0d7491fa496a3ac9a44eb7c/servers HTTP/1.1
User-Agent: curl/7.35.0
Host: 192.168.150.51:8774
Accept-Encoding: gzip, deflate, compress
Accept: application/json
X-Auth-Token: 734732012f404526926dc7e1d9e846ff
Content-Type: application/json
Content-Length: 130
{"server": {"flavorRef": "1CPU-4GB","name": "Testvm1","imageRef": "a3bf7a3d-f842-4bb7-b005-cbe8e42fc843", "metadata": {"HA_Enabled": "false" }}}
HTTP Response¶
HTTP/1.1 202 Accepted
Location: http://192.168.150.51:8774/v2/fd57c99ad0d7491fa496a3ac9a44eb7c/servers/18a560f3-5572-4b1e-88d0-0db23939eed0
Content-Type: application/json
Content-Length: 444
X-Compute-Request-Id: req-24aaea55-849f-482b-9870-3464a80153db
Date: Sun, 21 Sep 2014 05:37:45 GMT
{"server": {"security_groups": [{"name": "default"}], "OS-DCF:diskConfig": "MANUAL", "id": "18a560f3-5572-4b1e-88d0-0db23939eed0", "links": [{"href": "http://192.168.150.51:8774/v2/fd57c99ad0d7491fa496a3ac9a44eb7c/servers/18a560f3-5572-4b1e-88d0-0db23939eed0", "rel": "self"}, {"href": "http://192.168.150.51:8774/fd57c99ad0d7491fa496a3ac9a44eb7c/servers/18a560f3-5572-4b1e-88d0-0db23939eed0", "rel": "bookmark"}], "adminPass": "B8L9FUyxxfsv"}}
Error Execution Example¶
HTTP Request¶
POST /v2/b17a6492bfa54441910e15f07c983384/servers HTTP/1.1
User-Agent: curl/7.35.0
Host: 192.168.56.250:8774
X-Auth-Token: 5565d8f69d9a43b698aa30f30ebc681b
Content-type: application/json
Accept: application/json
Content-Length: 130
HTTP Response¶
HTTP/1.1 400 Bad Request
Content-Length: 72
Content-Type: application/json; charset=UTF-8
X-Compute-Request-Id: req-a66626f9-0287-4eb1-8e14-46467802f129
Date: Tue, 06 Oct 2015 07:41:51 GMT
{"badRequest": {"message": "Can not find requested image", "code": 400}}