bk-cmdb 资源池主机分配至业务空闲机模块 API 实战指南:transfer_resourcehost_to_idlemodule 全解析

原创2026-10-12 13:52:132,211 阅读
文章标签:后端企业应用微服务

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 完成。整体调用链如下:

  1. API 网关层:POST /api/v3/hosts/modules/resource/idle 命中 bk-apigateway 资源(见 docs/apidoc/apigw/open/bk_apigw_resources_bk-cmdb.yaml);
  2. host_server 服务层:Service.AssignHostToApp 解析请求体,并开启分布式事务(AutoRunTxn)包裹整个分配流程;
  3. host_server 逻辑层:Logics.AssignHostToApp 完成业务与模块校验后,组装 TransferHostsCrossBusinessRequest 请求;
  4. coreservice 层:调用 CoreService().Host().TransferToAnotherBusiness 真正执行主机跨业务转移,见 src/scene_server/host_server/logics/module.go。

4.2 逻辑层的执行步骤(源码级拆解)

Logics.AssignHostToApp(src/scene_server/host_server/logics/module.go)的核心执行顺序为:

  1. 校验目标业务存在:按 bk_biz_id 查询业务信息,业务不存在直接返回 CCErrCommNotFound;
  2. 获取资源池业务 ID(GetDefaultAppID):bk-cmdb 中资源池本身也是一个特殊业务,其下包含资源模块与资源自定义模块;
  3. 守卫逻辑:若目标业务恰好就是资源池业务本身(ownerAppID == conf.ApplicationID),直接返回成功,不执行任何转移;
  4. 定位资源池模块:通过 GetModuleIDByCond 查询资源池业务下 default 字段为资源模块(DefaultResModuleFlag)或资源自定义模块(DefaultResSelfDefinedModuleFlag)的模块 ID 集合;
  5. 校验主机归属:调用 notExistAppModuleHost 逐一核对 bk_host_id 列表中的主机是否真实存在于资源池模块下,存在不属于资源池的主机时,接口将报错 CCErrHostModuleConfigNotMatch(错误信息会拼出违规主机的内网 IP);
  6. 获取目标空闲机模块 ID:在目标业务下按默认字段为空闲机标志(DefaultResModuleFlag)定位"空闲机"模块(GetResourcePoolModuleID),未找到则报 CCErrHostModuleNotExist;
  7. 组装跨业务转移请求:构建 TransferHostsCrossBusinessRequest(源业务为资源池业务、目标业务为 bk_biz_id、目标模块为空闲机模块);
  8. 执行转移:调用 coreservice 的 TransferToAnotherBusiness 完成主机与模块关系变更;
  9. 写审计日志:通过 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 等接口针对的是已在业务内的主机,二者方向不同,切勿混用。

八、实战建议

  1. 批量分配前先校验:建议先调用 list_resource_pool_hosts 筛选出确属资源池的主机 ID,再调用本接口,避免整批请求因个别主机不在资源池而整体失败(服务端采用事务处理,任一主机校验失败则整批回滚);
  2. 分配后核对:成功响应 data 为 null,请通过 list_biz_hosts 或 find_host_biz_relations 确认主机已挂入目标业务空闲机模块;
  3. 权限申请:该接口非公开接口(isPublic: false),调用方需在 API 网关侧申请"主机池主机分配到业务"权限,并确认同时具备资源池主机查看权限;
  4. 跨版本兼容:若你的调用方同时管理"资源池主机跨业务转移"(/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
登录后查看全文
bk-cmdb