Skip to main content

Create VM

POST/v2.1/servers

To create a new virtual machine (VM), you can send a POST request to the /v2.1/servers endpoint of the compute service. This request requires an authentication token, which you should include in the request headers.

note

You should add X-OpenStack-Nova-API-Version: 2.67 to the request headers to ensure compatibility with the API version.

info

Source: create-server

Request​

Body Parameters​

serverobjectrequired

A server object.

flavorRefstringrequired

Flavor reference (ID/UUID or full URL).

namestringrequired

Server name.

networksarrayrequired

Network attachments. Required when multiple networks exist. From 2.37, supports string values "auto" or "none" (not a list) and cannot be combined with other network values. Interface tag accepted in 2.32–2.36 and from 2.42.

8 fields
uuidstringbody

Network UUID for a NIC. Required if port is omitted. Enforced UUID format from 2.37.

portstringbody

Existing port ID (must be DOWN). Required if uuid is omitted. Requested security groups are not applied to pre-existing ports.

fixed_ipsarraybody

Fixed IPs. If specifying an IP, a network uuid/net_id is also required.

ip_addressstringbody

Fixed IP address.

ip_versionintegerbody

IP version 4 or 6. Default 4.

port_security_enabledbooleanrequiredbody

Default port_security_enabled for a created port. New in 2.42.

security_groupsarrayrequiredbody

Security group IDs for the port. New in 2.67.

tagstringbody

Device role tag exposed via metadata/config drive. Accepted in 2.32–2.36 and from 2.42.

accessIPv4string

IPv4 address to access the server.

accessIPv6string

IPv6 address to access the server.

adminPassstring

Admin password; generated if omitted.

block_device_mapping_v2array

Advanced block device mappings (boot from volume, etc.). Tags accepted in 2.32 and from 2.42.

13 fields
boot_indexintegerrequiredbody

Boot order; 0 boots first; negative or None disables.

delete_on_terminationbooleanbody

Delete volume on server deletion. Default false.

destination_typestringbody

Device location: local or volume.

device_namestringbody

Device path; ignored by libvirt since 12.0.0.

device_typestringbody

Device type (e.g., disk, cdrom).

disk_busstringbody

Bus type (e.g., ide, scsi, virtio).

guest_formatstringbody

Filesystem (e.g., ext4, xfs, swap). Swap has specific restrictions.

no_devicebooleanbody

Marks as no device if true.

source_typestringbody

Source: blank, image, snapshot, or volume. Required unless no_device is true.

uuidstringbody

Source resource UUID (image/snapshot/volume).

volume_sizeintegerbody

Volume size (GiB). Required for image→volume and blank→volume.

tagstringbody

Block device role tag; accepted in 2.32 and from 2.42.

volume_typestringbody

Volume type ID or name; only with source blank/image/snapshot and destination volume. New in 2.67.

config_driveboolean

Enable config drive for metadata injection.

imageRefstring

Image UUID. Required unless booting from volume.

key_namestring

Key pair name.

metadataobject

Metadata key/value pairs (max 255 bytes each).

OS-DCF:diskConfigstring

Disk partitioning: AUTO or MANUAL. Cannot force MANUAL image to AUTO.

2 values
  • AUTO Builds the server with a single partition the size of the target flavor disk, and grows the file system to fill it.
  • MANUAL Uses the partition scheme and file system from the source image. Extra space stays unpartitioned.
personalityarray

Inject text files at launch. Available until 2.56.

user_datastring

Base64-encoded user data (< 65535 bytes).

descriptionstring

Free-form description (< 255 chars). New in 2.19.

tagsarray

Up to 50 tags; each non-empty, < 60 chars; '/' and ',' not allowed. New in 2.52.

trusted_image_certificatesarray

Up to 50 certificate IDs for image signature verification; not for volume-backed. New in 2.63.

hoststring

Target compute host name; typically admin-only. New in 2.74.

hypervisor_hostnamestring

Target hypervisor hostname; typically admin-only. New in 2.74.

os:scheduler_hintsobject

Top-level scheduler hints; availability varies by cloud.

8 fields
build_near_host_ipstringbody

Prefer hosts near this IP (with cidr). Requires SimpleCIDRAffinityFilter.

cidrstringbody

CIDR for build_near_host_ip; defaults to /24 if omitted.

different_cellarraybody

Schedule away from listed cells (names/routes). Cell v1 env.

different_hostarraybody

Prefer hosts different from given server UUIDs.

groupstringbody

Server group UUID; applies group policy (affinity/anti-affinity).

querystringbody

JsonFilter expression.

same_hostarraybody

Prefer same host as given server UUIDs.

target_cellstringbody

Target cell name. Cell v1 env.

curl -ks -H 'Content-Type: application/json' -H 'X-Auth-Token: gAAAAA<...>' -H 'X-OpenStack-Nova-API-Version: 2.67' \
-d '{
  "server": {
        "name": "Ubuntu24",
        "imageRef": "b4d9c688-1b96-4604-8cf1-d78c5c80a984",
        "block_device_mapping_v2": [
            {
                "boot_index": "0",
                "uuid": "b4d9c688-1b96-4604-8cf1-d78c5c80a984",
                "source_type": "image",
                "volume_size": "10",
                "destination_type": "volume",
                "volume_type": "nvmer3",
                "delete_on_termination": true
            }
        ],
        "OS-DCF:diskConfig": "AUTO",
        "flavorRef": "468c0c15-08bd-4e1d-8564-5053ce12966b",
        "networks": [
      {
        "uuid": "8ae2b710-ad3d-469e-a75a-c3e203887d2e"
      }
    ],
        "key_name": "Docs Writter"
    }
}' https://api.vietnix.cloud:8774/v2.1/servers

Response​

Parameters​

Locationstringrequiredheader

Location URL of the created server. Returned in the Location response header.

serverobjectrequiredbody

Server object.

idstringrequiredbody

UUID of the server.

linksarrayrequiredbody

Array of links to related resources.

adminPassstringrequiredbody

Administrative password for the server. Optional; returned only if enable_instance_password is True.

security_groupsarrayrequiredbody

One or more security group objects.

1 field
namestringrequiredbody

Security group name.

OS-DCFstringrequiredbody

Disk configuration. One of: AUTO (single partition sized to flavor disk), MANUAL (use source image layout; extra space remains unpartitioned).

Status Codes​

Success​

Status CodeDescription
200 - OKRequest was successful.
202 - AcceptedRequest 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.

Error​

Status CodeDescription
400 - Bad RequestSome content in the request was invalid.
401 - UnauthorizedUser must authenticate before making a request.
403 - ForbiddenPolicy does not allow current user to do this operation.
404 - Not FoundThe requested resource could not be found.
409 - ConflictThis operation conflicted with another operation on this resource.

Sample Response​

Response body
{
    "server": {
        "id": "70748c08-0f81-4e73-b2f1-7568e5339faa",
        "links": [
            {
                "rel": "self",
                "href": "https://api.vietnix.cloud:8774/v2.1/servers/70748c08-0f81-4e73-b2f1-7568e5339faa"
            },
            {
                "rel": "bookmark",
                "href": "https://api.vietnix.cloud:8774/servers/70748c08-0f81-4e73-b2f1-7568e5339faa"
            }
        ],
        "OS-DCF:diskConfig": "AUTO",
        "security_groups": [
            {
                "name": "default"
            }
        ],
        "adminPass": "z344qQ3xajM4"
    }
}