后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载导读batch_update_kube_cluster是蓝鲸智云配置平台bk-cmdb提供的容器集群属性批量更新接口v3.12.1允许调用方通过集群在 CMDB 中的唯一 ID 列表一次性更新多个 Kubernetes/TKE 集群的名称、版本、网络类型、地域、环境及项目归属等字段。本文以官方 API 文档为主体结合 bk-cmdb 开源仓库topo_server、coreservice、apimachinery、kube/types 等中的源码实现完整讲解该接口的参数规范、请求/响应示例、调用限制、底层处理链路与权限校验机制帮助开发者正确、安全地接入并使用该接口。一、接口概览项目说明接口名称batch_update_kube_cluster批量更新容器集群属性字段引入版本v3.12.1所需权限容器集群的编辑权限支持更新的字段集群名称、版本、网络类型、地域、集群网络、环境、项目 ID、项目名称、项目英文名不支持更新集群类型type需使用独立的update_kube_cluster_type接口该接口是 CMDB 容器资源管理Kubernetes 集群建模能力的一部分。在 bk-cmdb 中容器集群与节点、命名空间、工作负载、Pod 等资源共同构成容器业务拓扑集群作为最上层的容器资源单元其属性变化如版本升级、环境调整、项目归属变更需要通过本接口同步到 CMDB 的_bk_base_cluster集合中。从源码中的路由注册service.go可以看到topo_server 通过 REST 风格暴露了完整的集群管理接口族HTTP 方法路径对应处理函数POST/create/kube/clusterCreateClusterDELETE/delete/kube/clusterDeleteClusterPUT/updatemany/kube/clusterUpdateClusterFields本文接口PUT/update/kube/cluster/typeUpdateClusterTypePOST/findmany/kube/clusterSearchClusters本文所讲的批量更新接口对应PUT /updatemany/kube/cluster注意是updatemany前缀与单集群操作的路径风格/update/kube/cluster/type相区分。二、请求参数详解1. 公共参数接口请求中需要携带蓝鲸 API 网关ESB的公共鉴权参数即文档中{{ common_args_desc }}占位符所指代的内容通常包括字段类型必选描述bk_app_codestring是应用 ID接入 CMDB OpenAPI 的应用标识bk_app_secretstring是应用密钥安全校验用bk_usernamestring是操作者用户名bk_tokenstring是用户登录态令牌2. 接口参数字段类型必选描述bk_biz_idint是业务 IDidsarray是cluster 在 CMDB 中的唯一 ID 列表dataobject是需要更新的数据对应到源码中的请求结构体cluster.go// UpdateClusterOption update cluster request. type UpdateClusterOption struct { BizID int64 json:bk_biz_id UpdateClusterByIDsOption } // UpdateClusterByIDsOption update cluster by ids request。 type UpdateClusterByIDsOption struct { IDs []int64 json:ids Data Cluster json:data }其中bk_biz_id对应UpdateClusterOption.BizIDids对应IDsdata对应Cluster结构体两者通过 Go 结构体嵌套组合成完整请求体。3. data 对象字段data内可更新的字段全部为选填Partial Update 语义未传字段保持不变字段类型必选描述namestring否集群名称versionstring否集群版本network_typestring否网络类型如 overlay、underlayregionstring否地域networkarray否集群网络容器 overlay 网络的全局路由网段列表例如[127.0.0.0/21]environmentstring否环境bk_project_idstring否项目 IDbk_project_namestring否项目名称bk_project_codestring否项目英文名这些字段与集群数据模型src/kube/types/cluster.go中的Cluster结构体及ClusterSpecFieldsDescriptor一一对应data 字段Go 结构体字段json tag数据库字段bsonnameNamenameversionVersionversionnetwork_typeNetworkTypenetwork_typeregionRegionregionnetworkNetWorknetworkenvironmentEnvironmentenvironmentbk_project_idProjectIDbk_project_idbk_project_nameProjectNamebk_project_namebk_project_codeProjectCodebk_project_code字段名常量定义于 types.go其中bk_project_id、bk_project_name、bk_project_code三个项目相关字段用于将集群与蓝鲸项目bk project进行关联。三、完整请求示例{ bk_app_code: esb_test, bk_app_secret: xxx, bk_username: xxx, bk_token: xxx, bk_biz_id: 3, ids: [ 1 ], data: { name: cluster, version: 1.20.6, network_type: underlay, region: xxx, network: [ 127.0.0.0/21 ], environment: xxx, bk_project_id: 21bf9ef9be7c4d38a1d1f2uc0b44a8f2, bk_project_name: test, bk_project_code: test } }示例要点bk_biz_id: 3表示目标集群归属于业务 3ids: [1]表示待更新集群在 CMDB 中的自增 ID 为 1data中给出了network_type: underlay即集群网络类型为 underlay 模式这与源码注释中网络类型如 overlay 或 underlaycluster.go的描述一致network以数组形式声明集群的容器 overlay 网络路由网段如127.0.0.0/21对应源码中NetWork *[]string的切片类型定义。四、返回结果示例{ result: true, code: 0, message: success, permission: null, request_id: 87de106ab55549bfbcc46e47ecf5bcc7, data: null }五、返回结果参数说明字段类型描述resultbool请求成功与否。true请求成功false请求失败codeint错误编码。0 表示 success0 表示失败错误messagestring请求失败返回的错误信息permissionobject权限信息request_idstring请求链 IDdataobject无数据返回本接口更新成功后data为 null注意本接口为更新即成功语义成功后不返回更新后的集群对象若需要回读更新结果可结合集群查询接口/findmany/kube/cluster另行获取。六、源码视角批量更新的内部处理链路1. 服务端入口与参数解析接口请求首先进入 topo_server 的UpdateClusterFields处理函数cluster.go完整处理链路如下参数解析ctx.DecodeInto(data)将请求体反序列化为types.UpdateClusterOption参数校验data.Validate()依次校验bk_biz_id非 0、ids非空且数量不超限、data中各字段合法详见下文权限校验构造acmeta.ResourceAttribute{Type: acmeta.KubeCluster, Action: acmeta.Update, BusinessID: data.BizID}调用 IAM 鉴权对应容器集群的编辑权限集群归属校验getUpdateClustersInfo以ids bk_biz_id为条件查询集群若查到的集群数量与ids长度不一致则直接报错the clusterIDs must all be under the given business确保所有待更新集群必须属于同一业务强制剔除集群类型if data.UpdateClusterByIDsOption.Data.Type ! nil { data.UpdateClusterByIDsOption.Data.Type nil }——即使用户在 data 中携带了 type 字段也会被丢弃从代码层面硬性保证了本接口不支持更新集群类型这一约束事务化更新通过AutoRunTxn开启事务先调用 coreservice 的UpdateClusterFields写库再为每个被更新的集群生成并保存审计日志audit.GenerateClusterAuditLogaudit.SaveAuditLog任一环节失败则整体回滚响应成功后ctx.RespEntity(nil)对应响应示例中的data: null。2. 调用链与接口路由对外暴露的 OpenAPI 请求经 apimachinery 客户端转发到 topo_server。客户端侧封装位于 kube.go// UpdateClusterFields update cluster fields. func (st *Kube) UpdateClusterFields(ctx context.Context, header http.Header, data *types.UpdateClusterOption) errors.CCErrorCoder { ret : new(metadata.Response) subPath : /updatemany/kube/cluster err : st.client.Put(). WithContext(ctx). Body(data). SubResourcef(subPath). WithHeaders(header). Do(). Into(ret) ... }内部完整调用链为OpenAPI /updatemany/kube/cluster → topo_server service/kube/cluster.go: UpdateClusterFields → coreservice Kube().UpdateClusterFieldsapimachinery → coreservice service/kube/cluster.go: BatchUpdateCluster → MongoDB: _bk_base_cluster 集合 Update3. 可编辑字段校验机制更新请求中的字段并非任意可写而是受ClusterFields字段描述符约束cluster.govar ClusterFields table.MergeFields(CommonSpecFieldsDescriptor, BizIDDescriptor, ClusterSpecFieldsDescriptor)其中ClusterSpecFieldsDescriptor定义了集群业务字段的类型与可编辑性例如nameString可编辑、versionString可编辑、network_typeEnum可编辑、regionString可编辑、networkString可编辑、environmentString可编辑bk_project_id/bk_project_name/bk_project_code均 String可编辑scheduling_engine调度引擎、uid、xid、vpcVPC 网络等字段被标记为IsEditable: false不允许通过本接口更新type集群类型虽标记为可编辑但在服务端入口处已被强制置空只能走专用接口。CommonSpecFieldsDescriptorspec.go则定义了通用字段id、bk_supplier_account、creator、modifier、create_time、last_time其中仅modifier与last_time可编辑其余均为系统管理字段。底层校验由ValidateUpdatevalidate.go通过反射完成仅当字段为非 nil 指针时才视为本次需要更新再检查该字段在字段描述符中是否允许编辑从而保证部分更新Partial Update语义——未传字段保持原值不变。4. 底层存储更新coreservice 的BatchUpdateClustercluster.go执行最终写库以ids构造 MongoDB 的$in条件并追加bk_supplier_account归属条件SetModOwner确保只更新当前租户/供应商账户下的数据通过orm.GetUpdateFieldsWithOption结合IgnoredUpdateClusterFieldsid、bk_supplier_account、bk_biz_id、cluster_uid见 cluster.go过滤出真正可更新的字段避免主键与归属字段被误改最终执行mongodb.Client().Table(types.BKTableNameBaseCluster).Update(...)更新_bk_base_cluster集合。七、使用注意事项与边界约束1. 批量数量限制重要差异提示官方文档声明一次性更新集群数量不超过 100 个。但需要特别提示在当前开源仓库的源码实现中maxUpdateClusterNum被定义为 10cluster.goconst ( maxDeleteClusterNum 10 maxUpdateClusterNum 10 )且UpdateClusterByIDsOption.Validate()cluster.go会在len(option.IDs) maxUpdateClusterNum时返回CCErrCommXXExceedLimit错误。因此在实际调用当前仓库代码构建的 CMDB 时建议将单次ids数量控制在 10 个以内并对超限返回做容错处理文档中100 个的表述应理解为产品文档层面的上限说明实际以所部署版本代码为准。批量数量较大时请分批次调用。2. 集群类型不可在本接口更新本接口明确不支持更新集群类型type。服务端在处理时会将data.Type强制置空cluster.go因此即使传入也会被静默忽略不会报错也不会生效。如需更新集群类型请使用update_kube_cluster_type接口PUT /update/kube/cluster/type对应UpdateClusterType处理函数。该接口除常规鉴权外还会执行validateUpdateClusterType类型转换校验cluster.goSHARE_CLUSTER共享集群仅能由INDEPENDENT_CLUSTER独立集群转换而来INDEPENDENT_CLUSTER仅能由SHARE_CLUSTER转换而来且转换前会检查该集群是否仍被其他业务共享使用统计bk_namespace_id关联表中bk_biz_id ! 当前业务的共享命名空间记录存在共享资源时禁止转为独立集群。3. 集群必须归属于同一业务服务端getUpdateClustersInfo会严格校验查询到的集群数量与ids长度不一致时直接报错防止跨业务批量修改。4. 权限要求调用者需具备容器集群的编辑权限acmeta.KubeClusteracmeta.Update并且权限校验是基于bk_biz_id粒度进行的业务级授权。无权限时接口返回RespNoAuth响应中的permission字段会携带权限申请信息。5. 审计可追溯更新过程会在事务内为每个集群生成更新审计日志记录更新前后的字段差异相关实现位于 auditlog/kube.go可通过 CMDB 的审计查询能力追溯每次批量修改的操作者与变更内容。6. 字段更新语义data内所有字段均为选填采用部分更新语义只有被显式传入且合法的字段才会被写入未传字段保持原值id、bk_supplier_account、bk_biz_id、cluster_uid等系统字段即使传入也会被忽略。八、相关接口一览如需完整管理容器集群资源可配合使用以下同族接口路由注册见 service.go接口功能路由create_kube_cluster创建容器集群POST/create/kube/clusterdelete_kube_cluster删除容器集群DELETE/delete/kube/clusterbatch_update_kube_cluster批量更新容器集群属性本文PUT/updatemany/kube/clusterupdate_kube_cluster_type更新容器集群类型PUT/update/kube/cluster/typefind_many_kube_cluster按条件查询容器集群POST/findmany/kube/cluster此外集群之下还有节点/kube/node、命名空间/kube/namespace、工作负载/kube/workload/{kind}、Pod/kube/pod等容器资源管理接口共同构成 CMDB 的容器业务拓扑管理能力。相关的集群数据模型、字段定义与校验规则可进一步阅读 src/kube/types 目录下的源码。总结batch_update_kube_cluster是 bk-cmdb 容器集群资源管理中高频使用的批量维护接口。本文从官方 API 文档出发结合仓库源码完整还原了其参数规范、请求/响应格式、服务端处理链路解析 → 校验 → 鉴权 → 归属校验 → 字段过滤 → 事务更新 → 审计与底层存储实现并指出了文档与当前源码在批量数量上限上的差异文档 100 vs 源码常量 10。实际接入时请务必单次提交数量以所部署版本实际限制为准、区分集群属性更新与集群类型更新两个接口、确认目标集群归属同一业务并具备容器集群编辑权限即可安全稳定地使用该接口维护容器集群元数据。赞分享后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载相关推荐蓝鲸 CMDB 批量更新容器集群属性接口 batch_update_kube_cluster 详解蓝鲸 CMDB 批量更新容器集群属性接口 batch_update_kube_cluster 详解 本文围绕蓝鲸智云配置平台BlueKing CMDB对外提后端企业应用运维蓝鲸 CMDB 容器集群批量更新接口详解batch_update_kube_cluster 参数、约束与源码实现蓝鲸 CMDB 容器集群批量更新接口详解batch_update_kube_cluster 参数、约束与源码实现 导读 本文围绕蓝鲸智云配置平台BlueKi后端企业应用运维蓝鲸 CMDB 更新容器集群类型接口update/kube/cluster/type实战指南蓝鲸 CMDB 更新容器集群类型接口update/kube/cluster/type实战指南 导读 本文基于蓝鲸智云配置平台BlueKing CMDB的后端企业应用运维创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考