蓝鲸配置平台（bk-cmdb）批量删除 Kubernetes Pod 接口实战指南：参数、权限与底层实现解析-开发者社区

后端
企业应用
运维

【免费下载链接】bk-cmdb

蓝鲸智云配置平台(BlueKing CMDB)

项目地址：https://gitcode.com/gh_mirrors/bk/bk-cmdb

导读：本文围绕蓝鲸配置平台（BlueKing CMDB，bk-cmdb）中“批量删除 Pod”这一容器管理 API（版本 v3.12.1+，权限要求“容器 Pod 删除”），完整讲解接口请求/返回结构与调用示例，并结合仓库源码剖析参数校验、权限鉴权、共享集群校验、级联删除容器与审计日志生成等底层实现链路。读完本文，你将能够独立构造并调用该接口完成 Kubernetes Pod 的批量删除，并理解删除操作在 bk-cmdb 容器拓扑体系中的完整执行过程。

接口概述

“批量删除 Pod”是 bk-cmdb 容器资源管理能力的一部分。随着蓝鲸配置平台在 v3.12.1 版本引入对 Kubernetes 容器编排资源的纳管（Pod、Workload、Namespace、Node、Cluster 等），CMDB 可以同步并维护集群中的 Pod 实例数据。该接口用于按业务（biz）与 Pod 在 CMDB 中的自增主键（cc ID）批量删除 Pod 记录。

该接口同时存在于两套 API 网关文档体系中：

蓝鲸 API 网关（APIGW）后端文档：docs/apidoc/apigw/backend/zh/batch_delete_kube_pod.md（以及对应英文版 docs/apidoc/apigw/backend/en/batch_delete_kube_pod.md）
CMDB 内部 OpenAPI 文档：docs/apidoc/cc/zh_hans/batch_delete_kube_pod.md

两套文档描述的是同一删除能力：data数组中按业务聚合需要删除的 Pod，每个业务下通过ids指定 Pod 的 CMDB 内部 ID。需要特别注意的是，该删除操作删除的是CMDB 中纳管的 Pod 实例数据（即资源入库后的台账数据），删除动作发生一次，Pod 记录即从 CMDB 库中移除。

请求参数详解

通用参数（common args）

与 CMDB 其他 OpenAPI 一致，调用方需在请求体中携带身份认证与调用方信息，包括：

字段	类型	必选	描述
bk_app_code	string	是	应用 ID，用于标识调用方应用
bk_app_secret	string	是	应用密钥，用于应用级鉴权
bk_username	string	否	操作者用户名（用户名与 token 至少提供其一）
bk_token	string	否	用户登录票据（用户名与 token 至少提供其一）

接口参数

字段	类型	必选	描述
data	object array	是	要删除的 Pod 信息数组，`data`里所有 Pod 总和最多200 条

data 数组元素

字段	类型	必选	描述
bk_biz_id	int	是	业务 ID
ids	int array	是	要删除的 Pod 的 cc ID 数组，`data`里所有 Pod 的 ID 总和最多 200 条

参数约束的源码证据：上述“200 条”限制并非文档单方面约定，而是代码中的硬性校验。在 src/kube/types/pod.go 的DeletePodsOption.Validate()中可以看到：

data为空时返回CCErrCommParamsNeedSet（必填参数缺失）；
data长度超过common.BKMaxWriteOpLimit时返回CCErrCommXXExceedLimit；
每个data元素中bk_biz_id为 0 时返回业务 ID 缺失错误；
每个元素ids为空时返回 ID 缺失错误；
累加所有元素中的 Pod ID 数量，超过common.BKMaxWriteOpLimit（即 200）时返回超限错误。

DeletePodsOption与DeletePodData的结构定义（src/kube/types/pod.go）与文档字段一一对应：

// DeletePodsOption delete pods option, pods are aggregated by biz id type DeletePodsOption struct { Data []DeletePodData `json:"data"` } // DeletePodData delete pods data, including biz id and pods in it type DeletePodData struct { BizID int64 `json:"bk_biz_id"` PodIDs []int64 `json:"ids"` }

由此可见，data支持一次请求内携带多个业务（多个bk_biz_id），每个业务下挂各自待删除的 Pod ID 列表，但全量总和不得超过 200。

请求参数示例

以 CMDB 内部 OpenAPI 的完整请求体为例（需带通用鉴权参数）：

{ "bk_app_code": "code", "bk_app_secret": "secret", "bk_username": "xxx", "bk_token": "xxxx", "data": [ { "bk_biz_id": 123, "ids": [ 5, 6 ] } ] }

通过 APIGW 调用时，通用鉴权参数由网关上下文注入，请求体仅需携带业务参数（参考 docs/apidoc/apigw/backend/zh/batch_delete_kube_pod.md）：

{ "data": [ { "bk_biz_id": 123, "ids": [ 5, 6 ] } ] }

返回结果示例与参数说明

返回结果示例

{ "result": true, "code": 0, "message": "", "permission": null, "request_id": "87de106ab55549bfbcc46e47ecf5bcc7" }

返回结果参数（response）

字段	类型	描述
result	bool	请求成功与否。true: 请求成功；false: 请求失败
code	int	错误编码。0 表示 success，>0 表示失败错误
message	string	请求失败返回的错误信息
permission	object	权限信息（无权限时返回）
request_id	string	请求链 id

其中code、message、permission、request_id均来自 CMDB 统一的响应封装metadata.BaseResp（定义见 src/common/metadata/result.go）。APIGW 后端文档的响应示例中省略了request_id，但该字段在 CMDB 内部 OpenAPI 的实际响应中存在，用于全链路日志追踪。

权限要求与鉴权实现

接口文档明确标注：权限：容器 Pod 删除。这是 bk-cmdb 接入蓝鲸权限中心（IAM）后定义的标准权限动作。

在源码中可以找到完整的权限动作定义与映射关系：

权限动作 ID：delete_container_pod，中文名“容器Pod删除”，定义于 src/ac/iam/types.go，名称映射见 src/ac/iam/initial_actions.go；
权限动作被注册进默认动作分组，见 src/ac/iam/initial_action_groups.go；
资源类型：CMDB 侧 Pod 资源类型为kube_pod，定义于 src/ac/meta/resource.go；
动作与资源的绑定：在 src/ac/iam/adaptor.go 中，meta.KubePod资源的meta.Delete动作映射到DeleteContainerPod，meta.Create映射到CreateContainerPod，meta.Find映射到ViewBusinessResource。

也就是说，调用者必须拥有对应业务下“容器 Pod 删除”权限，否则请求会在鉴权阶段被拦截，返回permission信息。

删除流程的底层实现解析

1. 路由入口：topo_server 的 DeletePods

该接口的 HTTP 路由注册于 src/scene_server/topo_server/service/kube/service.go：

utility.AddHandler(rest.Action{Verb: http.MethodDelete, Path: "/deletemany/kube/pod", Handler: s.DeletePods})

对应的处理器为 src/scene_server/topo_server/service/kube/pod.go 中的DeletePods，其执行链路为：

参数解析：ctx.DecodeInto将请求体解析为types.DeletePodsOption，随后调用opt.Validate()完成上文所述的 200 条上限、业务 ID、ID 数组等校验；
权限鉴权：遍历opt.Data，为每个业务构造acmeta.ResourceAttribute{Type: acmeta.KubePod, Action: acmeta.Delete, BusinessID: data.BizID}，调用AuthManager.Authorize统一鉴权，任一业务无权限即返回RespNoAuth；
数据预检：checkDelPodData汇总所有ids，通过CoreService().Kube().ListPod按bk_pod_id in ids查询现存 Pod；若全部已不存在（len(pods) == 0），直接返回成功（幂等行为）；
共享集群校验：checkDeletePodSharedNs会比对 Pod 实际归属业务与请求携带业务，若 Pod 的命名空间属于共享命名空间（shared namespace）场景，则调用Logics.KubeOperation().CheckPlatBizSharedNs校验是否允许该业务删除，防止越权删除共享集群资源（src/scene_server/topo_server/service/kube/pod.go）；
生成审计日志：auditlog.NewKubeAudit(...).GeneratePodAuditLog为每个待删除 Pod 生成AuditDelete类型的审计记录；
事务执行：通过CoreService().Txn().AutoRunTxn开启分布式事务，事务内先调用CoreService().Kube().DeletePods执行真实删除，成功后SaveAuditLog落审计日志；任一步失败则整体回滚。

2. RPC 封装：apimachinery 的 DeletePods

topo_server 通过 apimachinery 客户端调用 core_service 的 RPC 接口。封装定义于 src/apimachinery/coreservice/kube/api.go：

// DeletePods delete pods api func (k *kube) DeletePods(ctx context.Context, h http.Header, opt *types.DeletePodsByIDsOption) errors.CCErrorCoder { resp := new(metadata.Response) subPath := "/deletemany/pod" err := k.client.Delete(). WithContext(ctx). Body(opt). SubResourcef(subPath). WithHeaders(h). Do(). Into(resp) ... }

这里透传的DeletePodsByIDsOption仅包含ids字段（src/kube/types/pod.go），即经过 topo_server 校验与聚合后的纯 ID 列表。

3. 数据落库：coreservice 的 DeletePods

真正操作 MongoDB 的逻辑位于 src/source_controller/coreservice/service/kube/pod.go，其核心步骤：

级联删除容器：先以bk_pod_id in ids为条件删除容器表cc_ContainerBase（types.BKTableNameBaseContainer）中的数据——Pod 删除会连带删除其下所有容器记录；
找出受影响的节点：在删除 Pod 前，先对 Pod 表cc_PodBase（types.BKTableNameBasePod，定义见 src/kube/types/types.go）按bk_node_id字段Distinct出这些 Pod 关联的节点 ID；
删除 Pod 记录：以id in ids为条件从cc_PodBase表删除 Pod 数据；
回写节点状态：调用getNodeIDsWithoutPod并发统计每个受影响节点上是否还残留 Pod，若某节点已无任何 Pod，则通过updateNodeHasPodField将该节点的has_pod字段置为 false，保证容器拓扑中节点状态的准确性。

4. 事件与缓存联动（删除后的后续影响）

Pod 数据被删除后，CMDB 的事件订阅与缓存体系会自动感知变化：

事件监听：WatchKubePod动作（kube_pod，定义于 src/ac/meta/meta.go）对应的 watch 事件可通过事件服务器对外推送，依赖方可持续消费 Pod 删除事件；
拓扑缓存：缓存服务（cacheservice）的 biz-topo 模块会 watch kube 相关表（见 src/source_controller/cacheservice/cache/biz-topo/watch/kube.go），Pod 删除后相关拓扑缓存随之更新。

调用注意事项与最佳实践

数量上限：单次请求data中所有ids总和最多 200 条，超出将返回CCErrCommXXExceedLimit错误。需要删除更多 Pod 时应分批调用。
幂等性：若请求中的 Pod ID 已全部不存在，接口直接返回成功，不会报错，适合重复调用场景（源码见 src/scene_server/topo_server/service/kube/pod.go）。
权限前置：调用前需为对应业务的操作用户授予“容器 Pod 删除”权限；无权限时响应result=false并携带permission字段，调用方应根据该字段引导用户完成权限申请。
共享集群场景：当 Pod 位于共享集群的共享命名空间、且请求业务并非 Pod 实际归属业务时，删除会被CheckPlatBizSharedNs拦截。请确保bk_biz_id与 Pod 实际归属业务一致。
级联语义：删除 Pod 会连带删除其下全部容器数据，并自动更新节点has_pod状态，无需额外调用其他接口。
请求链追踪：建议记录返回的request_id，排查问题时可通过该 ID 串联全链路日志。