更新时间:2024-07-23 GMT+08:00

创建云服务器

功能介绍

创建一台弹性云服务器

该接口在云服务器创建失败后不支持自动回滚。若需要自动回滚能力,可以调用POST /v1/{project_id}/cloudservers接口,具体使用请参见创建云服务器

URI

POST /v2.1/{project_id}/servers

参数说明请参见表1
表1 参数说明

参数

是否必选

描述

project_id

项目ID。

获取方法请参见获取项目ID

创建弹性云服务器接口别名:/v2/{project_id}/os-volumes_boot,该调用方式仅在OpenStack Client中使用,用户不推荐使用。

接口约束

  1. 该接口为原生接口,不支持整机镜像创建弹性云服务器功能。如需使用整机镜像创建弹性云服务器,请使用创建云服务器
  2. 使用该接口创建的云服务器,不支持在创建过程中绑定弹性公网IP,推荐使用创建云服务器创建云服务器并绑定弹性公网IP。
  3. 网络的三个参数(port、uuid和fixed_ip)中,port优先级最高;指定fixed_ip时必须指明uuid。
  4. 注入文件失败,将导致创建弹性云服务器失败。
  5. 使用镜像创建弹性云服务器时,存在下面约束:
    1. 不支持指定Host创建弹性云服务器
    2. 租户如果对弹性云服务器中的卷进行了备份,则需要租户自行删除该卷所对应的快照等数据后,才能删除卷。
    3. 调整镜像创建的弹性云服务器规格时,不支持resource_type不同的flavor之间的规格调整。
  6. 云服务平台提供的原生接口/v2/{project_id}/servers 和 /v2.1/{project_id}/servers 是基于社区版OpenStack原生接口加固而成的,兼容社区版OpenStack原生接口。
    较之社区版的OpenStack原生接口,在使用指定镜像的方式创建弹性云服务器时存在如下差异:
    • 社区OpenStack原生接口:默认使用服务器本地磁盘创建弹性云服务器
    • 云服务平台提供的原生接口:为了保障可靠性,使用共享存储作为系统盘创建弹性云服务器
    该差异的具体表现为,当您使用提供的原生接口创建云服务器时:
    1. 可以查询到云服务器挂载的系统盘信息。
    2. 云服务器的系统盘会占用云硬盘的配额。
    3. 不支持使用image过滤查询指定镜像方式创建的弹性云服务器
  7. 指定卷创建弹性云服务器场景下,指定的卷与创建的弹性云服务器必须处于相同的AZ(availability_zone)。
  8. 用户创建弹性云服务器时在block_device_mapping_v2设置的device_name字段不会生效,系统会默认生成一个device_name。
  9. 请勿使用“provider:network_type”为“geneve”的网络来创建弹性云服务器

    “provider:network_type”为“geneve”时,表示裸金属服务器使用的内部高速网络。

  10. 如果使用密钥方式远程登录云服务器,请使用key_name参数。如果使用密码方式远程登录云服务器,可使用adminPass参数;对于Linux云服务器,还可使用user_data进行注入,对于Windows云服务器,还可通过元数据admin_pass进行注入。
  11. 如果用于创建弹性云服务器的镜像使用的是原生接口,则在创建云服务器时,需注意将指定的AZ、系统盘大小和类型与创建镜像时所使用的云服务器的AZ、系统盘大小和类型保持一致,否则弹性云服务器将无法创建成功。

请求消息

请求参数如表2所示。

表2 请求参数

参数

是否必选

参数类型

描述

server

Object

弹性云服务器信息,参见表3

os:scheduler_hints

Object

弹性云服务器调度信息,参见表8。裸金属服务器场景不支持。

表3 server参数信息

参数

是否必选

参数类型

描述

imageRef

String

镜像ID或者镜像资源的URL。

  • 镜像ID示例:3b8d6fef-af77-42ab-b8b7-5a7f0f0af8f2
  • 镜像URL示例:http://glance.openstack.example.com/images/3b8d6fef-af77-42ab-b8b7-5a7f0f0af8f2
  • 指定卷作为系统卷创弹性云服务器时,不需填写该参数;非卷创建弹性云服务器时需填写有效的UUID参数,否则API将返回400错误。

flavorRef

String

规格ID或URL。

规格ID示例:c3.2xlarge

name

String

弹性云服务器名称。

取值范围:

  • 只能由中文字符、英文字母、数字及“_”、“-”、“.”组成,且长度为[1-128]个英文字符或[1-64]个中文字符。
  • 创建的云服务器数量(count字段对应的值)大于1时,为区分不同云服务器,创建过程中系统会自动在名称后加“-0000”的类似标记。若用户在名称后已指定“-0000”的类似标记,系统将从该标记后继续顺序递增编号。故此时名称的长度为[1-59]个字符。
    说明:

    云服务器虚拟机内部(hostname)命名规则遵循 RFC 952RFC 1123命名规范,建议使用a-z或0-9以及中划线"-"组成的名称命名,"_"将在弹性云服务器内部默认转化为"-"。

说明:

云服务器内部主机名(hostname)命名规则遵循 RFC 952RFC 1123命名规范,建议使用a-z或0-9以及中划线"-"组成的名称命名,"_"将在云服务器内部默认转化为"-"。

metadata

Map<String,String>

弹性云服务器元数据。参见表4

  • key的长度大于0小于256字节
  • value的长度大于等于0小于256字节

adminPass

String

如果需要使用密码方式登录云服务器,可使用adminPass字段指定云服务器管理员账户初始登录密码。其中,Linux管理员账户为root,Windows管理员账户为Administrator。

block_device_mapping_v2

Array of objects

扩展属性,指定弹性云服务器存储设备的v2接口。是存储资源的新版本接口,指定卷场景不能批创弹性云服务器。参见表5。裸金属服务器场景不支持。

config_drive

String

扩展属性,开启后在弹性云服务器创建时挂载config_drive向弹性云服务器内部传递信息。

当前不支持该功能。

security_groups

Array of objects

扩展属性,指定弹性云服务器的安全组,默认为default。

指定network创建弹性云服务器时该字段有效。对于已存在端口,安全组请求无效。具体请参见表6

networks

Array of objects

扩展属性,指定弹性云服务器的网卡信息。有多个租户网络时必须指定。参照表7

key_name

String

扩展属性,指定keypair的名称。

user_data

String

创建云服务器过程中待注入实例自定义数据。支持注入文本、文本文件。

说明:
  • user_data的值为base64编码之后的内容。
  • 注入内容(编码之前的内容)最大长度为32K。

更多关于待注入实例自定义数据的信息,请参见《弹性云服务器用户指南 》的“实例自定义数据注入”章节。

示例:

base64编码前:

  • Linux服务器:
    #!/bin/bash
    echo user_test > /home/user.txt
  • Windows服务器:
    rem cmd
    echo 111 > c:\aaa.txt

base64编码后:

  • Linux服务器:
    IyEvYmluL2Jhc2gKZWNobyB1c2VyX3Rlc3QgPiAvaG9tZS91c2VyLnR4dA==
  • Windows服务器:
    cmVtIGNtZAplY2hvIDExMSA+IGM6XGFhYS50eHQ=

availability_zone

String

扩展属性,指定弹性云服务器所在的AZ。

创建弹性云服务器时需要填入该参数。

return_reservation_id

Boolean

扩展属性,是否支持返回批量创建弹性云服务器的reservation_id。通过返回的reservation_id,可以过滤查询到本次创建的弹性云服务器

  • true,返回reservation_id。
  • false,返回弹性云服务器信息。
    说明:

    批量创建弹性云服务器时,支持使用该字段。

min_count

Integer

扩展属性,表示创建弹性云服务器最小数量。

默认值为1。

说明:

指定镜像创建弹性云服务器时,支持使用该字段。

max_count

Integer

表示创建弹性云服务器最大数量。

默认值与min_count的取值一致。

约束:

  • 参数max_count的取值必须大于等于参数min_count的取值。
  • 当min_count、max_count同时设置时,创弹性云服务器的数量取决于服务器的资源情况。根据资源情况,在min_count至max_count的取值范围内创建最大数量的弹性云服务器
说明:

指定镜像创建弹性云服务器时,支持使用该字段。

OS-DCF:diskConfig

String

diskConfig的方式,取值为AUTO、MANUAL。

  • MANUAL,镜像空间不会扩展。
  • AUTO,系统盘镜像空间会自动扩展为与flavor大小一致。

当前不支持该功能。

description

String

扩展属性,表示弹性云服务器描述信息,默认为空字符串。

微版本2.19及以上版本支持。

  • 长度最多允许85个字符。
  • 不能包含“<” 和 “>”等特殊符号。
表4 metadata字段数据结构说明

参数

是否必选

参数类型

描述

admin_pass

String

Windows弹性云服务器Administrator用户的密码。

说明:

创建密码方式鉴权的Windows弹性云服务器时为必选字段。

表5 block_device_mapping_v2参数

参数

参数类型

是否必选

描述

source_type

String

卷设备的源头类型,当前只支持volume、image、snapshot、blank类型。

当使用卷创建云服务器时,source_type设置为volume;当使用镜像创建云服务器时,source_type设置为image;当使用快照创建云服务器时,source_type设置为snapshot;当创建空数据卷时,source_type设置为blank。

说明:

当卷设备的源头类型为snapshot时,且boot_index为0,则该快照对应的云硬盘必须为系统盘。

destination_type

String

卷设备的目标类型,当前仅支持volume类型。

  • volume:卷。
  • local:本地文件,当前不支持该类型。

guest_format

String

local文件系统格式,例如:swap, ext4。

当前不支持该功能。

device_name

String

卷设备名称。

说明:

该字段已经废弃。

用户指定的device_name不会生效,系统会默认生成一个device_name。

delete_on_termination

Boolean

删除弹性云服务器时,是否删除卷,默认值false。

  • true:删除弹性云服务器时,删除卷
  • false:删除弹性云服务器时,不删除卷

boot_index

String

启动标识,“0”代表启动盘,“-1”代表非启动盘。

不传该字段时默认取值为“-1”。

说明:

当卷设备的源头类型全为volume时,boot_index的值有一个为0。

uuid

String

  • 当source_type值是volume时,uuid为卷的uuid;
  • 当source_type值是snapshot时,uuid为快照的uuid;
  • 当source_type值是image时,uuid为镜像的uuid;

volume_size

Integer

卷大小,整数,在source_type是image或blank,destination_type是volume的时候必选。

单位为GB。

volume_type

String

卷类型,在source_type是image,destination_type是volume时建议填写。

表6 security_groups参数

参数

是否必选

参数类型

描述

name

String

安全组名称或者uuid。

表7 networks参数

参数

是否必选

参数类型

描述

port

String

网络port uuid。

没有指定网络uuid时必须指定。

uuid

String

网络uuid。

没有指定网络port时必须指定。

fixed_ip

String

指定的IP地址。网络的三个参数(port、uuid和fixed_ip)中,port优先级最高;指定fixed_ip时必须指明uuid。

表8 os:scheduler_hints参数

参数

是否必选

参数类型

描述

group

String

反亲和性组信息。

UUID格式。

说明:

请确保云服务器组使用的是反亲和性anti-affinity策略,不推荐使用其他策略。

different_host

Array of strings

预留字段,当前不支持该功能。

same_host

Array of strings

预留字段,当前不支持该功能。

cidr

String

预留字段,当前不支持该功能。

build_near_host_ip

String

预留字段,当前不支持该功能。

tenancy

String

在专属主机或共享池中创建弹性云服务器。默认为在共享池创建。

值为: shareddedicated

  • shared:表示共享池。
  • dedicated:表示专属主机。

创建与查询此值均有效。

dedicated_host_id

String

专属主机ID。

此属性仅在tenancy值为dedicated时有效。

不指定此属性,系统将自动分配租户可自动放置弹性云服务器的专属主机。

创建与查询此值均有效。

响应消息

响应参数如表9所示。

表9 响应参数

参数

参数类型

描述

server

Object

云服务器信息,详情请参见表10

表10 server字段数据结构说明

参数

参数类型

描述

id

String

弹性云服务器ID,UUID格式。

links

Array of objects

弹性云服务器URI自描述信息,详情参见表11

security_groups

Array of objects

弹性云服务器所在安全组,详情参见表12

OS-DCF:diskConfig

String

diskConfig方式。

  • MANUAL,镜像空间不会扩展。
  • AUTO,系统盘镜像空间会自动扩展为与flavor大小一致。

reservation_id

String

reservation_id:通过返回的reservation_id,可以过滤查询到本次创建的弹性云服务器
说明:

批量创建弹性云服务器时,支持使用该字段。

adminPass

String

Windows弹性云服务器Administrator用户的密码。

表11 links字段数据结构说明

参数

参数类型

描述

rel

String

快捷链接标记名称。

href

String

对应快捷链接。

表12 security_groups字段数据结构说明

参数

参数类型

描述

name

String

安全组名称或者uuid。

请求示例

  • 通过block_device_mapping_v2扩展属性使用镜像创建一台云服务器,采用密钥方式登录鉴权。
    POST https://{endpoint}/v2.1/9c53a566cb3443ab910cf0daebca90c4/servers
    
    { 
        "server": { 
            "flavorRef": "s3.xlarge.2", 
            "name": "wjvm48", 
            "metadata": { 
                "name": "name_xx1", 
                "id": "id_xxxx1" 
            }, 
            "block_device_mapping_v2": [{ 
                "source_type": "image", 
                "destination_type": "volume", 
                "uuid": "b023fe17-11db-4efb-b800-78882a0e394b", 
                "delete_on_termination": "False", 
                "boot_index": "0",
                "volume_type": "SAS",
                "volume_size": "40"
            }], 
            "security_groups": [{ 
                "name": "name_xx5_sg" 
            }], 
            "networks": [{ 
                "uuid": "fd40e6f8-942d-4b4e-a7ae-465287b02a2c", 
                "port": "e730a11c-1a19-49cc-8797-cee2ad67af6f", 
                "fixed_ip": "10.20.30.137" 
            }], 
            "key_name": "test", 
            "user_data": "ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBpdCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5kIGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVsc2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4gQnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRoZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlvdSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vyc2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6b25zLiINCg0KLVJpY2hhcmQgQmFjaA==", 
            "availability_zone":"az1-dc1"
        } 
    }
  • 通过block_device_mapping_v2扩展属性使用快照创建一台云服务器,其中,boot_index为0,且该快照对应的云硬盘必须为系统盘。
    POST https://{endpoint}/v2.1/9c53a566cb3443ab910cf0daebca90c4/servers
    
    {
        "server":{
            "name":"wjvm48",
            "availability_zone":"az1-dc1",
            "block_device_mapping_v2": [
                {
                    "source_type":"snapshot",
                    "boot_index":"0",
                    "uuid":"df51997d-ee35-4fb3-a372-e2ac933a6565", // snapshot id,创建snapshot接口会返回id
                    "destination_type":"volume"
                }
            ],
            "flavorRef":"s3.xlarge.2",
            "max_count":1,
            "min_count":1,
            "networks": [
                {
                    "uuid":"79a68cef-0936-4e21-b1f4-b800ecb70246"
                }
            ] 
        } 
    }
  • 通过block_device_mapping_v2使用卷创建一台弹性云服务器
    POST https://{endpoint}/v2.1/9c53a566cb3443ab910cf0daebca90c4/servers
    
    { 
        "server": { 
            "flavorRef": "s3.xlarge.2", 
            "name": "wjvm48", 
            "metadata": { 
                "name": "name_xx1", 
                "id": "id_xxxx1" 
            }, 
            "block_device_mapping_v2": [{ 
                "source_type": "volume", 
                "destination_type": "volume", 
                "uuid": "bd7e4f86-b004-4745-bea2-a55b1085f107", 
                "delete_on_termination": "False", 
                "boot_index": "0", 
                "volume_type": "dsware",
                "volume_size": "40"
            }], 
            "security_groups": [{ 
                "name": "name_xx5_sg" 
            }], 
            "networks": [{ 
                "uuid": "fd40e6f8-942d-4b4e-a7ae-465287b02a2c", 
                "port": "e730a11c-1a19-49cc-8797-cee2ad67af6f", 
                "fixed_ip": "10.20.30.137" 
            }], 
            "key_name": "test", 
            "user_data": "ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBpdCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5kIGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVsc2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4gQnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRoZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlvdSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vyc2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6b25zLiINCg0KLVJpY2hhcmQgQmFjaA==", 
            "availability_zone":"az1-dc1"
        } 
    }
  • 使用imageRef创建一台弹性云服务器,建议将密码在配置文件或者环境变量中密文存放,使用时解密,确保安全。
    POST https://{endpoint}/v2.1/9c53a566cb3443ab910cf0daebca90c4/servers
    
    { 
        "server": { 
            "flavorRef": "s3.xlarge.2", 
            "name": "wjvm48", 
            "metadata": { 
                "name": "name_xx1", 
                "id": "id_xxxx1" 
            }, 
            "adminPass": "$ADMIN_PASS",
            "imageRef": "6b344c54-d606-4e1a-a99e-a7d0250c3d14",
            "security_groups": [{ 
                "name": "name_xx5_sg" 
            }], 
            "networks": [{ 
                "uuid": "fd40e6f8-942d-4b4e-a7ae-465287b02a2c",
                "port": "e730a11c-1a19-49cc-8797-cee2ad67af6f",
                "fixed_ip": "10.20.30.137" 
            }], 
            "key_name": "test", 
            "user_data": "ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBpdCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5kIGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVsc2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4gQnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRoZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlvdSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vyc2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6b25zLiINCg0KLVJpY2hhcmQgQmFjaA==", 
            "availability_zone":"az1-dc1"
        } 
    }
  • 批量创建弹性云服务器,最小数量为2,最大数量为3。
    POST https://{endpoint}/v2.1/9c53a566cb3443ab910cf0daebca90c4/servers
    
    {
        "server": {
            "availability_zone":"az1.dc1",
            "name": "test",
            "imageRef": "10ff4f01-35b6-4209-8397-359cb4475fa0",
            "flavorRef": "s3.xlarge.2",
            "return_reservation_id": "true",
            "networks": [
                {
                    "uuid": "51bead38-d1a3-4d08-be20-0970c24b7cab"
                }
            ],
            "min_count": "2",
            "max_count": "3"
        }
    }

响应示例

创建弹性云服务器

{
    "server": {
        "security_groups": [
            {
                "name": "name_xx5_sg"
            }
        ],
        "OS-DCF:diskConfig": " MANUAL",
        "id": "567c1557-0eca-422c-bfce-149d6b8f1bb8",
        "links": [
            {
                "href": "http://xxx/v2/dc4059e8e7994f2498b514ca04cdaf44/servers/567c1557-0eca-422c-bfce-149d6b8f1bb8",
                "rel": "self"
            },
            {
                "href": "http://xxx/dc4059e8e7994f2498b514ca04cdaf44/servers/567c1557-0eca-422c-bfce-149d6b8f1bb8",
                "rel": "bookmark"
            }
        ],
        "adminPass": "*********"
    }
}

批量创建弹性云服务器

{
    "reservation_id": "r-3fhpjulh"
}

返回值

请参考通用请求返回值