后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载在蓝鲸智云配置平台BlueKing CMDB中集群模板Set Template是标准化集群资源建模的核心工具它允许用户在指定业务bk_biz_id下创建一个具名集群模板并通过服务模板 ID 列表将一组服务模板挂载到该集群模板上从而实现集群—服务模板—服务实例的标准化拓扑管控。本文以官方 API 文档 docs/apidoc/cc/zh_hans/create_set_template.md 为主体完整讲解该接口的请求参数、请求/响应示例、字段含义并结合 bk-cmdb 源码深入剖析接口背后的调用链、参数校验规则与数据落库逻辑帮助读者既会用接口也懂其实现原理。一、接口功能与适用场景该接口的官方定义为在指定业务 ID 下创建指定名称的集群模板创建的集群模板通过指定的服务模板 ID 去包含服务模板。调用该接口需要具备集群模板新建权限。在 CMDB 的模板化运维体系中集群模板承载如下职责将一组服务模板Service Template组织到同一个集群模板Set Template下形成可复用的集群标准结构后续可通过用集群模板同步集群能力把集群模板批量实例化为具体集群Set并把服务模板实例化为集群下的模块Module实现从模板到实例的自动化批量生成。因此创建集群模板是服务模板 → 集群模板 → 集群实例这条标准化链路的第一步也是后续sync_set_template_to_set用集群模板同步集群等操作的前提。二、请求参数详解2.1 公共参数common args请求中首先需要携带蓝鲸 API 网关APIGW/ESB统一要求的公共鉴权参数。以官方示例与 docs/apidoc/apigw/definition.yaml 中体现的字段为准典型公共参数如下字段类型必选描述bk_app_codestring是应用 ID即申请到的应用编码如esb_testbk_app_secretstring是应用密钥用于应用身份校验bk_usernamestring是操作用户名bk_tokenstring否登录态 Token与用户名二选一场景下的登录凭证bk_supplier_accountstring否开发商账号默认为0说明公共参数的必选程度取决于接入方使用的鉴权方式应用鉴权或登录态鉴权实际以蓝鲸 API 网关接入规范为准bk_supplier_account在请求示例中固定为0用于多租户/开发商隔离场景。2.2 接口专属参数接口参数定义如下与源码 src/common/metadata/set_template_request.go 中CreateSetTemplateOption结构体的 JSON 字段一一对应字段类型必选描述bk_biz_idint是业务 IDnamestring是集群模板名称service_template_idsarray是服务模板 ID 列表其中CreateSetTemplateOption的 Go 定义为type CreateSetTemplateOption struct { Name string field:name json:name bson:name mapstructure:name ServiceTemplateIDs []int64 field:service_template_ids json:service_template_ids bson:service_template_ids mapstructure:service_template_ids }可以看到name与service_template_ids同时被声明了 JSON、BSON 与 mapstructure 标签说明该结构体既用于 HTTP 请求体解码也用于 MongoDB 文档映射与配置转换是贯穿请求解析—数据落库的统一数据载体。三、完整请求与响应示例3.1 请求参数示例{ bk_app_code: esb_test, bk_app_secret: xxx, bk_username: xxx, bk_token: xxx, bk_supplier_account: 0, name: test, bk_biz_id: 20, service_template_ids: [59] }要点提示bk_biz_id为 20即业务 20 下创建集群模板name为test即集群模板名称service_template_ids为[59]即该集群模板关联 1 个服务模板ID 为 59请求示例同时演示了如何将业务 ID 放在请求体里而真实的 REST 接口实现中bk_biz_id也可通过 URL 路径/create/topo/set_template/bk_biz_id/{bk_biz_id}/传入详见下文接口实现。3.2 返回结果示例{ result: true, code: 0, message: success, permission: null, request_id: e43da4ef221746868dc4c837d36f3807, data: { id: 6, name: test, bk_biz_id: 20, creator: admin, modifier: admin, create_time: 2019-11-27T17:24:10.67165808:00, last_time: 2019-11-27T17:24:10.67165808:00, bk_supplier_account: 0 } }返回体中的data即为新创建的集群模板完整信息其中id: 6是系统生成的集群模板唯一 ID。四、返回结果参数说明4.1 response 通用字段所有 CMDB 接口统一遵循如下响应外壳定义于 src/common/metadata/result.go 的BaseResp体系字段类型描述resultbool请求成功与否。true请求成功false请求失败codeint错误编码。0 表示 success0 表示失败错误messagestring请求失败返回的错误信息permissionobject权限信息无权限需求时为 nullrequest_idstring请求链 ID用于全链路日志追踪dataobject请求返回的数据4.2 data 字段说明data对应集群模板实体SetTemplate源码定义见 src/common/metadata/set_template.go字段类型描述idint集群模板 IDnamestring集群模板名称官方文档中误标为 array实际为 stringbk_biz_idint业务 IDcreatorstring创建者modifierstring最后修改人员create_timestring创建时间RFC3339 格式含时区偏移last_timestring更新时间bk_supplier_accountstring开发商账号源码中的实体定义为type SetTemplate struct { ID int64 field:id json:id bson:id Name string field:name json:name bson:name BizID int64 field:bk_biz_id json:bk_biz_id bson:bk_biz_id Creator string field:creator json:creator bson:creator Modifier string field:modifier json:modifier bson:modifier CreateTime time.Time field:create_time json:create_time bson:create_time LastTime time.Time field:last_time json:last_time bson:last_time SupplierAccount string field:bk_supplier_account json:bk_supplier_account bson:bk_supplier_account }五、接口调用链与源码实现剖析5.1 REST 路由注册该接口的真实访问路径由拓扑服务topo_server注册见 src/scene_server/topo_server/service/service_settemplate_initfunc.goutility.AddHandler(rest.Action{Verb: http.MethodPost, Path: /create/topo/set_template/bk_biz_id/{bk_biz_id}/, Handler: s.CreateSetTemplate})即 HTTP 方法为POST完整网关路径为/api/v3/create/topo/set_template/bk_biz_id/{bk_biz_id}/。业务 ID 从 URL 路径中解析src/scene_server/topo_server/service/set_template.go请求体解码到metadata.CreateSetTemplateOption{}后进入业务逻辑。5.2 服务端处理流程topo_server → coreservice拓扑服务层的CreateSetTemplatesrc/scene_server/topo_server/service/set_template.go处理逻辑从 URL 路径解析bk_biz_id解析失败返回CCErrCommParamsInvalid将请求体解码到CreateSetTemplateOption校验service_template_ids非空为空返回CCErrCommParamsNeedSet在事务AutoRunTxn内调用 coreservice 的SetTemplate().CreateSetTemplate完成创建若开启了权限中心鉴权auth.EnableAuthorize()将新集群模板注册为 IAM 资源创建者动作RegisterResourceCreatorAction类型为BizSetTemplate详见 src/ac/iam/gen_id.go 的genSetTemplateResource与 src/ac/parser/settemplate.go 中创建集群模板的权限解析规则返回创建的SetTemplate实体。coreservice 层的CreateSetTemplatesrc/source_controller/coreservice/service/set_template.go进一步委托给核心操作类setTemplateOperation.CreateSetTemplate。5.3 底层落库逻辑与校验规则coreservice核心实现位于 src/source_controller/coreservice/core/settemplate/set_template.go完整执行顺序如下构造实体以当前时间初始化SetTemplateCreator/Modifier取请求用户SupplierAccount取请求的开发商账号名称合法性校验调用SetTemplate.Validatesrc/common/metadata/set_template.go内部通过valid.ValidTopoNameField校验拓扑名称格式业务 ID 校验ValidateBusinessID同文件 L42-L55在cc_BaseApp表中按bk_biz_id计数不存在则报参数非法服务模板 ID 校验ValidateServiceTemplateIDs同文件 L57-L76先对传入 ID 去重再在cc_ServiceTemplate表中按bk_biz_id id in (...)统计数量不一致即返回CCErrCommParamsInvalid确保传入的服务模板必须属于同一业务名称唯一性校验在cc_SetTemplate表中按name bk_biz_id bk_supplier_account过滤同业务下重名返回CCErrCommDuplicateItem生成 ID 并落库通过mongodb.Client().NextSequence(cc_SetTemplate)生成自增 ID插入cc_SetTemplate表写入关联关系将每个服务模板 ID 构造成SetServiceTemplateRelationsrc/common/metadata/set_template.go批量插入cc_SetServiceTemplateRelation表多对多关系。对应的 MongoDB 表结构可参见 docs/db/set_template.mdcc_SetTemplate存放集群模板信息cc_SetServiceTemplateRelation存放集群模板与服务模板的关联关系cc_SetTemplateAttr存放集群模板属性配置属性由创建集群模板全量信息接口create/topo/set_template/all_info一并写入。5.4 事务保证整个创建过程在拓扑服务层包裹于事务中AutoRunTxn见 src/scene_server/topo_server/service/set_template.go。若 coreservice 创建失败或 IAM 注册失败事务回滚避免出现模板已创建但权限未注册的中间态。六、测试用例验证仓库自带的集成测试 src/test/topo_server/set_template_test.go 完整覆盖了本接口的行为契约create empty set template testL25-L38传入空service_template_ids断言返回CCErrCommParamsNeedSet验证了服务模板 ID 列表必填的约束create normal set template testL40-L61使用合法的业务 ID 与service_template_ids: [serviceTemplateID]调用CreateSetTemplate断言result true、Name setTpl2、ID ! 0随后依次覆盖更新、列表查询、关联服务模板查询、基于模板创建集群、模板与集群差异对比Diff等全流程。读者可以以该测试文件为参照编写自己的客户端调用代码例如复用 src/apimachinery/toposerver/settemplate/settemplate.go 中的CreateSetTemplate客户端封装。七、常见问题与注意事项service_template_ids不能为空源码与测试均强制校验空列表会返回参数必填错误服务模板必须属于同一业务传入的service_template_ids会在cc_ServiceTemplate表中按业务过滤并计数核对跨业务传 ID 会失败名称同业务唯一同一业务下集群模板名称不可重复重名报CCErrCommDuplicateItem权限要求调用需具备集群模板新建权限启用权限中心时创建动作还会同步注册到 IAM 资源实例类型BizSetTemplate便于后续细粒度授权ID 生成id由 MongoDB 自增序列生成返回响应中的id是后续更新、删除、同步等操作如 update_set_template.md、sync_set_template_to_set.md的关键入参文档勘误提示官方文档data字段说明中name的类型标注为array从源码SetTemplate.Namestring 类型与返回示例看实际应为字符串类型。八、小结本文完整覆盖了 bk-cmdb创建集群模板接口的请求参数、请求/响应示例、返回字段说明并通过 src/scene_server/topo_server/service/set_template.go 与 src/source_controller/coreservice/core/settemplate/set_template.go 两条源码路径还原了从 REST 入口到 MongoDB 落库的完整调用链参数解析 → 权限注册 → 业务/服务模板/名称三重校验 → ID 生成 → 模板与关联关系双表写入 → 事务提交。掌握这一接口即掌握了 CMDB 集群模板标准化的起点也为后续集群模板同步、差异对比等高级能力打下基础。赞分享后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载相关推荐蓝鲸智云配置平台bk-cmdb集群模板创建 API 实战指南create_set_template蓝鲸智云配置平台bk cmdb集群模板创建 API 实战指南create_set_template 集群模板Set Template是蓝鲸智云配置平台后端企业应用运维蓝鲸智云配置平台bk-cmdb创建服务模板 API 实战指南接口参数、响应结构与源码级调用原理蓝鲸智云配置平台bk cmdb创建服务模板 API 实战指南接口参数、响应结构与源码级调用原理 服务模板Service Template是蓝鲸智云配置后端企业应用运维蓝鲸智云配置平台bk-cmdb集群模板删除接口 delete_set_template 详解与源码实现蓝鲸智云配置平台bk cmdb集群模板删除接口 delete_set_template 详解与源码实现 本指南以 bk cmdb蓝鲸智云配置平台Blue后端企业应用运维创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考