蓝鲸配置平台 bk-cmdb 集群模板同步接口 sync_set_template_to_set 实战指南
蓝鲸配置平台 bk-cmdb 集群模板同步接口 sync_set_template_to_set 实战指南
集群模板(Set Template)是蓝鲸配置平台(bk-cmdb)中用于批量规范化集群与模块结构的关键机制:通过先定义"模板",再将其批量同步到多个集群实例,即可在业务内快速复制一致的拓扑结构。本文以 sync_set_template_to_set 接口为核心,完整讲解其请求参数、返回结构、ESB 网关映射方式,并结合 topo_server 源码深入剖析"模板—集群差异计算、模块增删改、异步任务执行"的底层实现链路,帮助开发者正确调用该接口并理解其内部工作原理。
接口概述:将集群模板批量同步到指定集群
sync_set_template_to_set 的语义是:根据业务 ID、集群模板 ID 以及待同步集群 ID 列表,将指定业务下的集群模板同步到这些集群上。调用成功后,目标集群的集群属性、以及集群下挂载的模块(Module)会按照集群模板及其关联的服务模板(Service Template)重新对齐——缺失的模块被创建、多余的模块被删除、名称不一致的模块被更新。
- 接口形态:ESB 网关接口,通过蓝鲸 API Gateway 转发到 bk-cmdb 内部接口;
- 调用权限:集群编辑权限;
- 适用场景:当调整了集群模板(如新增、删除或重命名某个服务模板)后,需要把模板的最新结构批量下发到一批已经存在的集群上;
- 注意事项:本接口的同步操作会改变目标集群的模块结构,属于变更型(operate)操作,建议先在测试业务上验证。
该接口与"模板实例化集群"是配套的两种路径:实例化集群时以集群模板为基础新建集群,而本接口则是把已有集群向模板"对齐"。两者在 topo_server 内部共享同一套差异计算与同步执行逻辑。
请求参数详解
接口请求体包含三类公共鉴权参数(bk_app_code、bk_app_secret、bk_username/bk_token)与三个业务参数,业务参数定义如下:
| 字段 | 类型 | 必选 | 描述 |
|---|---|---|---|
| bk_biz_id | int | 是 | 业务 ID |
| set_template_id | int | 是 | 集群模板 ID |
| bk_set_ids | array | 是 | 待同步集群 ID 列表 |
三个参数均必填,缺一不可:
bk_biz_id:目标业务。集群模板与集群均属于同一业务,跨业务同步不被允许;set_template_id:作为同步基准的集群模板。模板内部维护了模板属性(cc_SetTemplateAttr)及其关联的服务模板列表(cc_SetServiceTemplateRelation),是本次同步的"期望态"来源;bk_set_ids:本次要执行同步的集群实例 ID 数组。该列表可以为空数组以外的任意长度,但空数组会导致请求直接失败——源码中len(option.SetIDs) == 0时会返回参数错误(CCErrCommParamsNeedSet,见 set_template.go)。
从代码结构看,参数在服务端被解析为结构体 SyncSetTplToInstOption,其中仅包含 bk_set_ids 一个字段,而 bk_biz_id 与 set_template_id 则从 URL 路径参数中解析(见 set_template_request.go)。
请求参数示例
{
"bk_app_code": "esb_test",
"bk_app_secret": "xxx",
"bk_username": "xxx",
"bk_token": "xxx",
"bk_biz_id": 20,
"set_template_id": 6,
"bk_set_ids": [46]
}
对应含义:将业务 20 下的集群模板 6,同步到集群 46 上。示例中仅同步一个集群,实际使用时 bk_set_ids 可传入多个集群 ID。
使用 curl 直接调用内部接口
若不经过 ESB,也可以直接调用 bk-cmdb 的内部 HTTP 接口(需具备网关或内网访问条件):
curl -X POST \
-H 'Content-Type: application/json' \
-H 'X-Bk-Username: admin' \
-d '{"bk_set_ids":[46]}' \
'http://<cmdb-server>/api/v3/updatemany/topo/set_template/6/bk_biz_id/20/sync_to_instances'
该内部路由与 ESB 接口的映射关系记录在 cc.yaml:ESB 地址 /v2/cc/sync_set_template_to_set/(POST)转发至内部地址 /api/v3/updatemany/topo/set_template/{set_template_id}/bk_biz_id/{bk_biz_id}/sync_to_instances(POST)。路由注册代码位于 service_settemplate_initfunc.go。
返回结果与字段说明
返回结果示例
{
"result": true,
"code": 0,
"message": "success",
"permission": null,
"request_id": "e43da4ef221746868dc4c837d36f3807",
"data": null
}
返回字段说明
| 字段 | 类型 | 描述 |
|---|---|---|
| result | bool | 请求是否成功。true:成功;false:失败 |
| code | int | 错误编码。0 表示 success,>0 表示失败错误码 |
| message | string | 请求失败时返回的错误信息 |
| permission | object | 权限信息 |
| request_id | string | 请求链 ID,用于全链路日志追踪 |
| data | object | 请求返回的数据,本接口同步任务异步执行,成功时返回 null |
需要特别说明的是:该接口的 data 为 null 不代表同步已完成。从实现看,接口只负责"派发同步任务",任务本身由 task_server 异步执行。若需确认同步结果,应配合使用同步状态与历史查询接口(见下文"配套接口")。
内部实现链路:从请求到异步任务派发
1. 入口 Handler 与事务包裹
内部接口 SyncSetTplToInst 是 topo_server 服务层入口,流程如下(见 set_template.go):
- 从 URL 路径解析
bk_biz_id、set_template_id,解析失败返回参数错误; - 将请求体解码到
SyncSetTplToInstOption,并校验bk_set_ids非空; - 在**数据库事务(AutoRunTxn)**内调用业务逻辑层
SetTemplateOperation().SyncSetTplToInst,事务失败则整体回滚; - 事务成功即返回空 data 响应。
2. 业务逻辑:并发 Diff + 任务派发
逻辑层实现位于 settemplate.go,是理解本接口工作原理的关键:
- 拉取模板关联的服务模板:调用
ListSetTplRelatedSvcTpl获取集群模板下挂载的全部服务模板,作为期望态基准; - 并发计算差异:对
bk_set_ids中的每个集群,启动 goroutine 并发执行DiffSetTplWithInst(差异计算),通过带缓冲的 channel(容量 10)做并发限流,并收集每个集群的差异结果SetDiff; - 逐集群派发同步任务:对每个集群,将其差异中的每个模块差异(
ModuleDiffs)封装为SyncModuleTask,调用DispatchTask4ModuleSync通过 task_server 的Task().Create创建异步同步任务(任务类型SyncSetTaskFlag)。
3. 差异计算:Diff 规则
DiffSetTplWithInst(settemplate.go)会同时对比集群属性和模块结构;模块层面的对比由 DiffServiceTemplateWithModules(settemplate.go)完成,产生四类差异类型:
| DiffType | 触发条件 | 同步动作 |
|---|---|---|
| add | 服务模板存在于模板中,但集群下无对应模块 | 新建模块 |
| remove | 集群下存在模块,但其关联的服务模板不在模板中 | 删除模块 |
| changed | 模块关联的服务模板在模板中,但模块名称与模板名称不一致 | 更新模块名称 |
| unchanged | 模块名称与模板一致 | 无操作 |
同步动作的实际执行者 DoModuleSyncTask(见 worker.go)按 DiffType 分发:remove 删除模块,add 依据服务模板的名称、服务分类 ID 等信息新建模块,changed 仅更新模块名,unchanged 直接返回。同时每个集群在模块同步前都会先执行集群属性同步(syncSetAttributes),把模板属性(cc_SetTemplateAttr)中的值下发到集群实例上。
4. 数据模型支撑
与集群模板同步相关的核心存储表记录在 docs/db/set_template.md:
cc_SetTemplate:集群模板主表(模板 ID、名称、所属业务、创建/更新信息);cc_SetTemplateAttr:集群模板的属性配置表(模板 ID → 属性 ID → 属性值),是集群属性同步的数据源;cc_SetServiceTemplateRelation:集群模板与服务模板的关联表,决定了集群下应挂载哪些模块。
同步状态与配套接口
一次模板同步派发后,建议通过以下配套接口跟踪结果(均在 service_settemplate_initfunc.go 注册):
- 查询单集群同步详情:
POST /findmany/topo/set_template/{set_template_id}/bk_biz_id/{bk_biz_id}/instances_sync_status(Handler:GetSetSyncDetails),返回指定集群与模板的最新差异状态; - 查询批量同步状态:
POST /findmany/topo/set_template_sync_status/bk_biz_id/{bk_biz_id}(Handler:ListSetTemplateSyncStatus),返回业务下各集群模板是否"需要同步"的标记; - 查询同步历史:
POST /findmany/topo/set_template_sync_history/bk_biz_id/{bk_biz_id}(Handler:ListSetTemplateSyncHistory),查看历史同步任务的执行情况; - 预检差异:
POST /findmany/topo/set_template/{set_template_id}/bk_biz_id/{bk_biz_id}/diff_with_instances(Handler:DiffSetTplWithInst),在执行同步前先预览将会产生哪些差异,是安全变更的重要前置步骤。
在 UI 侧,集群模板列表页会通过同步状态接口标记出"需要同步"的模板(见 src/ui/src/views/set-template/index.vue 中 need-sync 标记逻辑),与上述接口对应。差异预检与同步派发共用 DiffSetTplWithInst,保证"预览结果"与"实际执行结果"一致。
调用建议与注意事项
- 先预检再同步:批量变更前先调用
diff_with_instances预览差异,确认新增/删除/修改的模块数量符合预期,避免误删模块; - 区分同步范围:
bk_set_ids只作用于列出的集群,未列出的集群不受影响;若希望对模板下全部集群同步,需自行先查询模板关联集群列表再传入; - 异步确认结果:接口返回
data: null仅表示任务派发成功,请通过instances_sync_status或set_template_sync_status确认最终同步结果; - 权限要求:调用方需具备目标业务的集群编辑权限,否则会被权限中心拦截并返回
permission信息; - 事务一致性:同步任务的派发过程在数据库事务内完成,若派发失败会自动回滚,不会产生"部分集群已派发"的中间状态;
- 并发上限:差异计算阶段采用容量为 10 的并发管道限流,大批量集群同步时会排队执行,属于预期行为。
综上,sync_set_template_to_set 是 bk-cmdb 集群模板体系中面向"存量集群对齐模板"的核心操作接口。理解其 Diff 计算、任务派发与异步执行机制后,开发者既可以安全地通过 ESB 网关调用,也能在需要时直接对接内部路由,实现集群结构的批量标准化治理。