文档首页/裸金属服务器 BMS/API参考/API/裸金属服务器状态管理/切换裸金属服务器的操作系统 - ChangeBaremetalServerOs
更新时间：2026-02-26 GMT+08:00
查看PDF
分享

切换裸金属服务器的操作系统 - ChangeBaremetalServerOs

功能介绍

切换裸金属服务器的操作系统。切换操作系统支持密码或者密钥注入。

切换操作系统属于异步API，接口调用成功只表示请求下发成功，任务执行结果请通过查询Job状态 - ShowJobInfosAPI获取。

约束

  • 关机状态或者切换操作系统失败的裸金属服务器，才能执行切换操作。
  • 使用私有镜像创建的裸金属服务器，请确保已经安装了Cloud-init（Linux镜像）或Cloudbase-init（Windows镜像）。如使用未安装Cloud-init或Cloudbase-init的镜像，该接口不能注入密钥或密码。公共镜像默认已安装Cloud-init或Cloudbase-init。
  • 执行切换操作系统任务时，请勿并行执行其他操作，否则可能会引起切换操作系统失败。
  • 目前Windows镜像不支持注入密码，Linux镜像的user_data为加密后的密码。

调试

您可以在API Explorer中调试该接口。

授权信息

账号具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备调用API所需的权限。

  • 如果使用角色与策略授权，具体权限要求请参见权限和授权项。
  • 如果使用身份策略授权，需具备如下身份策略权限。

    授权项

    访问级别

    资源类型（*为必须）

    条件键

    别名

    依赖的授权项

    bms:servers:changeOS

    write

    instance*

    • g:ResourceTag/<tag-key>
    • g:EnterpriseProjectId
    • bms:KmsKeyId
    • evs:Encrypted
    • bms:ImageId
    • bms:SSHKeyPairName

    -

    -

URI

POST /v1/{project_id}/baremetalservers/{server_id}/changeos

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

参数

是否必选

描述

X-Auth-Token

是

用户Token。通过调用IAM服务获取用户Token接口获取(响应消息头中X-Subject-Token的值)

project_id

是

项目ID。

获取方式请参见获取项目ID。

server_id

是

裸金属服务器ID。

可以从裸金属服务器控制台查询，或者通过调用查询裸金属服务器列表（废弃）获取。

请求参数

参数

是否必选

参数类型

描述

os-change

是

Object

标记为切换裸金属服务器OS操作。详情请参见表2。

表2 os-change字段数据结构说明

参数

是否必选

参数类型

描述

adminpass

否

String

裸金属服务器管理员账号的初始登录密码。

其中，Linux管理员账户为root，Windows管理员账户为Administrator。

建议密码复杂度如下：

  • 长度为8-26位。
  • 密码至少必须包含大写字母、小写字母、数字和特殊字符（!@$%^-_=+[{}]:,./?）中的三种。
  • 密码不能包含用户名或用户名的逆序。
说明：
  • 对于Windows裸金属服务器，不能包含用户名中超过两个连续字符的部分。
  • 对于Linux裸金属服务器也可使用user_data字段实现密码注入，此时adminpass字段无效。
  • adminpass和keyname不能同时有值。
  • adminpass和keyname如果同时为空，此时，metadata中的user_data属性必须有值。

keyname

否

String

密钥名称。

密钥可以通过创建和导入SSH密钥（OpenStack原生）API创建，或者使用查询SSH密钥列表（OpenStack原生）API查询已有的密钥。

userid

否

String

用户ID（登录管理控制台，进入我的凭证，即可看到“用户ID”）。

imageid

是

String

镜像ID。

镜像ID可以从镜像服务控制台获取，或者参考《镜像服务API参考》的“查询镜像列表”章节查询。

在使用“查询镜像列表”API查询时，可以添加过滤字段“?virtual_env_type=Ironic”来筛选裸金属服务器镜像。

metadata

否

Object

切换裸金属服务器的元数据。详情请参见表3。

表3 metadata字段数据结构说明

参数

是否必选

参数类型

描述

user_data

否

String

切换裸金属服务器过程中待注入的Linux镜像root密码，用户自定义初始化密码。

注：修改密码脚本需经base64编码。

建议密码复杂度如下：

  • 长度为8-26位。
  • 密码至少必须包含大写字母（A-Z）、小写字母（a-z）、数字（0-9）和特殊字符（!@$%^-_=+[{}]:,./?）中的三种。

示例：

  • 使用明文密码（存在安全风险），以密码cloud.1234为例： 
    1
2
    #!/bin/bash 
echo 'root:Cloud.1234' | chpasswd ;
  • 使用密码： 
    1
2
    #!/bin/bash 
echo 'root:$6$V6azyeLwcD3CHlpY$BN3VVq18fmCkj66B4zdHLWevqcxlig/GpOkLcOhab9smJoLKYm/Tf9Hcwa6DpiPDhdHfGEAPajFmLZa0YDd910' | chpasswd -e
  • 此脚本需经base64编码方式编码。

其中，$6$V6azyeLwcD3CHlpY$BN3VVq18fmCkj66B4zdHLWevqcxlig为密文密码，生成方法如下：

  1. 生成加密盐值 
    1
2
    [root@test linux]# python -c "import crypt, getpass, pwd;print crypt.mksalt()" 
$6$V6azyeLwcD3CHlpY
  2. 根据盐值生成密文密码 
    1
2
    [root@test linux]# python -c "import crypt, getpass, pwd;print crypt.crypt('Cloud.1234','\$6\$V6azyeLwcD3CHlpY')" 
 $6$V6azyeLwcD3CHlpY$BN3VVq18fmCkj66B4zdHLWevqcxlig/GpOkLcOhab9smJoLKYm/Tf9Hcwa6DpiPDhdHfGEAPajFmLZa0YDd910
  3. 密文生成之后，修改密码脚本需经base64编码方式编码。

__system__encrypted

否

String

metadata中表示加密功能的字段，0代表不加密，1代表加密。

该字段不存在时，系统盘默认为不加密。

该字段值为0时，__system__cmkid不生效。

__system__cmkid

否

String

用户主密钥ID，是metadata中表示加密功能的字段，与__system__encrypted配合使用。

说明：

请参考查询密钥列表，通过HTTPS请求获取密钥ID。

__system__encryption_algorithm

否

String

创建加密卷支持指定加密算法。

取值范围：

  • AES_256：通用的高级加密算法。
  • SM4：国密算法。

说明：

  • __system__encrypted、__system__cmkid均有效才支持设置。
  • 如果不设置，默认值为AES_256。

请求示例

1
POST https://{BMS Endpoint}/v1/bbf1946d374b44a0a2a95533562ba954/baremetalservers/cf2a8b97-b5c6-47ef-9714-eb27adf26e5b/changeos

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
    "os-change": {
        "keyname": "$key_name", 
        "imageid": "04dc740a-5820-4ab6-9d01-8cd3a6577296",
        "userid": "7e25b1da389f4697a79df3a0e5bd494e", 
        "metadata": {
              "user_data":  "$USER_DATA"
        }
    }
}

响应参数

  • 正常响应要素
表4 正常响应要素说明

名称

参数类型

说明

jobId

String

提交任务成功后返回的任务ID，用户可以使用该ID对任务执行情况进行查询。

如何根据job_id来查询Job的执行状态，请参考查询Job状态 - ShowJobInfos。

  • 异常响应要素
表5 异常响应要素说明

名称

参数类型

说明

error

字典数据结构

提交任务异常时返回的异常信息，详情请参见表6。

表6 error数据结构

名称

参数类型

说明

message

String

任务异常错误信息描述。

code

String

任务异常错误信息编码。

响应示例

  • 正常响应
{ 
    "jobId": "9288ec8d769dbc9b01769dc8f261002f"
}

返回值

正常返回值：

返回值

说明

200

服务器已成功处理了请求。

其他返回值请参考状态码。

错误码

请参考错误码。

相关文档