企业官网建设流程全解析

• 后端
• 企业应用
• 运维

本文基于 bk-cmdb 的 API 文档 batch_create_kube_workload.md 编写，完整讲解"批量创建 workload"接口（v3.12.1+）的请求参数结构、各字段语义、JSON 请求/响应示例与返回约定，并结合 topo_server 路由注册、coreservice 落库实现 与 类型定义 等源码给出底层原理佐证。读者阅读后能够掌握该接口的参数规范、权限要求、批量上限、错误处理方式，并可直接复制请求示例进行调用与二次开发。

接口概览

该接口用于在蓝鲸智云配置平台（BlueKing CMDB，以下简称 bk-cmdb）中批量创建 Kubernetes workload 资源，作为容器资源管理能力（集群 / 节点 / 命名空间 / workload / Pod / 容器）的一部分。

从源码看，该接口实际挂载在 topo_server 的 kube 服务下，路由定义为POST /createmany/kube/workload/{kind}，其中kind是路径参数（见 service.go），随后通过 apimachinery 客户端转发给 coreservice 完成真正的写入（见 coreservice kube 客户端）。API 网关（APIGW）会在此基础上封装鉴权与bk_app_code等公共参数。

请求参数

接口整体采用"公共参数 + 接口参数"的结构：bk_app_code、bk_app_secret、bk_username、bk_token等为调用方身份凭证（common args），接口自身的业务参数如下。

接口参数（顶层）

kind字段在源码中被定义为WorkloadType枚举，除文档列出的 8 种外，代码中还支持customResource（自定义资源），共 9 种类型，每种类型对应一张独立的存储表（见 types.go）：

data数组的长度上限 200 在源码中由常量WlCreateLimit = 200控制，WlCreateOption.Validate()会校验len(data) > WlCreateLimit并返回"超出限制"错误（见 workload.go）。

data[x]（单个 workload 主体）

从源码看，data数组会依据kind反序列化为对应的 workload 结构体（如Deployment），每个结构体在WorkloadBase基础上扩展Labels、Selector、Replicas、MinReadySeconds、StrategyType、RollingUpdateStrategy等字段（见 deployment.go）。其中：

• replicas在类型定义中是*int64，创建时必填（WorkLoadSpecFieldsDescriptor中标记为 required）。
• bk_namespace_id必须指向当前业务（bk_biz_id）下已存在的命名空间，否则创建会在 namespace 校验环节失败。

selector（工作负载选择器）

源码中LabelSelector结构包含MatchLabels map[string]string与MatchExpressions []LabelSelectorRequirement，语义与 Kubernetes 一致：matchLabels与matchExpressions的结果取AND（见 workload.go）。

match_expressions[x]（匹配表达式）

四种操作符在源码中分别对应常量LabelSelectorOpIn / LabelSelectorOpNotIn / LabelSelectorOpExists / LabelSelectorOpDoesNotExist（见 workload.go），values与操作符的搭配规则与 Kubernetes 官方LabelSelectorRequirement完全一致。

rolling_update_strategy（滚动更新策略）

当strategy_type为RollingUpdate时该字段不为空，其他情况为空。

max_unavailable / max_surge

两个字段结构相同，均采用 Kubernetes 的IntOrString语义——既可以传整数，也可以传百分比字符串：

对应源码IntOrString结构：Type取值IntType = 0/StringType = 1，IntVal int32与StrVal string二选一（见 workload.go）。文档示例中两者均使用整数（max_unavailable=1、max_surge=1），也可将max_surge写成"type": 1, "str_val": "10%"形式的百分比。

请求参数示例

以下 JSON 完整示例创建 1 个 deployment 类型的 workload（位于bk_biz_id=3业务下、bk_namespace_id=1的命名空间中）：

{ "bk_app_code": "esb_test", "bk_app_secret": "xxx", "bk_username": "xxx", "bk_token": "xxx", "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 } } } ] }

该示例与仓库中的集成测试 workload_test.go 高度一致——测试同样构造了test/test2标签、tier In [cache]的匹配表达式、RollingUpdate策略与IntOrString形式的滚动更新参数，可作为验证接口行为的对照样本。

多类型创建说明

• 一次请求中data数组可包含多条记录，上限 200 条；
• kind是整个请求的公共属性，data中所有记录必须属于同一种 workload 类型；
• 若需要直接创建 Pod（不经过 workload），可将kind设为pods，此时 data 项按 Pod 结构传递。

返回结果示例

{ "result": true, "code": 0, "data": { "ids": [ 1 ] }, "message": "success", "permission": null, "request_id": "87de106ab55549bfbcc46e47ecf5bcc7" }

注意：

• 返回的data中的 workloadID 数组顺序与参数中的数组数据顺序保持一致。

也就是说，ids[i]与请求data[i]一一对应，便于调用方将新创建的 workload ID 回写到自己的业务数据中。这一约定在源码中有明确保证：coreservice 按data索引顺序批量申请自增 ID，并逐个写入respData.IDs[idx]（见 workload.go）。

返回结果参数说明

response（公共返回体）

data

服务端处理流程与源码级原理

一次成功的批量创建在服务端大致经历以下环节：

1. 路由与鉴权：topo_server 的 CreateWorkload 先从路径参数解析kind并校验其合法性，然后解码请求体、执行参数校验，最后进行权限校验——资源类型为KubeWorkload、动作为Create，权限点对应"容器工作负载新建"。
2. 事务封装：整个创建过程包裹在AutoRunTxn事务中，创建失败时会整体回滚，避免出现部分 workload 写入成功的情况。
3. 类型分派与校验：coreservice 的 CreateWorkload 根据kind将原始 JSON 反序列化为对应 workload 结构体（WlArrayUnmarshalJSON），并逐条调用ValidateCreate()校验必填字段与取值合法性。
4. ID 分配与 namespace 校验：批量调用 MongoDB 的NextSequences按data顺序预取等量 ID；随后按bk_namespace_id批量查询 namespace，校验其归属业务是否与bk_biz_id一致（含共享 namespace 的CheckPlatBizSharedNs检查）。
5. 写入与审计：数据携带创建人、创建时间等 Revision 信息批量Insert到对应类型表（如cc_DeploymentBase），并生成审计日志（见 topo_server 审计逻辑）。
6. 返回：将按序生成的 ID 数组封装为metadata.RspIDs返回。

常见错误与排查建议

• 权限不足（permission 非空）：调用账号缺少"容器工作负载新建"权限，需在 bk-cmdb 权限中心为对应业务授权。
• kind 非法：kind不在上述枚举范围内时，WorkloadType.Validate()会返回can not support this type of workload（见 types.go），需检查路径/请求中的类型拼写。
• data 超过 200 条：触发WlCreateLimit校验失败，需拆分多次请求。
• namespace 不存在或不属于该业务：GetNamespaceSpec在查询不到全部 namespace 时会返回"未找到"错误（见 workload.go），请先用命名空间查询接口确认bk_namespace_id有效。
• IntOrString 传参不一致：type=0时int_val不能为空、type=1时str_val不能为空，二者不可混填。

相关资源

• 接口文档：batch_create_kube_workload.md
• 路由注册与处理器：topo_server kube service.go、workload.go
• 数据写入实现：coreservice workload.go
• 请求/响应类型与校验规则：src/kube/types/workload.go、src/kube/types/types.go、src/kube/types/deployment.go
• 客户端封装：src/apimachinery/toposerver/kube/kube.go
• 集成测试样例：src/test/topo_server/workload_test.go

• 后端
• 企业应用
• 运维