Creating virtual machines

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.

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.

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

The IDs of security groups applied to the port.

New in version 2.67

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.

New in version 2.32

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.

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.

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

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

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.

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

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.

New in version 2.32

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

Key pair name.

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.

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

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

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

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

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

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

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

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.

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.

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.

The security group name.

Some content in the request was invalid.

User must authenticate before making a request.

Policy does not allow current user to do this operation.

The requested resource could not be found.