13.2. Creating virtual machines

POST /servers

Create a virtual machine.

The progress of this operation depends on the location of the requested image, network I/O, host load, selected flavor, and other factors.

To check the progress of the request, make a GET /servers/{id} request. This call returns a progress attribute, which is a percentage value from 0 to 100.

When you create a server, the response shows only the server ID, its links, and the admin password. You can get additional attributes through subsequent GET requests on the server.

Include the block_device_mapping_v2 parameter in the create request body to boot a server from a volume.

Include the key_name parameter in the create request body to add a keypair to the server when you create it. Creating keypairs is described in Creating and importing SSH keys.

Note

Starting with the microversion 2.37, the networks field is required.

Preconditions:

  • The user must have sufficient server quota to create the number of servers requested.
  • The connection to the image service must be valid.

Asynchronous postconditions:

  • With correct permissions, you can see the server status as ACTIVE through API calls.
  • With correct access, you can see the created server in the compute node that OpenStack Compute manages.

Troubleshooting:

  • If the server status remains BUILDING or shows another error status, the request failed. Ensure you meet the preconditions then investigate the compute node.
  • The server is not created in the compute node that OpenStack Compute manages.
  • The compute node needs enough free resource to match the resource of the server creation request.
  • Ensure that the scheduler selection filter can fulfill the request with the available compute nodes that match the selection criteria of the filter.

Source: https://docs.openstack.org/api-ref/compute/?expanded=#create-server

13.2.1. Request

Name In Type Description
server body object A server object.
flavorRef body string The flavor reference, as an ID (including a UUID) or full URL, for the flavor for your server instance.
name body string The server name.
networks body array

A list of network object. Required parameter when there are multiple networks defined for the tenant. When you do not specify the networks parameter, the server attaches to the only network created for the current tenant. Optionally, you can create one or more NICs on the server. To provision the server instance with a NIC for a network, specify the UUID of the network in the uuid attribute in a networks object. To provision the server instance with a NIC for an already existing port, specify the port-id in the port attribute in a networks object.

If multiple networks are defined, the order in which they appear in the guest operating system will not necessarily reflect the order in which they are given in the server boot request. Guests should therefore not depend on device order to deduce any information about their network devices. Instead, device role tags should be used: introduced in 2.32, broken in 2.37, and re-introduced and fixed in 2.42, the tag is an optional, string attribute that can be used to assign a tag to a virtual network interface. This tag is then exposed to the guest in the metadata API and the config drive and is associated to hardware metadata for that network interface, such as bus (ex: PCI), bus address (ex: 0000:00:02.0), and MAC address.

A bug has caused the tag attribute to no longer be accepted starting with version 2.37. Therefore, network interfaces could only be tagged in versions 2.32 to 2.36 inclusively. Version 2.42 has restored the tag attribute.

Starting with microversion 2.37, this field is required and the special string values auto and none can be specified for networks. auto tells the Compute service to use a network that is available to the project, if one exists. If one does not exist, the Compute service will attempt to automatically allocate a network for the project (if possible). none tells the Compute service to not allocate a network for the instance. The auto and none values cannot be used with any other network values, including other network uuids, ports, fixed IPs or device tags. These are requested as strings for the networks value, not in a list. See the associated example.

networks.uuid (Optional) body string

To provision the server instance with a NIC for a network, specify the UUID of the network in the uuid attribute in a networks object. Required if you omit the port attribute.

Starting with microversion 2.37, this value is strictly enforced to be in UUID format.

networks.port (Optional) body string To provision the server instance with a NIC for an already existing port, specify the port-id in the port attribute in a networks object. The port status must be DOWN. Required if you omit the uuid attribute. Requested security groups are not applied to pre-existing ports.
networks.fixed_ip (Optional) body string A fixed IPv4 address for the NIC. Valid with a neutron or nova-networks network.
networks.tag (Optional) body string

A device role tag that can be applied to a network interface. The guest OS of a server that has devices tagged in this manner can access hardware metadata about the tagged devices from the metadata API and on the config drive, if enabled.

Note

Due to a bug, network interface tags are accepted between 2.32 and 2.36 inclusively, and subsequently starting with version 2.42.

New in version 2.32

accessIPv4 (Optional) body string IPv4 address that should be used to access this server.
accessIPv6 (Optional) body string IPv6 address that should be used to access this server.
adminPass (Optional) body string The administrative password of the server. If you omit this parameter, the operation generates a new password.
availability_zone (Optional) body string

The availability zone from which to launch the server. When you provision resources, you specify from which availability zone you want your instance to be built. Typically, an admin user will use availability zones to arrange OpenStack compute hosts into logical groups.

An availability zone provides a form of physical isolation and redundancy from other availability zones. For instance, if some racks in your data center are on a separate power source, you can put servers in those racks in their own availability zone. Availability zones can also help separate different classes of hardware. By segregating resources into availability zones, you can ensure that your application resources are spread across disparate machines to achieve high availability in the event of hardware or other failure. See Availability Zones (AZs) for more information.

You can list the available availability zones by calling the os-availability-zone API, but you should avoid using the default availability zone when creating the server. The default availability zone is named nova. This AZ is only shown when listing the availability zones as an admin.

block_device_mapping_v2 (Optional) body array

Enables fine grained control of the block device mapping for an instance. This is typically used for booting servers from volumes. An example format would look as follows:

"block_device_mapping_v2": [{
    "boot_index": "0",
    "uuid": "ac408821-c95a-448f-9292-73986c790911",
    "source_type": "image",
    "volume_size": "25",
    "destination_type": "volume",
    "delete_on_termination": true,
    "tag": "disk1",
    "disk_bus": "scsi"}]

In microversion 2.32, tag is an optional string attribute that can be used to assign a tag to the block device. This tag is then exposed to the guest in the metadata API and the config drive and is associated to hardware metadata for that block device, such as bus (ex: SCSI), bus address (ex: 1:0:2:0), and serial.

A bug has caused the tag attribute to no longer be accepted starting with version 2.33. It has been restored in version 2.42.

block_device_mapping_v2.boot_index body integer Defines the order in which a hypervisor tries devices when it attempts to boot the guest from storage. Give each device a unique boot index starting from 0. To disable a device from booting, set the boot index to a negative value or use the default boot index value, which is None. The simplest usage is, set the boot index of the boot device to 0 and use the default boot index value, None, for any other devices. Some hypervisors might not support booting from multiple devices; these hypervisors consider only the device with a boot index of 0. Some hypervisors support booting from multiple devices but only if the devices are of different types. For example, a disk and CD-ROM.
block_device_mapping_v2.delete_on_termination (Optional) body boolean To delete the boot volume when the server is destroyed, specify true. Otherwise, specify false. Default: false
block_device_mapping_v2.destination_type (Optional) body string

Defines where the block device mapping will reside. Valid values are:

  • local: The ephemeral disk resides local to the compute host on which the server runs
  • volume: The persistent volume is stored in the block storage service
block_device_mapping_v2.device_name (Optional) body string A path to the device for the volume that you want to use to boot the server. Note that as of the 12.0.0 Liberty release, the Nova libvirt driver no longer honors a user-supplied device name. This is the same behavior as if the device name parameter is not supplied on the request.
block_device_mapping_v2.device_type (Optional) body string The device type. For example, disk, cdrom.
block_device_mapping_v2.disk_bus (Optional) body string Disk bus type, some hypervisors (currently only libvirt) support specify this parameter. Some example disk_bus values can be: fdc, ide, sata, scsi, usb, virtio, xen, lxc and uml. Support for each bus type depends on the virtualization driver and underlying hypervisor.
block_device_mapping_v2.guest_format (Optional) body string

Specifies the guest server disk file system format, such as ext2, ext3, ext4, xfs or swap.

Swap block device mappings have the following restrictions:

  • The source_type must be blank
  • The destination_type must be local
  • There can only be one swap disk per server
  • The size of the swap disk must be less than or equal to the swap size of the flavor
block_device_mapping_v2.no_device (Optional) body boolean It is no device if True.
block_device_mapping_v2.source_type (Optional) body string

The source type of the block device. Valid values are:

  • blank: Depending on the destination_type and guest_format, this will either be a blank persistent volume or an ephemeral (or swap) disk local to the compute host on which the server resides
  • image: This is only valid with destination_type=volume; creates an image-backed volume in the block storage service and attaches it to the server
  • snapshot: This is only valid with destination_type=volume; creates a volume backed by the given volume snapshot referenced via the block_device_mapping_v2.uuid parameter and attaches it to the server
  • volume: This is only valid with destination_type=volume; uses the existing persistent volume referenced via the block_device_mapping_v2.uuid parameter and attaches it to the server

This parameter is required unless block_device_mapping_v2.no_device is specified.

See Block Device Mapping in Nova for more details on valid source and destination types.

block_device_mapping_v2.uuid (Optional) body string This is the uuid of source resource. The uuid points to different resources based on the source_type. For example, if source_type is image, the block device is created based on the specified image which is retrieved from the image service. Similarly, if source_type is snapshot then the uuid refers to a volume snapshot in the block storage service. If source_type is volume then the uuid refers to a volume in the block storage service.
block_device_mapping_v2.volume_size (Optional) body integer

The size of the volume (in GiB). This is integer value from range 1 to 2147483647 which can be requested as integer and string. This parameter must be specified in the following cases:

  • An image to volume case
    • block_device_mapping_v2.source_type is image
    • block_device_mapping_v2.destination_type is volume
  • A blank to volume case
    • block_device_mapping_v2.source_type is blank
    • block_device_mapping_v2.destination_type is volume
block_device_mapping_v2.tag (Optional) body string

A device role tag that can be applied to a block device. The guest OS of a server that has devices tagged in this manner can access hardware metadata about the tagged devices from the metadata API and on the config drive, if enabled.

Note

Due to a bug, block device tags are accepted in version 2.32 and subsequently starting with version 2.42.

New in version 2.32

block_device_mapping_v2.volume_type (Optional) body string

The device volume_type. This can be used to specify the type of volume which the compute service will create and attach to the server. If not specified, the block storage service will provide a default volume type. See the block storage volume types API for more details. There are some restrictions on volume_type:

  • It can be a volume type ID or name.
  • It is only supported with source_type of blank, image or snapshot.
  • It is only supported with destination_type of volume.

New in version 2.67

config_drive (Optional) body boolean Indicates whether a config drive enables metadata injection. The config_drive setting provides information about a drive that the instance can mount at boot time. The instance reads files from the drive to get information that is normally available through the metadata service. This metadata is different from the user data. Not all cloud providers enable the config_drive. Read more in the OpenStack End User Guide.
imageRef (Optional) body string The UUID of the image to use for your server instance. This is not required in case of boot from volume. In all other cases it is required and must be a valid UUID otherwise API will return 400.
key_name (Optional) body string

Key pair name.

Note

The null value was allowed in the Nova legacy v2 API, but due to strict input validation, it is not allowed in the Nova v2.1 API.

metadata (Optional) body object Metadata key and value pairs. The maximum size of the metadata key and value is 255 bytes each.
OS-DCF:diskConfig (Optional) body string

Controls how the API partitions the disk when you create, rebuild, or resize servers. A server inherits the OS-DCF:diskConfig value from the image from which it was created, and an image inherits the OS-DCF:diskConfig value from the server from which it was created. To override the inherited setting, you can include this attribute in the request body of a server create, rebuild, or resize request. If the OS-DCF:diskConfig value for an image is MANUAL, you cannot create a server from that image and set its OS-DCF:diskConfig value to AUTO. A valid value is:

  • AUTO. The API builds the server with a single partition the size of the target flavor disk. The API automatically adjusts the file system to fit the entire partition.
  • MANUAL. The API builds the server by using whatever partition scheme and file system is in the source image. If the target flavor disk is larger, the API does not partition the remaining disk space.
personality (Optional) body array

The file path and contents, text only, to inject into the server at launch. The maximum size of the file path data is 255 bytes. The maximum limit is the number of allowed bytes in the decoded, rather than encoded, data.

Available until version 2.56

security_groups (Optional) body array One or more security groups. Specify the name of the security group in the name attribute. If you omit this attribute, the API creates the server in the default security group. Requested security groups are not applied to pre-existing ports.
user_data (Optional) body string

Configuration information or scripts to use upon launch. Must be Base64 encoded. Restricted to 65535 bytes.

Note

The null value allowed in Nova legacy v2 API, but due to the strict input validation, it isn’t allowed in Nova v2.1 API.

description (Optional) body string

A free form description of the server. Limited to 255 characters in length. Before microversion 2.19 this was set to the server name.

New in version 2.19

tags (Optional) body array

A list of tags. Tags have the following restrictions:

  • Tag is a Unicode bytestring no longer than 60 characters.
  • Tag is a non-empty string.
  • ‘/’ is not allowed to be in a tag name
  • Comma is not allowed to be in a tag name in order to simplify requests that specify lists of tags
  • All other characters are allowed to be in a tag name
  • Each server can have up to 50 tags.

New in version 2.52

trusted_image_certificates (Optional) body array

A list of trusted certificate IDs, which are used during image signature verification to verify the signing certificate. The list is restricted to a maximum of 50 IDs. This parameter is optional in server create requests if allowed by policy, and is not supported for volume-backed instances.

New in version 2.63

host (Optional) body string

The name of the compute service host on which the server is to be created. The API will return 400 if no compute services are found with the given host name. By default, it can be specified by administrators only.

New in version 2.74

hypervisor_hostname (Optional) body string

The hostname of the hypervisor on which the server is to be created. The API will return 400 if no hypervisors are found with the given hostname. By default, it can be specified by administrators only.

New in version 2.74

os:scheduler_hints (Optional) body object

The dictionary of data to send to the scheduler. Alternatively, you can specify OS-SCH-HNT:scheduler_hints as the key in the request body.

Note

This is a top-level key in the request body, not part of the server portion of the request body.

There are a few caveats with scheduler hints:

  • The request validation schema is per hint. For example, some require a single string value, and some accept a list of values.
  • Hints are only used based on the cloud scheduler configuration, which varies per deployment.
  • Hints are pluggable per deployment, meaning that a cloud can have custom hints which may not be available in another cloud.

For these reasons, it is important to consult each cloud’s user documentation to know what is available for scheduler hints.

os:scheduler_hints.build_near_host_ip (Optional) body string Schedule the server on a host in the network specified with this parameter and a cidr (os:scheduler_hints.cidr). It is available when SimpleCIDRAffinityFilter is available on cloud side.
os:scheduler_hints.cidr (Optional) body string Schedule the server on a host in the network specified with an IP address (os:scheduler_hints:build_near_host_ip) and this parameter. If os:scheduler_hints:build_near_host_ip is specified and this paramete is omitted, /24 is used. It is available when SimpleCIDRAffinityFilter is available on cloud side.
os:scheduler_hints.different_cell (Optional) body array A list of cell routes or a cell route (string). Schedule the server in a cell that is not specified. It is available when DifferentCellFilter is available on cloud side that is cell v1 environment.
os:scheduler_hints.different_host (Optional) body array A list of server UUIDs or a server UUID. Schedule the server on a different host from a set of servers. It is available when DifferentHostFilter is available on cloud side.
os:scheduler_hints.group (Optional) body string The server group UUID. Schedule the server according to a policy of the server group (anti-affinity, affinity, soft-anti-affinity or soft-affinity). It is available when ServerGroupAffinityFilter, ServerGroupAntiAffinityFilter, ServerGroupSoftAntiAffinityWeigher, ServerGroupSoftAffinityWeigher are available on cloud side.
os:scheduler_hints.query (Optional) body string

Schedule the server by using a custom filter in JSON format. For example:

"query": "[\">=\",\"$free_ram_mb\",1024]"

It is available when JsonFilter is available on cloud side.

os:scheduler_hints.same_host (Optional) body array A list of server UUIDs or a server UUID. Schedule the server on the same host as another server in a set of servers. It is available when SameHostFilter is available on cloud side.
os:scheduler_hints.target_cell (Optional) body string A target cell name. Schedule the server in a host in the cell specified. It is available when TargetCellFilter is available on cloud side that is cell v1 environment.

13.2.1.1. Example

Create a VM with the specified flavor, from the specified image. Create two NICs in the specified network, get one IP address from DHCP and set the other manually. The placement will be inherited from the image.

# curl -ks -H 'Content-Type: application/json' -H 'X-Auth-Token: gAAAAA<...>' -d '
{
  "server": {
    "name": "vm2",
    "flavorRef": "100",
    "networks": [
      {
        "uuid": "56b9b3ab-219a-41a5-a9f0-ebf5ee74f827",
		"fixed_ip": "192.168.128.10"
      },
      {
        "uuid": "17062703-8551-46e3-bf37-5509d9f93462"
      }
	  
    ],
    "block_device_mapping_v2": [
      {
        "boot_index": "0",
        "uuid": "c92d820c-50dc-4fd1-a0bc-2f1071487b67",
        "source_type": "image",
        "volume_size": "1",
        "destination_type": "volume",
        "delete_on_termination": true
      }
    ]
  }
}' https://<node_IP_addr>:8774/v2.1/f5d834d636c642c7bfe8af86139c6f26/servers

13.2.2. Response

Name In Type Description
Location header string The location URL of the server, HTTP header “Location: <server location URL>” will be returned.
server body object A server object.
id body string The UUID of the server.
links body array Links to the resources in question. See API Guide / Links and References for more info.
OS-DCF:diskConfig body string

Disk configuration. The value is either:

  • AUTO. The API builds the server with a single partition the size of the target flavor disk. The API automatically adjusts the file system to fit the entire partition.
  • MANUAL. The API builds the server by using the partition scheme and file system that is in the source image. If the target flavor disk is larger, The API does not partition the remaining disk space.
security_groups body array One or more security groups objects.
security_groups.name body string The security group name.
adminPass (Optional) body string The administrative password for the server. If you set enable_instance_password configuration option to False, the API wouldn’t return the adminPass field in response.

13.2.2.1. Status codes

13.2.2.1.1. Success

Code Reason
202 - Accepted Request was accepted for processing, but the processing has not been completed. A ‘location’ header is included in the response which contains a link to check the progress of the request.

13.2.2.1.2. Error

Code Reason
400 - Bad Request Some content in the request was invalid.
401 - Unauthorized User must authenticate before making a request.
403 - Forbidden Policy does not allow current user to do this operation.
404 - Not Found The requested resource could not be found.
409 - Conflict This operation conflicted with another operation on this resource.

13.2.2.2. Example

{
  "server": {
    "security_groups": [
      {
        "name": "default"
      }
    ],
    "OS-DCF:diskConfig": "MANUAL",
    "id": "c3f154f1-c656-49b4-a6c0-4dd1e088817c",
    "links": [
      {
        "href": "https://<node_IP_addr>:8774/v2.1/f5d834d636c642c7bfe8af86139c6f26/servers/c3f154f1-c656-49b4-a6c0-4dd1e088817c",
        "rel": "self"
      },
      {
        "href": "https://<node_IP_addr>:8774/f5d834d636c642c7bfe8af86139c6f26/servers/c3f154f1-c656-49b4-a6c0-4dd1e088817c",
        "rel": "bookmark"
      }
    ],
    "adminPass": "54e8z6YWPoEp"
  }
}