bk-cmdb 资源池主机分配至业务空闲机模块 API 实战指南:transfer_resourcehost_to_idlemodule 全解析
bk-cmdb 资源池主机分配至业务空闲机模块 API 实战指南:transfer_resourcehost_to_idlemodule 全解析
导读
transfer_resourcehost_to_idlemodule 是蓝鲸智云配置平台(bk-cmdb)提供的一项核心主机流转能力,用于将资源池(主机池)中的主机一次性批量分配至指定业务(business)的内置"空闲机"模块。本文基于 bk-cmdb 官方 API 文档,结合仓库源码,完整讲解该接口的请求参数、请求/响应示例、权限模型以及底层调用链(hostserver → coreservice),帮助开发者、运维平台集成方快速掌握"主机从资源池进入业务"这一高频操作的正确姿势与内部机制。
一、接口概览
| 项目 | 内容 |
|---|---|
| 接口路径 | POST /api/v3/hosts/modules/resource/idle |
| 操作 ID | transfer_resourcehost_to_idlemodule |
| 中文说明 | 资源池主机分配至业务的空闲机模块 |
| 英文说明 | Transfer host from resource pool to idle module of the business |
| 所需权限 | 将主机池主机分配到业务(Allocate Hosts from Host Pool to Business Permission) |
该接口的 API 网关资源定义可在仓库的 docs/apidoc/apigw/open/bk_apigw_resources_bk-cmdb.yaml 中查到:isPublic: false(需申请权限)、allowApplyPermission: true,并默认挂载了 bk-rate-limit 限流插件(默认每 1 秒 100 个令牌)。
从源码看,该路由注册于 host_server 服务中,处理函数为 Service.AssignHostToApp:
// src/scene_server/host_server/service/service_initfunc.go L263-264
utility.AddHandler(rest.Action{Verb: http.MethodPost, Path: "/hosts/modules/resource/idle",
Handler: s.AssignHostToApp})
二、请求参数详解
请求参数表
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
bk_supplier_account |
string | 否 | 开发商账号(开发者账号) |
bk_biz_id |
int | 是 | 业务 ID,即主机要分配进入的目标业务 |
bk_host_id |
array | 是 | 主机 ID 列表,即待分配的资源池主机 |
这三个字段与源码中的请求结构体一一对应。DefaultModuleHostConfigParams 定义在 src/common/metadata/common.go:
type DefaultModuleHostConfigParams struct {
ApplicationID int64 `json:"bk_biz_id"`
HostIDs []int64 `json:"bk_host_id"`
ModuleID int64 `json:"bk_module_id"`
}
AssignHostToApp 通过 ctx.DecodeInto(&conf) 完成请求体解析(见 src/scene_server/host_server/service/module.go),任何参数缺失或类型不匹配都会直接返回请求解析错误。
请求示例
{
"bk_biz_id": 1,
"bk_host_id": [
9,
10
]
}
三、响应示例与返回参数
响应示例
{
"result": true,
"code": 0,
"message": "success",
"permission": null,
"data": null
}
响应参数表
| 名称 | 类型 | 说明 |
|---|---|---|
result |
bool | 请求是否成功。true:成功;false:失败 |
code |
int | 错误码。0 表示成功,>0 表示失败 |
message |
string | 请求失败时返回的错误信息 |
data |
object | 请求返回的数据(本接口成功时为空) |
permission |
object | 权限信息 |
需要注意的是,接口成功时 data 恒为 null(源码中 ctx.RespEntity(nil)),说明该接口不返回明细数据,主机是否分配成功需通过"查询业务下主机"类接口(如 list_biz_hosts)二次确认。当主机因业务校验、模块校验失败时,服务会返回 result: false 及对应错误码与 message。
四、调用流程与底层实现原理
4.1 一次请求的完整链路
该接口虽是 host_server 提供的 REST API,但其核心数据变更最终由 coreservice 完成。整体调用链如下:
- API 网关层:
POST /api/v3/hosts/modules/resource/idle命中 bk-apigateway 资源(见 docs/apidoc/apigw/open/bk_apigw_resources_bk-cmdb.yaml); - host_server 服务层:
Service.AssignHostToApp解析请求体,并开启分布式事务(AutoRunTxn)包裹整个分配流程; - host_server 逻辑层:
Logics.AssignHostToApp完成业务与模块校验后,组装TransferHostsCrossBusinessRequest请求; - coreservice 层:调用
CoreService().Host().TransferToAnotherBusiness真正执行主机跨业务转移,见 src/scene_server/host_server/logics/module.go。
4.2 逻辑层的执行步骤(源码级拆解)
Logics.AssignHostToApp(src/scene_server/host_server/logics/module.go)的核心执行顺序为:
- 校验目标业务存在:按
bk_biz_id查询业务信息,业务不存在直接返回CCErrCommNotFound; - 获取资源池业务 ID(
GetDefaultAppID):bk-cmdb 中资源池本身也是一个特殊业务,其下包含资源模块与资源自定义模块; - 守卫逻辑:若目标业务恰好就是资源池业务本身(
ownerAppID == conf.ApplicationID),直接返回成功,不执行任何转移; - 定位资源池模块:通过
GetModuleIDByCond查询资源池业务下default字段为资源模块(DefaultResModuleFlag)或资源自定义模块(DefaultResSelfDefinedModuleFlag)的模块 ID 集合; - 校验主机归属:调用
notExistAppModuleHost逐一核对bk_host_id列表中的主机是否真实存在于资源池模块下,存在不属于资源池的主机时,接口将报错CCErrHostModuleConfigNotMatch(错误信息会拼出违规主机的内网 IP); - 获取目标空闲机模块 ID:在目标业务下按默认字段为空闲机标志(
DefaultResModuleFlag)定位"空闲机"模块(GetResourcePoolModuleID),未找到则报CCErrHostModuleNotExist; - 组装跨业务转移请求:构建
TransferHostsCrossBusinessRequest(源业务为资源池业务、目标业务为bk_biz_id、目标模块为空闲机模块); - 执行转移:调用 coreservice 的
TransferToAnotherBusiness完成主机与模块关系变更; - 写审计日志:通过
auditlog.NewHostModuleLog记录分配前状态(WithPrevious)与分配后审计(SaveAudit)。
由此可见,接口内部做了非常严格的"主机必须来自资源池、目标业务必须存在、空闲机模块必须存在"三重校验,任何一步失败都会中止整个事务,不会出现部分成功导致的脏数据。
五、权限控制模型
5.1 操作识别
在权限解析层,该接口对应路由模式 moveResPoolHostToBizIdleModulePattern = "/api/v3/hosts/modules/resource/idle"(见 src/ac/parser/host.go),命中后权限动作(Action)为 meta.MoveResPoolHostToBizIdleModule(src/ac/parser/host.go)。
5.2 权限动作与资源模型
| 项 | 值 |
|---|---|
| Action ID(IAM) | assign_host_to_biz(ResourcePoolHostTransferToBusiness) |
| 动作中文名 | 主机池主机分配到业务 |
| 动作英文名 | Assigned Pool Hosts To Business |
| 关联动作 | 需要先具备查看资源池主机(ViewResourcePoolHost)权限 |
| 关联资源 | 主机池目录(SysHostRscPoolDirectory)+ 目标业务 |
相关定义可分别在 src/ac/iam/types.go、src/ac/iam/initial_actions.go 与 src/ac/iam/adaptor.go 中确认。
5.3 权限校验时的资源归属判断
权限解析器在构造资源实例时,会调用 getRscPoolHostModuleRelation(src/ac/parser/util.go)查询待分配主机与模块的关联关系,并逐一断言主机必须属于资源池业务:
- 若某台主机不在资源池业务下,直接返回"host does not belongs to host pool"参数错误;
- 校验通过后,以
BusinessID: opt.Business(目标业务)、Type: meta.HostInstance构造资源属性,交给 IAM 做assign_host_to_biz动作鉴权。
这意味着:即使主机 ID 合法,只要它不属于资源池,也无法通过权限层,从源头保证了资源池边界不被破坏。
六、常见错误与排障指引
结合源码错误分支,按出现频率整理如下:
| 错误场景 | 源码依据 | 提示 |
|---|---|---|
| 目标业务不存在 | CCErrCommNotFound |
确认 bk_biz_id 是否有效且已创建 |
| 主机不属于资源池模块 | CCErrHostModuleConfigNotMatch,message 会包含违规主机 IP |
先用 list_resource_pool_hosts 确认主机确实在资源池中 |
| 目标业务缺少空闲机模块 | CCErrHostModuleNotExist |
检查业务内置模块是否被误删除 |
| 目标业务等于资源池业务 | 直接返回成功 | 资源池内分配自身无实际意义,接口做了短路处理 |
| 请求体字段缺失/类型错误 | DecodeInto 解析失败 |
严格按 bk_biz_id(int)、bk_host_id(array)传参 |
| 无权限 | 返回 permission 信息 |
需要申请"主机池主机分配到业务"权限 |
七、与其他主机流转接口的区分
为避免与相近接口混淆,这里做一次横向对比:
| 接口 | 路径 | 语义 |
|---|---|---|
transfer_resourcehost_to_idlemodule |
/hosts/modules/resource/idle |
资源池 → 业务空闲机模块(本文主角) |
transfer_host_to_idlemodule |
/hosts/modules/idle |
业务内主机 → 该业务空闲机模块 |
transfer_host_to_faultmodule |
/hosts/modules/fault |
业务内主机 → 该业务故障机模块 |
transfer_host_to_recyclemodule |
/hosts/modules/recycle |
业务内主机 → 该业务回收站模块 |
transfer_host_to_resourcemodule |
/hosts/modules/resource |
业务内主机 → 资源池(上交) |
transfer_sethost_to_idle_module |
/hosts/modules/idle/set |
清空集群/模块下主机至空闲机 |
transfer_host_across_biz |
/hosts/modules/across/biz |
业务间主机转移(跨业务) |
以上路由均注册于 src/scene_server/host_server/service/service_initfunc.go。从"资源池下发主机到业务"的场景出发,transfer_resourcehost_to_idlemodule 是唯一正确的入口;transfer_host_to_idlemodule 等接口针对的是已在业务内的主机,二者方向不同,切勿混用。
八、实战建议
- 批量分配前先校验:建议先调用
list_resource_pool_hosts筛选出确属资源池的主机 ID,再调用本接口,避免整批请求因个别主机不在资源池而整体失败(服务端采用事务处理,任一主机校验失败则整批回滚); - 分配后核对:成功响应
data为null,请通过list_biz_hosts或find_host_biz_relations确认主机已挂入目标业务空闲机模块; - 权限申请:该接口非公开接口(
isPublic: false),调用方需在 API 网关侧申请"主机池主机分配到业务"权限,并确认同时具备资源池主机查看权限; - 跨版本兼容:若你的调用方同时管理"资源池主机跨业务转移"(
/hosts/resource/cross/biz),注意二者参数模型不同(后者使用resource_hosts数组结构,见 src/common/metadata/hostserver.go),本接口仅接受扁平的bk_biz_id + bk_host_id。
延伸阅读
- 归档版中文接口文档(含资源池分配接口早期定义):docs/apidoc/archived/host/host_relation.md
- API 网关资源定义:docs/apidoc/apigw/open/bk_apigw_resources_bk-cmdb.yaml
- 服务路由注册:src/scene_server/host_server/service/service_initfunc.go
- 逻辑层实现:src/scene_server/host_server/logics/module.go
- 请求参数结构体:src/common/metadata/common.go
- 权限动作定义:src/ac/iam/initial_actions.go、src/ac/iam/types.go