4. 弃用检测原理：API Request 审计、日志分析、Metrics 指标监控

在 Kubernetes 集群升级节点池之前，必须系统性地识别当前集群中所有正在使用的已弃用 API。弃用检测并非单一手段，而是需要从 API Request 审计、日志分析 和 Metrics 指标监控 三个维度构建立体化检测体系。每种方法覆盖不同的数据源和场景，互为补充。

4.1 三维检测体系总览

下表对比了三种检测方法的核心差异与适用场景：

4.2 API Request 审计：精确到每一次调用

Kubernetes 审计日志记录了每个经过 API Server 的请求的完整元数据，包括请求的用户、资源、动词、响应状态码以及请求的 API 版本。通过启用审计策略并配置后端（如 Webhook 或日志文件），可以捕获所有使用已弃用 API 版本的请求。

关键审计字段：

• requestURI：包含请求的完整 API 路径，如 /apis/apps/v1beta1/deployments。
• responseStatus.code：响应码，重点关注 404（资源不存在）和 410（资源已移除）。
• user.username：发起请求的用户或 ServiceAccount。
• objectRef.resource 和 objectRef.apiVersion：明确标识被访问的资源及其 API 版本。

示例审计日志片段（已格式化）：

{
  "kind": "Event",
  "apiVersion": "audit.k8s.io/v1",
  "level": "RequestResponse",
  "auditID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "stage": "ResponseComplete",
  "requestURI": "/apis/apps/v1beta1/namespaces/default/deployments/my-app",
  "verb": "get",
  "user": {
    "username": "system:serviceaccount:default:my-sa",
    "groups": ["system:serviceaccounts", "system:authenticated"]
  },
  "sourceIPs": ["10.0.0.5"],
  "responseStatus": {
    "code": 200
  },
  "objectRef": {
    "resource": "deployments",
    "apiVersion": "apps/v1beta1",
    "namespace": "default",
    "name": "my-app"
  },
  "requestReceivedTimestamp": "2025-03-15T10:30:00.123456Z"
}

4.3 日志分析：捕获组件内部的弃用警告

Kubernetes 组件（特别是 kube-apiserver 和 kube-controller-manager）在启动或处理请求时，会在日志中输出弃用警告。这些警告通常以 WARNING 级别记录，包含明确的弃用提示信息。

常见日志模式：

• WARNING: the v1beta1 API version is deprecated and will be removed in a future release
• WARNING: apps/v1beta1 Deployment is deprecated in v1.9+, unavailable in v1.16+
• WARNING: use apps/v1 instead of extensions/v1beta1

使用 kubectl logs 配合 grep 快速扫描：

# 扫描 kube-apiserver 日志中的弃用警告
kubectl logs -n kube-system kube-apiserver-master-0 --tail=10000 | grep -i "deprecated" | grep -i "v1beta1"

# 使用 jq 解析结构化日志（如果启用 JSON 输出）
kubectl logs -n kube-system kube-apiserver-master-0 --tail=10000 | jq 'select(.msg | test("deprecated")) | {timestamp: .ts, msg: .msg}'

4.4 Metrics 指标监控：实时趋势与告警

kube-apiserver 暴露的 /metrics 端点提供了丰富的 API 调用统计指标。通过 Prometheus 采集这些指标，可以实时监控已弃用 API 的使用情况，并设置告警规则。

核心指标：

PromQL 查询示例：

# 查询所有使用 v1beta1 API 的请求速率（每分钟）
sum(rate(apiserver_request_total{version=~".*v1beta1.*"}[5m])) by (resource, verb, version)

# 查询响应码为 410（Gone）的请求，表示访问了已移除的 API
sum(rate(apiserver_request_total{code="410"}[5m])) by (resource, verb)

# 设置告警：当已弃用 API 请求速率超过阈值时触发
alert: DeprecatedAPIUsageHigh
expr: sum(rate(apiserver_request_total{version=~".*v1beta1.*"}[5m])) > 0.1
for: 10m
labels:
  severity: warning
annotations:
  summary: "已弃用 API 请求速率过高（当前值：{{ $value }}/s）"

4.5 三维检测体系架构图

下图展示了三种检测方法在集群中的部署位置和数据流向：

4.6 检测优先级与组合策略

在实际操作中，建议按以下优先级组合使用三种检测方法：

1. 第一优先级：Metrics 指标监控 —— 部署 Prometheus 告警规则，实时发现已弃用 API 的突发流量，避免影响升级窗口。
2. 第二优先级：API Request 审计 —— 启用审计日志并配置长期存储，用于离线分析和精确溯源，生成详细的弃用 API 使用报告。
3. 第三优先级：日志分析 —— 作为补充手段，捕获审计和 Metrics 可能遗漏的组件内部弃用警告，特别是来自控制器和调度器的自引用请求。