Prev Next

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_ips` (Optional)	body	array	Fixed IP addresses. If you request a specific fixed IP address without a network’s `uuid` or `net_id`, the request returns a `Bad Request (400)` response code.
`networks.ip_address` (Optional)	body	string	The IP address.
`networks.ip_version` (Optional)	body	integer	The IP protocol version. Valid value is `4` or `6`. Default is `4`.
`networks.port_security_enabled`	body	boolean	The port security status of the network. Valid values are enabled (`true`) and disabled (`false`). This value is used as the default value of `port_security_enabled` field of a newly created port. New in version 2.42
`networks.security_groups`	body	array	The IDs of security groups applied to the port. New in version 2.67
`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
`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 networks, assign one IP address manually and the other one automatically from the IPv4 subnet. The placement will be inherited from the image.

# curl -ks -H 'Content-Type: application/json' -H 'X-OpenStack-Nova-API-Version: 2.67' -H 'X-Auth-Token: gAAAAA<...>' -d '
{
  "server": {
    "name": "vm2",
    "flavorRef": "100",
    "networks": [
      {
        "uuid": "0bb6b7a7-da8d-432c-b8d5-12139f7924d1",
        "fixed_ips": [{"ip_address": "192.168.128.10"}],
        "port_security_enabled": true,
        "security_groups": ["5c2f26d9-c599-41db-b67b-b47811b58e28"]
      },
      {
        "uuid": "17062703-8551-46e3-bf37-5509d9f93462",
        "fixed_ips": [{"ip_version": 4}],
        "port_security_enabled": true,
        "security_groups": ["5c2f26d9-c599-41db-b67b-b47811b58e28"]
      }
    ],
    "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"
  }
}

Version 5.0.0 — Feb 01, 2022

Prev Next