Chuyển tới nội dung chính

Create VM

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​

NameInTypeDescription
serverbodyobjectA server object.
flavorRefbodystringFlavor reference (ID/UUID or full URL).
namebodystringServer name.
networksbodyarrayNetwork 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.
networks.uuid (Optional)bodystringNetwork UUID for a NIC. Required if port is omitted. Enforced UUID format from 2.37.
networks.port (Optional)bodystringExisting port ID (must be DOWN). Required if uuid is omitted. Requested security groups are not applied to pre-existing ports.
networks.fixed_ips (Optional)bodyarrayFixed IPs. If specifying an IP, a network uuid/net_id is also required.
networks.ip_address (Optional)bodystringFixed IP address.
networks.ip_version (Optional)bodyintegerIP version 4 or 6. Default 4.
networks.port_security_enabledbodybooleanDefault port_security_enabled for a created port. New in 2.42.
networks.security_groupsbodyarraySecurity group IDs for the port. New in 2.67.
networks.tag (Optional)bodystringDevice role tag exposed via metadata/config drive. Accepted in 2.32–2.36 and from 2.42.
accessIPv4 (Optional)bodystringIPv4 address to access the server.
accessIPv6 (Optional)bodystringIPv6 address to access the server.
adminPass (Optional)bodystringAdmin password; generated if omitted.
block_device_mapping_v2 (Optional)bodyarrayAdvanced block device mappings (boot from volume, etc.). Tags accepted in 2.32 and from 2.42.
block_device_mapping_v2.boot_indexbodyintegerBoot order; 0 boots first; negative or None disables.
block_device_mapping_v2.delete_on_termination (Optional)bodybooleanDelete volume on server deletion. Default false.
block_device_mapping_v2.destination_type (Optional)bodystringDevice location: local or volume.
block_device_mapping_v2.device_name (Optional)bodystringDevice path; ignored by libvirt since 12.0.0.
block_device_mapping_v2.device_type (Optional)bodystringDevice type (e.g., disk, cdrom).
block_device_mapping_v2.disk_bus (Optional)bodystringBus type (e.g., ide, scsi, virtio).
block_device_mapping_v2.guest_format (Optional)bodystringFilesystem (e.g., ext4, xfs, swap). Swap has specific restrictions.
block_device_mapping_v2.no_device (Optional)bodybooleanMarks as no device if true.
block_device_mapping_v2.source_type (Optional)bodystringSource: blank, image, snapshot, or volume. Required unless no_device is true.
block_device_mapping_v2.uuid (Optional)bodystringSource resource UUID (image/snapshot/volume).
block_device_mapping_v2.volume_size (Optional)bodyintegerVolume size (GiB). Required for image→volume and blank→volume.
block_device_mapping_v2.tag (Optional)bodystringBlock device role tag; accepted in 2.32 and from 2.42.
block_device_mapping_v2.volume_type (Optional)bodystringVolume type ID or name; only with source blank/image/snapshot and destination volume. New in 2.67.
config_drive (Optional)bodybooleanEnable config drive for metadata injection.
imageRef (Optional)bodystringImage UUID. Required unless booting from volume.
key_name (Optional)bodystringKey pair name.
metadata (Optional)bodyobjectMetadata key/value pairs (max 255 bytes each).
OS-DCF:diskConfig (Optional)bodystringDisk partitioning: AUTO or MANUAL. Cannot force MANUAL image to AUTO.
personality (Optional)bodyarrayInject text files at launch. Available until 2.56.
user_data (Optional)bodystringBase64-encoded user data (< 65535 bytes).
description (Optional)bodystringFree-form description (< 255 chars). New in 2.19.
tags (Optional)bodyarrayUp to 50 tags; each non-empty, < 60 chars; '/' and ',' not allowed. New in 2.52.
trusted_image_certificates (Optional)bodyarrayUp to 50 certificate IDs for image signature verification; not for volume-backed. New in 2.63.
host (Optional)bodystringTarget compute host name; typically admin-only. New in 2.74.
hypervisor_hostname (Optional)bodystringTarget hypervisor hostname; typically admin-only. New in 2.74.
os:scheduler_hints (Optional)bodyobjectTop-level scheduler hints; availability varies by cloud.
os:scheduler_hints.build_near_host_ip (Optional)bodystringPrefer hosts near this IP (with cidr). Requires SimpleCIDRAffinityFilter.
os:scheduler_hints.cidr (Optional)bodystringCIDR for build_near_host_ip; defaults to /24 if omitted.
os:scheduler_hints.different_cell (Optional)bodyarraySchedule away from listed cells (names/routes). Cell v1 env.
os:scheduler_hints.different_host (Optional)bodyarrayPrefer hosts different from given server UUIDs.
os:scheduler_hints.group (Optional)bodystringServer group UUID; applies group policy (affinity/anti-affinity).
os:scheduler_hints.query (Optional)bodystringJsonFilter expression.
os:scheduler_hints.same_host (Optional)bodyarrayPrefer same host as given server UUIDs.
os:scheduler_hints.target_cell (Optional)bodystringTarget cell name. Cell v1 env.

Using curl​

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

Using HTTP request​

POST https://api.vietnix.cloud:8774/v2.1/servers
Content-Type: application/json
X-Auth-Token: gAAAAA<...>
X-OpenStack-Nova-API-Version: 2.67

{
  "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"
    }
}

Response​

Parameters​

NameInTypeDescription
LocationheaderstringLocation URL of the created server. Returned in the Location response header.
serverbodyobjectServer object.
idbodystringUUID of the server.
linksbodyarrayArray of links to related resources.
adminPassbodystringAdministrative password for the server. Optional; returned only if enable_instance_password is True.
security_groupsbodyarrayOne or more security group objects.
security_groups.namebodystringSecurity group name.
OS-DCF:diskConfigbodystringDisk 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​

{
    "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"
    }
}