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

创建云服务器

功能介绍

创建一台或多台云服务器。

本接口为异步接口,当前创建云服务器请求下发成功后会返回job_id,此时创建云服务器并没有立即完成,需要通过调用查询任务的执行状态查询job状态,当Job状态为 SUCCESS 时代表云服务器创建成功。

调用接口前,您需要了解API认证鉴权

调用接口前,您需要提前获取到地区和终端节点

弹性云服务器的登录鉴权方式包括两种:密钥对、密码。为安全起见,推荐使用密钥对方式。

  • 密钥对

    指使用密钥对作为弹性云服务器的鉴权方式。

    接口调用方法:使用key_name字段,指定弹性云服务器登录时使用的密钥文件。

  • 密码

    指使用设置初始密码方式作为弹性云服务器的鉴权方式,此时,您可以通过用户名密码方式登录弹性云服务器,Linux操作系统时为root用户的初始密码,Windows操作系统时为Administrator用户的初始密码。

    接口调用方法:使用adminPass字段,指定管理员账号的初始登录密码,adminPass字段的使用方法请参见表3。对于镜像已安装Cloud-init的Linux云服务器,如果需要使用密文密码,可以使用user_data字段进行密码注入,具体请参见表3

    对于安装Cloud-init镜像的Linux云服务器,若指定user_data字段,则该adminPass字段无效。

  • 镜像密码

    使用Linux操作系统私有镜像创建云服务器,支持使用私有镜像的密码。

    接口调用方法:使用镜像密码,则无需指定key_nameadminPass字段。

URI

POST /v1/{project_id}/cloudservers

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

参数

是否必选

描述

project_id

项目ID。

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

请求消息

请求参数

请求参数如表2所示。

表2 请求参数

参数

是否必选

参数类型

描述

server

Object

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

dry_run

Boolean

是否只预检此次请求,默认为false。

  • true:发送检查请求,不会创建实例。检查项包括是否填写了必需参数、请求格式等。
    • 如果检查不通过,则返回对应错误。
    • 如果检查通过,则返回202状态码。
  • false:发送正常请求,通过检查后并且执行创建云服务器请求。
表3 创建云服务器请求参数说明

参数

是否必选

参数类型

描述

imageRef

String

待创建云服务器的系统镜像,需要指定已创建镜像的ID,ID格式为通用唯一识别码(Universally Unique Identifier,简称UUID)。

flavorRef

String

待创建云服务器的系统规格的ID。

已上线的规格请参见《弹性云服务器用户指南》的“实例类型与规格”章节。

name

String

云服务器名称。

取值范围:

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

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

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=

adminPass

String

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

密码复杂度要求:
  • 长度为8-26位。
  • 密码至少必须包含大写字母、小写字母、数字和特殊字符(!@$%^-_=+[{}]:,./?~#*)中的三种。
  • 密码不能包含用户名或用户名的逆序。
  • Windows系统密码不能包含用户名或用户名的逆序,不能包含用户名中超过两个连续字符的部分。

key_name

String

如果需要使用SSH密钥方式登录云服务器,请指定已创建密钥的名称。

密钥可以通过密钥创建接口进行创建(请参见 创建和导入SSH密钥),或使用SSH密钥查询接口查询已有的密钥(请参见查询SSH密钥列表 )。

vpcid

String

待创建云服务器所属虚拟私有云(简称VPC),需要指定已创建VPC的ID,UUID格式。

VPC的ID可以从控制台或者参考《虚拟私有云接口参考》的“查询VPC”章节获取。

nics

Array of objects

待创建云服务器的网卡信息。详情请参见表4

约束:

  • 需要指定vpcid对应VPC下已创建的子网(subnet)的网络ID,UUID格式。
  • 当前单个云服务器支持最多挂载12张网卡。

publicip

Object

配置云服务器弹性公网IP信息,弹性公网IP有三种配置方式。

  • 不使用(无该字段)
  • 自动分配,需要指定新创建弹性公网IP的信息
  • 使用已有,需要指定已创建弹性公网IP的信息

详情请参见表1

count

Integer

创建云服务器数量。

约束:

  • 不传该字段时默认取值为1。
  • 租户的配额足够时,最大值为500。

root_volume

Object

云服务器对应系统盘相关配置。

详情请参见表5

data_volumes

Array of objects

云服务器对应数据盘相关配置。每一个数据结构代表一块待创建的数据盘。

约束:目前云服务器最多可挂载59块数据盘(部分规格只支持23块数据盘)

详情请参见表6

security_groups

Array of objects

云服务器对应安全组信息。

约束:当该值指定为空时,默认给云服务器绑定default安全组。

详情请参见表2

availability_zone

String

待创建云服务器所在的可用区,需要指定可用分区名称。

说明:

如果为空,会自动指定一个符合要求的可用区。

如果在专属主机上创建云服务器,需指定云服务器与专属主机所在可用区一致。

extendparam

Object

创建云服务器附加信息。

详情请参见表7

metadata

Map<String,String>

创建云服务器元数据。

可以通过元数据自定义键值对。

说明:
  • 如果元数据中包含了敏感数据,您应当采取适当的措施来保护敏感数据,比如限制访问范围、加密等。
  • 最多可注入10对键值(Key/Value)。
  • 主键(Key)只能由大写字母(A-Z)、小写字母(a-z)、数字(0-9)、中划线(-)、下划线(_)、冒号(:)、空格( )和小数点(.)组成,长度为[1-255]个字符。
  • 值(value)最大长度为255个字符。

系统预留键值对请参见表9

tags

Array of strings

弹性云服务器的标签。

标签的格式为“key.value”。其中,key的长度不超过36个字符,value的长度不超过43个字符。

标签命名时,需满足如下要求:

说明:
  • 创建弹性云服务器时,一台弹性云服务器最多可以添加10个标签。

description

String

云服务器描述信息,默认为空字符串。

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

参数

是否必选

参数类型

描述

subnet_id

String

待创建云服务器所在的子网信息。

需要指定vpcid对应VPC下已创建的子网(subnet)的网络ID,UUID格式。

ip_address

String

待创建云服务器网卡的IP地址,IPv4格式。

约束:
  • 不填或空字符串,默认在子网(subnet)中自动分配一个未使用的IP作网卡的IP地址。
  • 若指定IP地址,该IP地址必须在子网(subnet)对应的网段内,且未被使用。

ipv6_enable

Boolean

是否支持ipv6。取值为true时,表示此网卡支持ipv6。

ipv6_bandwidth

Object

绑定的共享带宽信息,详情请参见ipv6_bandwidth字段数据结构说明

表5 root_volume字段数据结构说明

参数

是否必选

参数类型

描述

volumetype

String

云服务器系统盘对应的磁盘类型,需要与系统所提供的磁盘类型相匹配。

目前支持“SSD”,“SAS”。
  • “SSD”为超高IO云硬盘
  • “SAS”为高IO云硬盘

当指定的云硬盘类型在availability_zone内不存在时,则创建云硬盘失败。

说明:
  • 了解不同磁盘类型的详细信息,请参见“云硬盘用户指南 > 磁盘类型及性能介绍”。

size

Integer

系统盘大小,容量单位为GB,输入大小范围为[1,1024]。

约束:

  • 系统盘大小取值应不小于镜像支持的系统盘的最小值(镜像的min_disk属性)。
  • 若该参数没有指定或者指定为0时,系统盘大小默认取值为镜像中系统盘的最小值(镜像的min_disk属性)。
说明:

镜像系统盘的最小值(镜像的min_disk属性)可在控制台上单击镜像详情查看。或通过调用“查询镜像详情(OpenStack原生)”API获取,详细操作请参考《镜像服务API参考》中“查询镜像详情(OpenStack原生)”章节。

extendparam

Object

磁盘的产品信息。

详情请参见创建磁盘的extendparam字段数据结构说明

hw:passthrough

Boolean

设置云硬盘的设备类型:
  • 参数指定为false,创建VBD类型磁盘。
  • 参数指定为true,创建SCSI类型磁盘。
  • 参数未指定或者指定非Boolean类型的字符,默认创建VBD类型磁盘。

metadata

Object

创建云硬盘的metadata信息,metadata中的key和value长度不大于255个字节。

仅在创建加密盘时使用metadata字段。

详情请参见创建磁盘的metadata字段数据结构说明

表6 data_volumes字段数据结构说明

参数

是否必选

参数类型

描述

volumetype

String

云服务器数据盘对应的磁盘类型,需要与系统所提供的磁盘类型相匹配。

目前支持“SSD”,“SAS”。
  • “SSD”为超高IO云硬盘
  • “SAS”为高IO云硬盘

当指定的云硬盘类型在availability_zone内不存在时,则创建云硬盘失败。

说明:
  • 了解不同磁盘类型的详细信息,请参见“云硬盘用户指南 > 磁盘类型及性能介绍”。

size

Integer

数据盘大小,容量单位为GB,输入大小范围为[10,32768]。

如果使用数据盘镜像创建数据盘时,size取值不能小于创建数据盘镜像的源数据盘的大小。

shareable

Boolean

是否为共享磁盘。true为共享盘,false为普通云硬盘。

说明:

该字段已废弃,请使用multiattach。

multiattach

Boolean

创建共享磁盘的信息。

  • true:创建的磁盘为共享盘。
  • false:创建的磁盘为普通云硬盘。
说明:

shareable当前为废弃字段,如果确实需要同时使用shareable字段和multiattach字段,此时,请确保两个字段的参数值相同。当不指定该字段时,系统默认创建普通云硬盘。

hw:passthrough

Boolean

设置云硬盘的设备类型:
  • 参数指定为false,创建VBD类型磁盘。
  • 参数指定为true,创建SCSI类型磁盘。
  • 参数未指定或者指定非Boolean类型的字符,默认创建VBD类型磁盘。

extendparam

Object

磁盘的产品信息。

详情请参见表6

data_image_id

String

数据镜像的ID,UUID格式。

如果使用数据盘镜像创建数据盘,则data_image_id为必选参数,且不支持使用metadata。

metadata

Object

创建云硬盘的metadata信息,metadata中的key和value长度不大于255个字节。

仅在创建加密盘时使用metadata字段。

如果使用数据盘镜像创建数据盘,不支持使用metadata。

详情请参见创建磁盘的metadata字段数据结构说明

响应消息

参数

参数类型

描述

job_id

String

提交任务成功后返回的任务ID,用户可以使用该ID对任务执行情况进行查询。如何根据job_id来查询Job的执行状态,请参考5.8 查询Job状态。

异常响应请参考响应(任务类),异常响应要素说明。

请求示例

  • 创建一台按需计费云服务器,操作系统为CentOS 7.6 64bit,4U8G,磁盘类型为“SSD”,绑定10M的按带宽计费的弹性公网IP,采用密钥方式登录鉴权。
    POST https://{endpoint}/v1/{project_id}/cloudservers
    
    {
        "server": {
            "availability_zone":"az1-dc1",
            "name": "newserver", 
            "imageRef": "67f433d8-ed0e-4321-a8a2-a71838539e09", 
            "root_volume": {
                "volumetype": "SSD"
            }, 
            "data_volumes": [ 
                {
                    "volumetype": "SSD", 
                    "size": 100,
                    "multiattach": true,
                    "hw:passthrough": true
                }
            ], 
            "flavorRef": "s3.xlarge.2", 
            "vpcid": "0dae26c9-9a70-4392-93f3-87d53115d171", 
            "security_groups": [
                {
                    "id": "507ca48f-814c-4293-8706-300564d54620"
                }
            ], 
            "nics": [
                {
                    "subnet_id": "157ee789-03ea-45b1-a698-76c92660dd83"
                }
            ], 
            "publicip": {
                "eip": {
                    "iptype": "5_bgp",
                    "bandwidth": {
                        "size": 10, 
                        "sharetype": "PER"
                    }
                }
            }, 
            "key_name": "sshkey-123", 
            "count": 1, 
            "server_tags": [
                {
                    "key": "key1",
                    "value": "value1"
                }
            ],
            "metadata": {
                   "op_svc_userid": "8ea65f4099ba412883e2a0da72b96873",
                   "agency_name": "test"
            }
        }
    }
  • 使用系统盘加密且自带两个数据盘的整机镜像创建云服务器,对于恢复的两块数据盘,一块按默认属性恢复,另一块更改磁盘属性为“SSD,100GB”;再为创建的云服务器新挂载一个属性为“SSD,50GB”的数据盘。
    POST https://{endpoint}/v1/{project_id}/cloudservers
    
    {
        "server": {
            "availability_zone":"az1-dc1", 
            "name": "wholeImageServer", 
            "imageRef": "ff49b1f1-3e3e-4913-89c6-a026041661e8", 
            "root_volume": {
                "volumetype": "SSD",
                "metadata": {
                     "__system__encrypted": "1",
                     "__system__cmkid": "83cdb52d-9ebf-4469-9cfa-e7b5b80da846"
                 }
            }, 
            "data_volumes": [
                {
                    "volumetype": "SSD", 
                    "size": 100,
                    "extendparam":{
                        "snapshotId": "ef020653-9742-4d24-8672-10af42c9702b"
                    }
                }, 
                {
                    "volumetype": "SSD", 
                    "size": 50
                }
            ], 
            "flavorRef": "s2.large.2", 
            "vpcid": "0dae26c9-9a70-4392-93f3-87d53115d171", 
            "security_groups": [
                {
                    "id": "507ca48f-814c-4293-8706-300564d54620"
                }
            ], 
            "nics": [
                {
                    "subnet_id": "157ee789-03ea-45b1-a698-76c92660dd83"
                }
            ],
            "key_name": "sshkey-123"
        }
    }
  • 发送预校验请求,检查创建弹性云服务器的请求消息是否填写了必选参数,请求格式是否正确。
    POST https://{endpoint}/v1/{project_id}/cloudservers
    
    {
        "dry_run": true,
        "server": {
            "availability_zone":"az1-dc1",
            "name": "newserver", 
            "imageRef": "1189efbf-d48b-46ad-a823-94b942e2a000", 
            "root_volume": {
                "volumetype": "SSD"
            }, 
            "data_volumes": [
                {                 
                     "volumetype": "SSD",                  
                     "size": 100,                 
                     "multiattach": true,                 
                     "hw:passthrough": true             
                }
            ], 
            "flavorRef": "s3.xlarge.2", 
            "vpcid": "0dae26c9-9a70-4392-93f3-87d53115d171", 
            "security_groups": [
                {
                    "id": "507ca48f-814c-4293-8706-300564d54620"
                }
            ], 
            "nics": [
                {
                    "subnet_id": "157ee789-03ea-45b1-a698-76c92660dd83"
                }
            ], 
            "key_name": "sshkey-123", 
            "count": 1
        }
    }

响应示例

{
    "job_id": "93c82933d6b7827d3016b8771f2070873"
}

{
    "error": {
        "code": "request body is illegal.", 
        "message": "Ecs.0005"
    }
}

{
    "error": {
        "message": "privateIp [%s] is not in this subnet [%s]",
        "code": "Ecs.0005",
        "details": [
            {
                "code": "Ecs.0039"
            }
        ]
    }
}

返回值

请参考通用请求返回值

错误码

请参考错误码