bk-cmdb API 详解:transfer_resourcehost_to_idlemodule —— 资源池主机分配至业务空闲机模块
bk-cmdb API 详解:transfer_resourcehost_to_idlemodule —— 资源池主机分配至业务空闲机模块
本文以 bk-cmdb(蓝鲸智云配置平台)开放接口 transfer_resourcehost_to_idlemodule 为核心,完整讲解该接口的请求参数、响应结构、鉴权模型,并结合 host_server 的源码实现,深入剖析"资源池主机 → 业务空闲机模块"这一跨业务拓扑变更背后的完整调用链:路由注册、事务封装、前置校验、跨业务转移与审计日志落盘。读完后,你可以直接调用该接口完成主机分配,也能在排查 result: false 类失败时快速定位到具体校验分支。
接口概览
该接口用于将位于资源池(默认业务下的资源目录)中的主机,批量分配到指定业务的空闲机模块(idle module),是蓝鲸 CMDB 主机生命周期管理中"采购/纳管 → 资源池 → 业务"流转的关键一步。
| 项目 | 说明 |
|---|---|
| API 名称 | transfer_resourcehost_to_idlemodule |
| 请求路径 | POST /api/v3/hosts/modules/resource/idle |
| 功能 | 分配资源池主机到业务的空闲机模块 |
| 所需权限 | 资源池主机分配到业务权限(Allocate Hosts from Host Pool to Business) |
在 API 网关侧的资源定义见 bk_apigw_resources_bk-cmdb.yaml,其中可以看到该资源:
isPublic: false、allowApplyPermission: true,即非公开资源,调用方需在蓝鲸开放平台申请权限后才能调用;- 后端以 HTTP 方式转发到同样的路径
/api/v3/hosts/modules/resource/idle; - 配置了
bk-rate-limit插件,默认档位__default为每 1 秒 100 个令牌(tokens: 100, period: 1),用于限流保护。
请求参数
公共参数
与其他 esb-cc 接口一致,请求需携带蓝鲸开放平台通用参数(common_args_desc 定义的一组公共字段),请求示例中体现如下:
bk_app_code:调用方应用 ID(App Code)bk_app_secret:应用密钥bk_username:操作人账号bk_token:蓝鲸 SSO 访问令牌
接口参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
bk_supplier_account |
string | 否 | 开发机账号 |
bk_biz_id |
int | 是 | 目标业务 ID |
bk_host_id |
array | 是 | 待分配的主机 ID 数组(资源池中的主机) |
这些字段在 host_server 的服务端解码到了 DefaultModuleHostConfigParams 结构体:
type DefaultModuleHostConfigParams struct {
ApplicationID int64 `json:"bk_biz_id"`
HostIDs []int64 `json:"bk_host_id"`
ModuleID int64 `json:"bk_module_id"`
}
从源码结构看,该结构体被多个"默认模块转移"接口共用(bk_module_id 在本接口中不需要传入,目标模块固定为业务空闲机模块,由逻辑层自动解析)。
请求参数示例
{
"bk_app_code": "esb_test",
"bk_app_secret": "xxx",
"bk_username": "xxx",
"bk_token": "xxx",
"bk_supplier_account": "123456789",
"bk_biz_id": 1,
"bk_host_id": [
9,
10
]
}
响应参数
响应示例
{
"result": true,
"code": 0,
"message": "success",
"permission": null,
"request_id": "e43da4ef221746868dc4c837d36f3807",
"data": null
}
响应字段说明
| 字段 | 类型 | 说明 |
|---|---|---|
result |
bool | 请求成功与否。true: 成功;false: 失败 |
code |
int | 错误编码。0 表示 success,>0 表示失败错误 |
message |
string | 请求失败返回的错误信息 |
data |
object | 请求返回的数据(本接口成功时为 null) |
permission |
object | 权限信息(鉴权失败时给出) |
request_id |
string | 请求链路 ID,排查日志的关键线索 |
服务端实现链路
路由注册与 HTTP 处理
该接口的路由在 host_server 的 service_initfunc.go 中注册:
utility.AddHandler(rest.Action{Verb: http.MethodPost, Path: "/hosts/modules/resource/idle",
Handler: s.AssignHostToApp})
对应的 HTTP 处理器 AssignHostToApp 做了三件事:
- 用
ctx.DecodeInto将请求体解码为metadata.DefaultModuleHostConfigParams,解码失败直接返回参数错误; - 通过
CoreAPI.CoreService().Txn().AutoRunTxn把核心逻辑包在一个存储事务中执行,保证跨业务转移(删旧关系 + 建新关系)的原子性; - 事务失败时调用
ctx.RespEntityWithError(exceptionArr, txnErr)返回业务错误码与异常主机列表,成功则ctx.RespEntity(nil),即data: null。
同文件中还可以看到一组"默认模块"姊妹接口,它们复用同一套参数结构:
POST /hosts/modules/idle→MoveHost2IdleModule(业务内主机上交空闲机)POST /hosts/modules/fault→MoveHost2FaultModule(上交故障机)POST /hosts/modules/recycle→MoveHost2RecycleModule(上交回收站)POST /hosts/modules/resource→MoveHostToResourcePool(业务主机移回资源池,本接口的反向操作)
核心业务逻辑:校验与跨业务转移
真正的业务规则在 Logics.AssignHostToApp,执行顺序为:
- 校验目标业务存在:按
bk_biz_id查询业务详情(字段bk_biz_id,bk_app_name),查不到时返回CCErrCommNotFound。 - 确定资源池宿主业务:通过
GetDefaultAppID获取资源池所属的默认业务 ID(ownerAppID)。若目标业务就是资源池本身(ownerAppID == conf.ApplicationID),则直接返回成功,不做任何转移。 - 校验主机确实在资源池资源目录中:在资源池业务下查询
bk_is_default属于资源池标记(DefaultResModuleFlag)或资源自定义模块(DefaultResSelfDefinedModuleFlag)的模块,再用notExistAppModuleHost核对传入主机是否都挂在这些模块下。若有主机不满足,接口会把这些主机的bk_host_id转换为内网 IP(convertHostIDToHostIP 注释明确该容错方法"出现任何错误都会被忽略")并返回CCErrHostModuleConfigNotMatch,错误信息中附带违规主机的 IP 列表,便于运维快速定位。 - 解析目标空闲机模块:在目标业务下按
bk_is_default = 资源池标记条件查询空闲机模块 ID(GetResourcePoolModuleID),模块不存在时返回CCErrHostModuleNotExist(携带模块名)。 - 构造跨业务转移请求并落库:
assignParams := &metadata.TransferHostsCrossBusinessRequest{
SrcApplicationIDs: []int64{ownerAppID},
DstApplicationID: conf.ApplicationID,
HostIDArr: conf.HostIDs,
DstModuleIDArr: []int64{moduleID},
}
随后调用 CoreAPI.CoreService().Host().TransferToAnotherBusiness 完成"从资源池业务删除主机-模块关系、在目标业务空闲机模块下建立关系"的跨业务操作;失败时返回 CCErrHostEditRelationPoolFail,核心服务返回 result: false 时透传 result.Code / ErrMsg。
- 审计日志:转移前后通过
auditlog.NewHostModuleLog(...).WithPrevious记录主机模块关系的前置快照,成功后audit.SaveAudit落库,使该操作可审计、可回溯;审计服务初始化失败返回CCErrCommResourceInitFailed。
也就是说,接口文档中"data: null、result: true"的成功语义,对应源码中的"事务内 TransferToAnotherBusiness 成功且 result.Result 为真,审计保存成功"。
权限解析:资源池主机分配到业务
在 IAM 权限解析器中,host.go 将该路径定义为专门的模式常量:
moveResPoolHostToBizIdleModulePattern = "/api/v3/hosts/modules/resource/idle"
当请求命中该路径且为 POST 时(host.go),解析器会解码请求体中的 hostPool 参数,并调用 getRscPoolHostModuleRelation(opt.HostID) 反查这批主机在资源池中挂接的模块关系,再据此构造 meta.ResourceAttribute 参与鉴权。这与文档中"Permission: Allocate Hosts from Host Pool to Business Permission"的描述一致:权限点与主机在资源池中的实际归属绑定,而不是仅按 bk_biz_id 判断。
内部 SDK 调用示例
除通过 ESB/开放平台调用外,仓库内部也提供了 Go 客户端封装。hostserver.AssignHostToApp 即该接口的编程式客户端:
func (hs *hostServer) AssignHostToApp(ctx context.Context, h http.Header,
dat *metadata.DefaultModuleHostConfigParams) (resp *metadata.Response, err error) {
resp = new(metadata.Response)
subPath := "/hosts/modules/resource/idle"
err = hs.client.Post().
WithContext(ctx).
Body(dat).
SubResourcef(subPath).
WithHeaders(h).
Do().
Into(resp)
return
}
在集群内部组件(如蓝鲸框架、其他中心)需要程序化分配主机时,可以直接复用 DefaultModuleHostConfigParams 结构与该客户端方法,而无需手工拼接 HTTP 请求。
常见失败场景对照
结合源码中的错误分支,调用失败时可按如下表快速定位:
| 现象 | 源码错误码 | 含义 |
|---|---|---|
| 返回"not found"类错误 | CCErrCommNotFound |
bk_biz_id 对应的业务不存在 |
| 错误信息中带一串内网 IP | CCErrHostModuleConfigNotMatch |
部分主机不在资源池的资源目录模块下(如已被分配或不在资源池业务中) |
| 提示某模块不存在 | CCErrHostModuleNotExist |
目标业务下未初始化空闲机模块 |
| 转移关系失败 | CCErrHostEditRelationPoolFail |
核心服务执行跨业务关系变更失败 |
result: false 且带核心服务错误码 |
透传 result.Code / ErrMsg |
核心服务(拓扑/存储层)拒绝,需按 request_id 查日志 |
关联接口
该接口与一组主机-模块转移接口共同构成主机流转闭环,均注册在 service_initfunc.go:
| 路径 | 处理器 | 用途 |
|---|---|---|
POST /hosts/modules |
TransferHostModule |
业务内主机转移到指定模块 |
POST /hosts/modules/resource/idle |
AssignHostToApp |
资源池主机分配至业务空闲机模块(本文接口) |
POST /hosts/modules/resource |
MoveHostToResourcePool |
业务主机移回资源池 |
POST /hosts/modules/idle / fault / recycle |
MoveHost2*Module |
业务内主机上交到默认模块 |
POST /hosts/modules/across/biz |
TransferHostAcrossBusiness |
业务间转移主机 |
POST /hosts/resource/cross/biz |
TransferResourceHostsAcrossBusiness |
资源池主机在多个业务间转移 |
POST /host/transfer/resource/directory |
TransferHostResourceDirectory |
主机在资源池目录之间转移 |
历史接口文档(含入参出参说明)参见 host_relation.md。
小结
transfer_resourcehost_to_idlemodule 是 bk-cmdb 中资源池主机进入业务体系的唯一入口接口:参数上仅需 bk_biz_id 与 bk_host_id 两个核心字段;实现上则串联了业务存在性校验、资源池归属校验、目标空闲机模块解析、跨业务拓扑转移(事务保证原子性)与模块关系审计日志五个环节。理解这条调用链后,无论是编写自动化纳管脚本,还是排查"主机分配失败"类工单,都能直接在 host_server 的 service/logics 两层代码中定位到具体失败点。