3. API Server 接口调用基础：RESTful API 设计原则、资源路径、HTTP 方法与状态码

Kubernetes API Server（kube-apiserver）是整个控制平面的唯一入口，所有对集群状态的查询、变更、准入控制以及组件间的通信，最终都表现为对 API Server 的 RESTful 接口调用。理解其设计原则、资源路径规范以及 HTTP 方法与状态码的语义，是编写可靠客户端、调试集群问题以及构建准入策略的基础。

3.1 RESTful 设计原则在 Kubernetes 中的体现

Kubernetes API 严格遵循 REST（Representational State Transfer）架构风格，核心原则包括：

• 资源导向：一切皆资源（Pod、Service、Secret、Deployment 等），每个资源拥有唯一的 URI。
• 无状态通信：每个请求包含所有必要信息，服务端不保存客户端上下文。
• 统一接口：使用标准的 HTTP 方法（GET、POST、PUT、PATCH、DELETE）对资源进行 CRUD 操作。
• 自描述消息：资源表示（JSON/YAML）包含类型（kind）、API 版本（apiVersion）和元数据（metadata）。

3.2 资源路径（URI）结构规范

API Server 的请求路径遵循严格的层级结构，用于定位资源类型、命名空间以及资源实例。路径结构分为三类：

路径中常见的占位符与子资源：

• {name}：资源实例名称，如 /api/v1/namespaces/default/pods/my-pod。
• /status：子资源，用于读取或更新资源状态（由控制器写入）。
• /scale：子资源，用于手动或自动扩缩容。
• /proxy：子资源，用于代理访问 Pod 或 Service 的端口。
• /bindings：子资源，用于将 Pod 绑定到特定节点。

3.3 HTTP 方法与对应操作语义

Kubernetes API 使用标准的 HTTP 方法对资源执行操作，每种方法对应特定的语义和幂等性特征：

3.4 常用 HTTP 状态码与含义

API Server 返回的 HTTP 状态码遵循 RFC 7231 标准，但在 Kubernetes 上下文中具有特定语义：

3.5 实际调用示例：创建与查询 Secret

以下示例展示如何使用 curl 直接调用 API Server 创建和查询 Secret 资源，演示路径、方法与状态码的配合：

# 1. 创建 Secret（POST）
curl -k -X POST \
  -H "Authorization: Bearer <>" \
  -H "Content-Type: application/json" \
  -d '{
    "apiVersion": "v1",
    "kind": "Secret",
    "metadata": { "name": "db-secret", "namespace": "default" },
    "type": "Opaque",
    "data": { "password": "cGFzc3dvcmQxMjM=" }
  }' \
  https://api-server:6443/api/v1/namespaces/default/secrets

# 预期响应：201 Created，返回完整的 Secret 对象（data 字段被自动隐藏）

# 2. 查询 Secret（GET）
curl -k -X GET \
  -H "Authorization: Bearer <>" \
  https://api-server:6443/api/v1/namespaces/default/secrets/db-secret

# 预期响应：200 OK，返回 Secret 元数据（data 字段不显示原始值）

# 3. 更新 Secret 标签（PATCH）
curl -k -X PATCH \
  -H "Authorization: Bearer <>" \
  -H "Content-Type: application/merge-patch+json" \
  -d '{"metadata": {"labels": {"env": "production"}}}' \
  https://api-server:6443/api/v1/namespaces/default/secrets/db-secret

# 预期响应：200 OK，返回更新后的 Secret 对象

3.6 常见错误排查清单

在调用 API Server 时，以下是最常见的错误模式及其根因：

• 401 Unauthorized： 无效、证书未配置或过期。检查 ~/.kube/config 中的凭据。
• 403 Forbidden：RBAC 规则缺失。使用 kubectl auth can-i 验证权限。
• 404 Not Found：资源不存在或路径拼写错误（注意大小写和命名空间）。
• 409 Conflict：resourceVersion 过期。重新获取最新资源版本后重试 PUT。
• 422 Unprocessable Entity：请求体校验失败或准入 Webhook 拒绝。检查字段格式和 Webhook 日志。
• 429 Too Many Requests：超出 API Server 的 --max-requests-inflight 限制。实现指数退避重试。