后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载集群模板Set Template是蓝鲸智云配置平台bk-cmdb中用于统一管理集群Set实例结构的关键抽象它将一组服务模板Service Template与集群属性固化到模板中再通过同步批量应用到具体集群。本文聚焦集群模板生命周期管理中的删除环节完整讲解delete_set_template接口的请求参数、调用示例、响应结构并结合 bk-cmdb 开源仓库的 topo_server、coreservice 源码与测试用例剖析删除动作背后的引用保护、级联清理与权限控制机制帮助开发者安全、正确地通过开放 API 移除集群模板。接口功能概述delete_set_template用于根据业务 ID 与集群模板 ID 列表删除指定业务下的集群模板支持一次批量删除多个模板。该接口需要调用方具备集群模板删除权限对应 IAM 动作delete_biz_set_template。从调用链上看该接口属于拓扑管理topo_server对外暴露的 REST API其路径为DELETE /api/v3/deletemany/topo/set_template/bk_biz_id/{bk_biz_id}/该路由在 src/scene_server/topo_server/service/service_settemplate_initfunc.go 中注册utility.AddHandler(rest.Action{Verb: http.MethodDelete, Path: /deletemany/topo/set_template/bk_biz_id/{bk_biz_id}/, Handler: s.DeleteSetTemplate})注意这里是deletemany批量删除与单条删除接口不同删除目标通过请求体中的set_template_ids数组指定而不是放在 URL 路径里。请求参数说明公共请求参数该接口为 ESB企业服务总线/ APIGW 网关接入方式请求中需要附带蓝鲸体系的公共鉴权与身份参数即文档中{{ common_args_desc }}所代表的内容典型字段如下字段类型必填说明bk_app_codestring是应用 ID蓝鲸应用身份标识bk_app_secretstring是应用密钥用于接口鉴权bk_usernamestring否当前用户名称用于权限校验的身份来源bk_tokenstring否登录票据与 bk_username 二选一接口参数字段类型必填说明bk_biz_idint是业务 ID即集群模板所属的业务set_template_idsarray是集群模板 ID 列表可一次提交多个待删除的 ID其中bk_biz_id同时作为 URL 路径参数存在/bk_biz_id/{bk_biz_id}/因此该字段在请求体中与 URL 中会重复出现set_template_ids则只出现在请求体 JSON 中。对应的请求体结构定义在 src/common/metadata/set_template_request.go// DeleteSetTemplateOption TODO type DeleteSetTemplateOption struct { SetTemplateIDs []int64 field:set_template_ids json:set_template_ids bson:set_template_ids mapstructure:set_template_ids }从定义可以看出set_template_ids是int64数组。若未传该字段或传入空数组服务端将无法执行删除同时列表中的 ID 必须全部真实存在且属于该业务否则删除结果无法达到预期。请求参数示例以下为完整的请求报文示例包含公共参数与接口参数{ bk_app_code: esb_test, bk_app_secret: xxx, bk_username: xxx, bk_token: xxx, bk_biz_id: 20, set_template_ids: [59] }该示例表示在业务 ID 为20的业务下删除 ID 为59的集群模板。若需要批量删除多个模板将set_template_ids扩展为[59, 60, 61]即可。响应示例删除成功时接口返回如下{ result: true, code: 0, message: success, permission: null, request_id: e43da4ef221746868dc4c837d36f3807, data: null }删除操作无业务数据回传因此data字段为null。result: true、code: 0共同表示本次请求成功执行。返回结果参数说明所有 bk-cmdb 接口统一采用以下响应包裹结构response字段类型说明resultbool请求是否成功。true成功false失败codeint错误码。0 表示成功0 表示失败的错误码messagestring失败时返回的错误信息permissionobject权限信息当发生权限校验拦截时返回request_idstring请求链路 ID用于日志追踪与问题定位dataobject请求返回的数据删除接口成功时为 null对应地在 src/apimachinery/coreservice/settemplate/api.go 中删除请求的客户端封装为// DeleteSetTemplate TODO func (p *setTemplate) DeleteSetTemplate(ctx context.Context, header http.Header, bizID int64, option metadata.DeleteSetTemplateOption) errors.CCErrorCoder { ret : struct { metadata.BaseResp json:,inline }{} subPath : /deletemany/topo/set_template/bk_biz_id/%d/ err : p.client.Delete(). WithContext(ctx). Body(option). SubResourcef(subPath, bizID). WithHeaders(header). Do(). Into(ret) ... }这里的BaseResp即对应响应中的result、code、message、permission、request_id等公共字段data字段则由具体接口自行定义。删除动作的底层实现解析1. topo_server 服务层参数解析与事务包裹拓扑服务层的处理入口为Service.DeleteSetTemplate位于 src/scene_server/topo_server/service/set_template.go。其处理流程如下从 URL 路径参数中解析bk_biz_id解析失败时返回CCErrCommParamsInvalid将请求体 JSON 解码为metadata.DeleteSetTemplateOption通过CoreService().Txn().AutoRunTxn开启事务在事务内调用 coreservice 的SetTemplate().DeleteSetTemplate完成删除事务失败则回滚并返回错误成功则RespEntity(nil)返回空数据。关键代码如下option : metadata.DeleteSetTemplateOption{} if err : ctx.DecodeInto(option); err ! nil { ctx.RespAutoError(err) return } txnErr : s.Engine.CoreAPI.CoreService().Txn().AutoRunTxn(ctx.Kit.Ctx, ctx.Kit.Header, func() error { if err : s.Engine.CoreAPI.CoreService().SetTemplate().DeleteSetTemplate(ctx.Kit.Ctx, ctx.Kit.Header, bizID, option); err ! nil { blog.Errorf(DeleteSetTemplate failed, ..., ...) return err } return nil })2. coreservice 数据层引用检查 级联删除真正落库的实现在 coreservice 的setTemplateOperation.DeleteSetTemplate位于 src/source_controller/coreservice/core/settemplate/set_template.go。删除过程分为三步第一步引用检查关键保护删除前会先查询cc_Set集群实例表中是否存在set_template_id落在待删除 ID 列表内的集群setFilter : map[string]interface{}{ common.BKAppIDField: bizID, common.BKOwnerIDField: kit.SupplierAccount, common.BKSetTemplateIDField: map[string]interface{}{ common.BKDBIN: option.SetTemplateIDs, }, } referenceCount, err : mongodb.Client().Table(common.BKTableNameBaseSet).Find(setFilter).Count(kit.Ctx) ... if referenceCount 0 { blog.Error(DeleteSetTemplate failed, set templates referenced by %d sets, ..., referenceCount, ...) return kit.CCError.CCError(common.CCErrCommRemoveReferencedRecordForbidden) }也就是说只要还有集群实例在引用该模板即由该模板创建的集群仍存在删除就会被拒绝返回被引用记录禁止删除类错误CCErrCommRemoveReferencedRecordForbidden。这保证了一旦删除模板不会出现孤儿集群失去模板语义约束的情况。第二步删除集群模板主记录引用检查通过后按bk_biz_id、bk_owner_id供应商账号与id IN set_template_ids条件删除cc_SetTemplate表中的模板记录setTplFilter : map[string]interface{}{ common.BKAppIDField: bizID, common.BKOwnerIDField: kit.SupplierAccount, common.BKFieldID: map[string]interface{}{ common.BKDBIN: option.SetTemplateIDs, }, } if err : mongodb.Client().Table(common.BKTableNameSetTemplate).Delete(kit.Ctx, setTplFilter); err ! nil { ... }注意删除条件同时包含bk_biz_id与bk_owner_id从数据层面确保只能删除本业务、本供应商账号下的模板跨业务/跨租户的 ID 无法被误删。第三步级联清理模板与服务模板的关联关系集群模板的构成由cc_SetServiceTemplateRelation集群模板-服务模板多对多关系表记录。删除模板时需同步清理这些关联记录relationFilter : map[string]interface{}{ common.BKAppIDField: bizID, common.BKOwnerIDField: kit.SupplierAccount, common.BKSetTemplateIDField: map[string]interface{}{ common.BKDBIN: option.SetTemplateIDs, }, } if err : mongodb.Client().Table(common.BKTableNameSetServiceTemplateRelation).Delete(kit.Ctx, relationFilter); err ! nil { ... }相关的表名常量定义在 src/common/tablenames.goBKTableNameSetTemplate cc_SetTemplate BKTableNameSetTemplateAttr cc_SetTemplateAttr BKTableNameSetServiceTemplateRelation cc_SetServiceTemplateRelation关于集群模板属性cc_SetTemplateAttr的说明从当前删除实现看删除流程只清理了主记录与服务模板关联关系两类数据。集群模板的自定义属性数据cc_SetTemplateAttr在模板被删除后是否会一并清理从源码结构看该删除路径中并未显式处理如需彻底清理模板属性可关注 set_template_attr.go 中提供的属性删除接口。3. 权限控制IAM 资源与动作该接口的权限模型在鉴权解析器中有明确注册见 src/ac/parser/settemplate.go{ Name: DeleteSetTemplateRegex, Description: 删除集群模板, Regex: regexp.MustCompile(^/api/v3/deletemany/topo/set_template/bk_biz_id/([0-9])/?$), HTTPMethod: http.MethodDelete, BizIDGetter: BizIDFromURLGetter, ResourceType: meta.SetTemplate, ResourceAction: meta.Delete, InstanceIDGetter: func(request *RequestContext, re *regexp.Regexp) (int64s []int64, e error) { data : struct { SetTemplateIDs []int64 json:set_template_ids mapstructure:set_template_ids }{} ... return data.SetTemplateIDs, nil }, },解析器会从请求体中提取set_template_ids作为实例 ID交给 IAM 做资源实例级鉴权。对应的资源类型与动作定义在 src/ac/iam/types.go 中资源类型BizSetTemplatebiz_set_template即集群模板动作DeleteBusinessSetTemplatedelete_biz_set_template即删除集群模板。因此在网关/开放平台调用该接口时当前用户必须具备对应业务下这些目标集群模板的删除权限否则会被鉴权拦截并在响应中返回permission信息。测试用例对删除语义的验证仓库中的集成测试用例 src/test/topo_server/set_template_test.go 对删除接口的两种典型场景做了验证可作为理解接口行为的权威依据场景一模板仍被集群引用时删除必须失败// delete setTemplate be referenced By(delete set template) func() { option : metadata.DeleteSetTemplateOption{ SetTemplateIDs: []int64{setTemplateID}, } err : topoServerClient.SetTemplate().DeleteSetTemplate(ctx, header, bizID, option) Expect(err).NotTo(BeNil()) }()随后测试通过ListSetTemplate确认模板仍然存在Count 0且结果中包含该模板 ID印证了被引用禁止删除的保护逻辑。场景二先删除集群实例再删除模板删除成功By(delete set) func() { err : topoServerClient.Instance().DeleteSet(ctx, bizID, setID, header) Expect(err).To(BeNil()) }() By(delete set template) func() { option : metadata.DeleteSetTemplateOption{ SetTemplateIDs: []int64{setTemplateID}, } err : topoServerClient.SetTemplate().DeleteSetTemplate(ctx, header, bizID, option) Expect(err).To(BeNil()) }()删除集群后再执行删除模板此时引用计数为 0删除成功测试随后再次ListSetTemplate验证结果Count为 0模板已被彻底移除。这两组用例清晰揭示了删除集群模板的正确操作顺序先删除由该模板创建的集群实例再删除模板本身这与蓝鲸配置平台中集群模板不能直接删除被引用的模板的设计语义完全一致。使用注意事项与最佳实践先解除引用再删除删除set_template_ids中的模板前请通过按模板查询集群接口ListSetTplRelatedSets见 set_template.go确认没有集群实例仍在使用这些模板。若仍有引用删除请求会被拒绝并返回CCErrCommRemoveReferencedRecordForbidden类错误。批量删除的边界set_template_ids支持数组批量删除但所有 ID 必须属于请求 URL 中bk_biz_id指定的同一业务跨业务 ID 不会被删除数据层删除条件强制限定bk_biz_id与bk_owner_id。权限前置调用前确保当前用户bk_username/bk_token对应身份对目标模板具备删除集群模板delete_biz_set_template权限否则响应中permission字段会携带拦截详情。响应判定以result与code为准判断成功与否code: 0且result: true才代表删除完成失败时结合message与request_id链路 ID进行问题定位与日志追溯。删除的语义边界删除模板只会移除模板本身及其与服务模板的关联关系不会影响已被删除集群之外的其他集群实例也不会自动销毁服务模板——服务模板仍可在业务内独立存在与复用。通过本文的接口说明与源码级剖析你可以完整掌握 bk-cmdb 集群模板删除 API 的调用方式、失败场景与底层保护机制从而在自动化运维与 CMDB 数据治理流程中安全地管理集群模板生命周期。赞分享后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载相关推荐蓝鲸配置平台 bk-cmdb 删除集群模板接口 delete_set_template 深度指南蓝鲸配置平台 bk cmdb 删除集群模板接口 delete_set_template 深度指南 导读 本文围绕蓝鲸智云配置平台BlueKing CMDB即后端企业应用运维蓝鲸智云配置平台bk-cmdb集群模板删除接口 delete_set_template 详解与源码实现蓝鲸智云配置平台bk cmdb集群模板删除接口 delete_set_template 详解与源码实现 本指南以 bk cmdb蓝鲸智云配置平台Blue后端企业应用运维蓝鲸配置平台bk-cmdb批量删除业务集接口详解蓝鲸配置平台bk cmdb批量删除业务集接口详解 导读 本文围绕蓝鲸配置平台bk cmdb提供的批量删除业务集开放接口展开完整介绍接口的版本与权限后端企业应用运维创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考