Kubernetes 官方文档怎样识别已弃用 API

Kubernetes 的 API 弃用不是看到一个 v1beta1 就直接改成 v1。在规模较大的集群里，YAML、控制器、脚本和旧版客户端可能分别调用不同入口，真正需要确认的是：哪个 group/version/resource 被调用、它将在什么版本停止服务、迁移后是否有字段语义变化。

官方地址：https://kubernetes.io/docs/reference/using-api/deprecation-guide/

最稳妥的判断顺序是“官方文档定范围，Warning 定请求，审计和指标定调用面”。这样得到的是一份可交给迁移负责人的证据清单，而不是只在仓库里搜索字符串。

先把弃用问题从版本表中圈出来

官方 Deprecated API Migration Guide 按 Kubernetes 版本列出停止服务的 API，并给出替代版本和 notable changes。先记录四个字段：API group、version、resource、removed release。比如 batch/v1beta1 的 CronJob 在 v1.25 停止服务，迁移目标是 batch/v1；Ingress 的旧版本迁移还伴随 pathType 必填等语义变化。

这一步解决的是“文档上已经知道什么”，但不能证明你的集群仍在使用它。不要把历史清单里的旧 apiVersion 当成线上调用证据，也不要因为对象已经存储过就认为旧 endpoint 还在被访问。

用响应 Warning 找到真实请求

Kubernetes 从 1.19 开始，对已弃用 REST API 的请求返回 Warning 响应头。它适合在客户端、网关或 API 调试链路中快速确认“这次请求确实命中了弃用接口”。下面的示例只读取接口，不修改对象：

# 读取资源接口的响应头，保留 Warning 以便判断是否命中弃用 API
kubectl get --raw='/apis/batch/v1beta1/cronjobs' -v=6 2>&1 | grep -i 'warning'

# 也可以在客户端日志中记录 group、version 和 resource，方便回溯调用方
# 生产环境不要把完整 Authorization 头或敏感对象内容写入日志

如果没有看到 Warning，只能说明这次请求没有返回该提示，不能证明整个集群没有旧客户端。批量控制器、定时任务和外部集成往往不会经过你正在观察的那条命令。

让审计事件给出调用身份和移除版本

启用 Kubernetes Audit 后，可以在审计事件里查找 k8s.io/deprecated: "true"。如果官方为该 API 标出了目标移除版本，还会出现 k8s.io/removed-release。审计记录能把资源请求与 user、userAgent、sourceIPs 等字段联系起来，适合定位“是谁还在调用”。

# 从导出的审计 JSONL 中筛选已弃用 API 请求
# jq 只读取标记字段，避免把完整对象内容带入排查输出
jq 'select(.annotations["k8s.io/deprecated"] == "true")
  | {user: .user.username, verb: .verb, uri: .requestURI,
     removed: .annotations["k8s.io/removed-release"]}' audit.log

# 对输出按 userAgent 和 requestURI 汇总，帮助拆分控制器、脚本和人工客户端
# 汇总前先确认审计策略确实记录了 requestMetadata 与 requestObject 所需字段

审计证据的价值在于身份和时间范围，但它受审计策略、保留周期和采集链路影响。若历史窗口不完整，应把结论写成“在观察窗口内未发现”，不要写成绝对的“没有调用”。

用指标补齐集群级调用面

API Server 会暴露 apiserver_requested_deprecated_apis 指标。它包含 group、version、resource、subresource 和 removed_release 标签，可与 apiserver_request_total 按维度关联。指标适合回答“哪些资源仍有流量”，审计更适合回答“哪个身份发起了请求”，两者不要混为一谈。

# 查询仍有请求的已弃用 API，先看移除版本和资源维度
apiserver_requested_deprecated_apis > 0

# 只聚合调用量，避免面板被 userAgent 等高基数标签放大
sum by (group, version, resource, subresource, removed_release) (
  apiserver_requested_deprecated_apis
)

若指标存在但审计里找不到身份，通常是观察窗口、审计策略或指标抓取范围不同；若 Warning、审计和指标都没有信号，也只代表当前采集面未发现证据。

把识别结果变成迁移清单

建议每个弃用项保留一行记录：group/version/resource、来源证据、调用身份或 userAgent、removed_release、目标 API、字段差异、负责人和回归窗口。这样可以把“文档已弃用”与“线上仍在调用”分开排优先级。

上线前用禁用旧 API 做一次演练

迁移完成后，可以在隔离环境按官方迁移指南提供的方式，用 API Server 的 --runtime-config=/=false 禁用目标旧版本，模拟未来停止服务的结果。演练的重点不是“命令成功”本身，而是确认控制器、部署脚本和外部客户端都能切换到新版本。

# 在隔离集群的 API Server 参数中禁用一个已完成迁移的旧版本
# 先确认回滚方案和控制面配置来源，再重启或滚动更新 API Server
--runtime-config=admissionregistration.k8s.io/v1beta1=false

# 演练后检查控制器日志、审计事件和发布流水线结果
# 发现旧调用时回到调用方修复，不要只改数据库中的已存对象

最终的完成标准是：文档中的替代版本已确认，旧请求在 Warning、审计和指标观察窗口内归零，禁用旧版本的隔离演练没有新的调用方。存储对象是否能被新版本读取，还要根据具体资源的官方迁移说明单独确认。

几个容易混淆的问题

看到 v1beta1 就一定要立刻迁移吗？

不应只按字符串判断。要先对照官方弃用指南确认该资源的停止服务版本，再结合集群实际请求证据排优先级；Alpha、Beta 和 GA 的生命周期规则也不同。

没有 Warning 是否代表可以不管？

不是。Warning 是单次请求证据，批处理、控制器或外部客户端可能没有出现在你的观察路径中，应该继续看审计和指标。

kubectl convert 能替代迁移评审吗？

不能。官方文档明确提示转换可能使用不理想的默认值，具体资源仍需查 API reference 和迁移说明；转换工具本身也不是默认安装的 kubectl 子命令。

识别已弃用 API 的关键不是记住一张版本表，而是建立“官方定义—实际请求—调用身份—迁移验证”的闭环。规模越大，越应该把四类证据分开保存，再按移除版本和调用方责任推进迁移。