蓝鲸 CMDB 批量创建 Workload 接口（batch_create_kube_workload）实战指南

后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载本文围绕蓝鲸智云配置平台BlueKing CMDBAPI Gateway 提供的batch_create_kube_workload接口展开讲解如何通过一次请求在 CMDB 中批量登记 Kubernetes 工作负载Workload覆盖接口路由、参数结构、kind 类型语义、滚动更新策略以及调用与响应格式并下沉到 topo_server、coreservice 源码层解释 ID 生成、事务与审计等实现细节。读完本文你可以独立完成 deployment、statefulSet、daemonSet、cronJob、job 乃至 customResource 等各类工作负载的批量入库与结果解析。接口概览batch_create_kube_workload是蓝鲸 CMDB 提供给 API Gateway 的「批量创建 workload」接口版本 v3.12.1用于将 Kubernetes 集群中的工作负载数据一次性批量写入 CMDB作为容器拓扑建模的一部分。调用该接口需要具备「容器工作负载新建」权限。该接口在 API Gateway 侧的映射关系定义于 docs/apidoc/apigw/backend/bk_apigw_resources_bk-cmdb.yaml对应的网关资源为/api/v3/createmany/kube/workload/{kind}: post: operationId: batch_create_kube_workload description: 批量创建workload x-bk-apigateway-resource: isPublic: false allowApplyPermission: true backend: type: HTTP method: post path: /api/v3/createmany/kube/workload/{kind} pluginConfigs: - type: bk-rate-limit yaml: | rates: __default: - period: 1 tokens: 100可见该资源为私有资源isPublic: false、允许申请权限allowApplyPermission: true并配置了默认限流插件每 1 秒 100 个令牌。kind是路径参数直接拼接到 URL 中例如POST /api/v3/createmany/kube/workload/deployment。在 CMDB 服务端该路由由 topo_server 注册见 src/scene_server/topo_server/service/kube/service.go// workload utility.AddHandler(rest.Action{Verb: http.MethodPost, Path: /createmany/kube/workload/{kind}, Handler: s.CreateWorkload})输入参数详解顶层参数参数名称参数类型必选描述bk_biz_idint是业务idkindstring是workload类型目前支持的workload类型有deployment、daemonSet、statefulSet、gameStatefulSet、gameDeployment、cronJob、job、pods(放不通过workload而直接创建Pod)、customResource(自定义资源)dataarray是数组, 一次限制创建200其中bk_biz_id与kind缺一不可在源码 src/kube/types/workload.go 的WlCreateOption.Validate()中BizID 0会直接返回bk_biz_id未设置的错误kind则会先经过WorkloadType.Validate()校验不支持的 kind 会返回can not support this type of workload错误。data数组的长度上限由常量WlCreateLimit 200硬性约束见 src/kube/types/workload.go超过 200 条会返回超过限制的错误即文档所述「一次限制创建200」。data[x]参数名称参数类型必选描述bk_namespace_idint是namespace在cc中的唯一标识namestring是workload名称cr_kindstring否CR类型kind为customResource时必填cr_api_versionstring否CR的apiVersionkind为customResource时必填labelsmap否标签selectorobject否工作负载选择器replicasint否工作负载实例个数strategy_typestring否工作负载更新机制min_ready_secondsint否指定新创建的 Pod 在没有任意容器崩溃情况下的最小就绪时间 只有超出这个时间 Pod 才被视为可用rolling_update_strategyobject否滚动更新策略从源码看name与bk_namespace_id是所有 workload 类型必填的公共字段见 src/kube/types/workload.go 的WorkloadBase内嵌NamespaceSpec携带bk_namespace_id。cr_kind、cr_api_version仅对customResource生效且在 src/kube/types/custom_resource.go 的字段描述中被标记为IsRequired: true与文档「kind为customResource时必填」一致。strategy_type的可选值与 workload 类型相关详见下文「kind 类型与更新机制」一节。selector参数名称参数类型必选描述match_labelsmap否根据label匹配match_expressionsarray否匹配表达式对应源码中的LabelSelector结构src/kube/types/workload.gotype LabelSelector struct { // MatchLabels is a map of {key,value} pairs. MatchLabels map[string]string json:match_labels bson:match_labels // MatchExpressions is a list of label selector requirements. The requirements are ANDed. MatchExpressions []LabelSelectorRequirement json:match_expressions bson:match_expressions }match_labels与match_expressions的结果按 Kubernetes 语义做 AND 运算空 label selector 匹配所有对象null label selector 不匹配任何对象。match_expressions[x]参数名称参数类型必选描述keystring是标签的keyoperatorstring是操作符可选值In、NotIn、Exists、DoesNotExistvaluesarray否字符串数组如果操作符为In或NotIn,不能为空如果为Exists或DoesNotExist必须为空操作符在源码中以枚举常量形式定义src/kube/types/workload.goconst ( LabelSelectorOpIn LabelSelectorOperator In LabelSelectorOpNotIn LabelSelectorOperator NotIn LabelSelectorOpExists LabelSelectorOperator Exists LabelSelectorOpDoesNotExist LabelSelectorOperator DoesNotExist )rolling_update_strategy当strategy_type为RollingUpdate不为空其他情况为空参数名称参数类型必选描述max_unavailableobject否最大不可用max_surgeobject否最大溢出max_unavailable 与 max_surge两者结构一致用于表达「绝对数值或百分比」二选一的滚动更新限制对应源码中的IntOrString类型src/kube/types/workload.go参数名称参数类型必选描述typeint是可选值为0(表示int类型)或1(表示string类型)int_valint否当type为0(表示int类型)不能为空对应的的int值str_valstring否当type为1(表示string类型),不能为空对应的string值type IntOrString struct { Type Type json:type bson:type IntVal int32 json:int_val bson:int_val StrVal string json:str_val bson:str_val } const ( // IntType the IntOrString holds an int. IntType 0 // StringType the IntOrString holds a string. StringType 1 )type0时传int_val如5表示最多 5 个type1时传str_val如10%表示期望 Pod 数的百分比。这一设计对齐 Kubernetes 原生IntOrString语义其中max_unavailable表示更新过程中允许的最大不可用 Pod 数max_surge表示允许超出期望副本数的最大 Pod 数。kind 类型与更新机制kind路径参数在服务端被解析为WorkloadType枚举src/kube/types/types.goValidate()仅接受以下九种取值kind 取值对应结构体说明deploymentDeployment无状态应用更新机制支持Recreate重建、RollingUpdate滚动更新statefulSetStatefulSet有状态应用更新机制支持RollingUpdate、OnDeletedaemonSetDaemonSet守护进程集更新机制支持RollingUpdate、OnDeletegameStatefulSetGameStatefulSet游戏有状态集更新机制支持RollingUpdate、OnDelete、InplaceUpdate、HotPatchUpdategameDeploymentGameDeployment游戏无状态应用更新机制支持RollingUpdate、InplaceUpdate、HotPatchUpdatecronJobCronJob定时任务jobJob一次性任务podsPodsWorkload不通过 workload 而直接创建的 PodcustomResourceCustomResource自定义资源必须携带cr_kind与cr_api_version每种类型对应一张独立的 MongoDB 集合表名见 src/kube/types/types.go例如 deployment 写入cc_DeploymentBase、statefulSet 写入cc_StatefulSetBase、customResource 写入cc_CustomBase。WorkloadType.Table()会在创建时完成表名映射这也是「kind 一旦确定数据必须落到对应集合」的底层保证。各类型的滚动更新策略结构在源码中略有差异deployment 与 daemonSet 的RollingUpdateStrategy包含max_unavailable与max_surge两个IntOrString字段见 src/kube/types/deployment.go、src/kube/types/daemonset.gostatefulSet、gameStatefulSet 还额外包含partition字段gameDeployment 的RollingUpdateStrategy同样包含partition、max_unavailable、max_surge。调用示例以下示例以kinddeployment创建一个名为test的工作负载原文示例JSON 字段顺序与 API 文档保持一致{ bk_biz_id: 3, kind: deployment, data: [ { bk_namespace_id: 1, name: test, labels: { test: test, test2: test2 }, selector: { match_labels: { test: test, test2: test2 }, match_expressions: [ { key: tier, operator: In, values: [ cache ] } ] }, replicas: 1, strategy_type: RollingUpdate, min_ready_seconds: 1, rolling_update_strategy: { max_unavailable: { type: 0, int_val: 1 }, max_surge: { type: 0, int_val: 1 } } } ] }要点解读selector.match_labels要求与labels保持一致性示例中均为test: test、test2: test2match_expressions的多个表达式之间为 AND 关系replicas: 1表示工作负载实例个数为 1strategy_type: RollingUpdate配合rolling_update_strategy使用max_unavailable.type0、int_val1表示滚动更新时最多允许 1 个 Pod 不可用max_surge同理最多允许超出 1 个 Pod若想以百分比表达可将type改为1并填写str_val例如str_val: 10%。若创建自定义资源data中还需携带cr_kind与cr_api_version例如{ bk_biz_id: 3, kind: customResource, data: [ { bk_namespace_id: 1, name: my-cr, cr_kind: MyResource, cr_api_version: example.com/v1, replicas: 1 } ] }响应示例与响应参数说明成功响应示例{ result: true, code: 0, data: { ids: [ 1 ] }, message: success, permission: null, }注意返回的data中的workloadID数组顺序与参数中的数组数据顺序保持一致。响应参数说明参数名称参数类型描述resultbool请求成功与否。true:请求成功false请求失败codeint错误编码。 0表示success0表示失败错误messagestring请求失败返回的错误信息permissionobject权限信息dataobject请求返回的数据data参数名称参数类型描述idsarray在cc中的唯一标识数组data.ids对应源码中的metadata.RspIDs结构由CreateWorkload处理后返回。其顺序与请求data数组一一对应按索引对齐这从 src/scene_server/topo_server/service/kube/workload.go 的审计日志生成逻辑data.IDs[idx]与req.Data[idx]配对可以印证。服务端调用链与实现原理batch_create_kube_workload请求进入 CMDB 后主链路为API Gateway → topo_server → coreservice → MongoDB。topo_server 入口处理src/scene_server/topo_server/service/kube/workload.go解析路径参数kind并调用WorkloadType.Validate()校验反序列化请求体为types.WlCreateOption并整体校验业务 ID、data 数量 ≤ 200、逐条ValidateCreate权限校验构造acmeta.ResourceAttribute{Type: acmeta.KubeWorkload, Action: acmeta.Create}即「容器工作负载新建」权限。权限动作与 IAM 资源类型的映射见 src/ac/iam/adaptor.gometa.KubeWorkload→CreateContainerWorkload通过AutoRunTxn开启事务在事务内调用 coreservice 的CreateWorkload并生成审计日志auditlog.NewKubeAuditGenerateWorkloadAuditLog失败则整体回滚。coreservice 实际落库src/source_controller/coreservice/service/kube/workload.go根据kind.Table()确定目标集合如cc_DeploymentBase通过mongodb.Client().NextSequences批量预取自增 ID按序填充到每条 workload 并写入respData.IDs—— 这正是响应ids与请求data顺序一致的来源根据请求中的bk_namespace_id批量查询 namespaceGetNamespaceSpec将 namespace 归属的业务 ID、集群 ID、集群 UID、namespace 名称回填到 workload 的NamespaceSpec中保证 workload 始终挂接在正确的容器拓扑节点下调用CheckPlatBizSharedNs做共享集群shared cluster合法性校验若 workload 所属 namespace 的业务与请求bk_biz_id不一致必须存在对应的共享集群关系记录否则报参数错误逐条写入 Revisioncreator、modifier、create_time、last_time与bk_supplier_account后批量Insert。事件与缓存写入完成后cacheservice 会通过 watch 机制感知 workload 集合的数据变更见 src/source_controller/cacheservice/event/flow/workload_flow.go —— 它一次性监听全部 9 张 workload 集合cc_DeploymentBase、cc_StatefulSetBase、cc_DaemonSetBase、cc_GameDeploymentBase、cc_GameStatefulSetBase、cc_CronJobBase、cc_JobBase、cc_PodWorkloadBase、cc_CustomBase用于维护容器业务拓扑缓存。测试用例参考仓库提供了覆盖 workload 完整生命周期的端到端测试 src/test/topo_server/workload_test.go流程为创建业务 → 创建集群 → 创建 namespace →CreateWorkloadkinddeployment携带 labels、selector、replicas、strategy_type、min_ready_seconds 与滚动更新策略→UpdateWorkload→ListWorkload查询与计数 →DeleteWorkload。测试中滚动更新策略的两种形态均有覆盖rollingUpdateStrategy : types.RollingUpdateDeployment{ MaxUnavailable: types.IntOrString{ Type: types.IntType, // type0 IntVal: 2, }, MaxSurge: types.IntOrString{ Type: types.StringType, // type1 StrVal: 12, }, }这与你通过 API 调用batch_create_kube_workload时提交的rolling_update_strategy结构完全一致可作为构造请求体的直接参考。注意事项与最佳实践版本与权限接口自 v3.12.1 起提供调用方需通过 API Gateway 申请「容器工作负载新建」权限对应 IAM 动作CreateContainerWorkload批量上限单次data最多 200 条超出返回错误如需导入更多数据请分批调用顺序保证响应data.ids与请求data数组按索引一一对应可用于建立外部系统与 CMDB workload ID 的映射kind 大小写敏感statefulSet、daemonSet、gameStatefulSet、gameDeployment、cronJob等取值须与文档严格一致且写入后数据落于各自独立的集合customResource 必填项kindcustomResource时必须同时提供cr_kind与cr_api_versionnamespace 归属校验bk_namespace_id对应的 namespace 必须属于bk_biz_id业务或处于该业务可用的共享集群中否则请求会被拒绝selector 与 labels 一致性建议保持match_labels与labels内容一致避免后续查询与拓扑展示时出现语义歧义滚动更新策略约束max_unavailable与max_surge不能同时为 0strategy_type非RollingUpdate时rolling_update_strategy应保持为空。赞分享后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载相关推荐蓝鲸配置平台bk-cmdb批量更新 Kubernetes Workload 接口实战指南蓝鲸配置平台bk cmdb批量更新 Kubernetes Workload 接口实战指南 导读 本文围绕 bk cmdb蓝鲸智云配置平台API 网关提供后端企业应用运维蓝鲸 CMDB 批量创建容器节点接口 batch_create_kube_node 实战指南蓝鲸 CMDB 批量创建容器节点接口 batch_create_kube_node 实战指南 导读 本文讲解蓝鲸智云配置平台bk cmdb开放接口中批量创后端企业应用运维蓝鲸配置平台 bk-cmdb 批量删除 Kubernetes Workload 接口batch_delete_kube_workload实战指南蓝鲸配置平台 bk cmdb 批量删除 Kubernetes Workload 接口batch_delete_kube_workload实战指南 本篇技术指后端企业应用运维上一篇百度网盘提取码终极破解指南3秒快速获取资源密码的完整教程下一篇GHelper终极指南释放华硕笔记本的隐藏性能创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考