APIServer 本质上就是一个特殊的 RESTful HTTPS 服务器 。从协议底层看，它接收的仍然是标准的 HTTP/1.1 或 HTTP/2 请求，但语义、认证方式、状态管理哲学与普通业务 HTTP API 差异极大。
一、APIServer 接收的请求长什么样？
1.1 一个真实的完整请求（ kubectl create pod 的底层）
当你在终端执行：
kubectl run nginx --image=nginx
kubectl 实际上向 APIServer 发送了如下 HTTP 请求（简化版）：
POST /api/v1/namespaces/default/pods HTTP/2
Host: 10.96.0.1:443
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...
Content-Type: application/json
Accept: application/json
{
"apiVersion": "v1",
"kind": "Pod",
"metadata": {
"name": "nginx",
"namespace": "default",
"labels": {
"run": "nginx"
}
},
"spec": {
"containers": [{
"name": "nginx",
"image": "nginx",
"resources": {}
}]
}
}
APIServer 返回：
HTTP/2 201 Created
Content-Type: application/json
{
"kind": "Pod",
"apiVersion": "v1",
"metadata": {
"name": "nginx",
"uid": "a3f5c8d2-...",
"resourceVersion": "1234567",
"creationTimestamp": "2026-05-12T11:51:00Z"
},
"spec": { ... },
"status": { "phase": "Pending" }
}
1.2 URI 的固定结构（RESTful 资源路径）
K8s API 的 URL 不是随意设计的，而是严格的资源层级：
/api/v1/namespaces/{namespace}/pods/{name}
/api/v1/namespaces/{namespace}/services/{name}
/apis/apps/v1/namespaces/{namespace}/deployments/{name}
/apis/networking.k8s.io/v1/namespaces/{namespace}/ingresses/{name}
|------------------|--------------------------------------------|
| URL 段 | 含义 |
| /api/v1 | 核心 API 组（Pod/Service/Node/Namespace 等） |
| /apis/apps/v1 | 命名 API 组（Deployment/StatefulSet/DaemonSet） |
| /namespaces/{ns} | 命名空间作用域 |
| /{resource} | 资源类型（复数小写） |
| /{name} | 具体资源实例 |
| /{name}/status | 子资源：仅更新状态（权限可独立控制） |
| /{name}/scale | 子资源：扩缩容专用端点 |
| /{name}/log | 子资源：Pod 日志（连接至 kubelet） |
| /{name}/exec | 子资源：远程执行（WebSocket 升级） |
二、与普通 HTTP API 的六大核心差异
差异 1：声明式（Declarative）vs 命令式（Imperative）
|----------|---------------------|------------------------------------------------|
| 维度 | 普通业务 HTTP API | K8s APIServer |
| 哲学 | "去做这件事"（命令） | "我要这个状态"（声明） |
| 请求语义 | POST /orders → 创建订单 | POST /pods → 声明"我想要一个 Pod" |
| 幂等性 | 通常不保证 | 绝对幂等：相同 YAML 重复 apply，结果不变 |
| 状态收敛 | 业务系统自己维护 | APIServer 只负责持久化期望状态，实际状态由 Controller 异步收敛 |
例子：
- 普通 API：POST /send-sms 执行一次就发一条短信，重复调用发多条。
- K8s API：POST /pods 如果 Pod 已存在且 spec 未变，直接返回 200/409，不会创建第二个。
差异 2：内置全局版本控制（ResourceVersion）
每个 K8s 资源都有 resourceVersion，本质是 etcd 的 MVCC 版本号：
"metadata": {
"resourceVersion": "1234567"
}
作用：
- 乐观并发控制 ：PUT 请求带 If-Match: "1234567"，若服务端版本已变，返回 409 Conflict，防止覆盖。
- Watch 断点续传 ：客户端断开重连时携带 resourceVersion，APIServer 从该版本之后推送事件。
普通 HTTP API 通常没有 ：需要自己设计 version 字段或 ETag 机制。
差异 3：Watch 机制（长轮询/流式事件）
这是 K8s API 最独特的能力，普通 HTTP API 极少需要：
GET /api/v1/namespaces/default/pods?watch=1&resourceVersion=1234567 HTTP/1.1
Accept: application/json
返回不是一次性 JSON，而是持续的 Chunked Transfer 流：
{"type":"ADDED", "object":{...}}
{"type":"MODIFIED", "object":{...}}
{"type":"DELETED", "object":{...}}
谁在用 Watch？
- kubelet：Watch 本节点 Pod 变化，决定创建/销毁容器
- Controller：Watch Deployment，发现副本数变化后创建 ReplicaSet
- Scheduler：Watch 未绑定节点的 Pod，执行调度
普通 HTTP API：如果需要实时推送，通常用 WebSocket 或 SSE，但语义与 Watch 完全不同。
差异 4：FieldSelector / LabelSelector（服务端过滤）
GET /api/v1/pods?fieldSelector=status.phase=Running,spec.nodeName=node-01
GET /api/v1/pods?labelSelector=app=payment,env=prod
APIServer 在收到请求后，会将过滤条件下推至 etcd，只返回匹配的资源。
普通 HTTP API ：通常是 GET /api/items?status=active，由业务服务自己查数据库过滤。K8s 的 Selector 是基础设施级能力 ，且支持集合运算（In、NotIn、Exists）。
差异 5：子资源（Subresource）与权限精细化
普通 API 通常是 /resource/{id} 平铺，K8s 有子资源概念：
|--------|---------------------------|-----------------------------------------|
| 子资源 | URL | 独立权限 |
| Status | /pods/{name}/status | 可单独授权（如 kubelet 只允许更新 status，不允许改 spec） |
| Log | /pods/{name}/log | 实际代理到 kubelet，权限可独立控制 |
| Exec | /pods/{name}/exec | WebSocket 升级，独立 RBAC 规则 |
| Scale | /deployments/{name}/scale | HPA 只需要 scale 权限，不需要 full update 权限 |
| Bind | /pods/{name}/binding | Scheduler 专用，将 Pod 绑定到节点 |
金融级意义：等保要求最小权限，子资源让 RBAC 可以精确到"只能看日志，不能删 Pod"。
差异 6：内置认证授权链（不是"加个 JWT 中间件"那么简单）
APIServer 的请求在到达业务逻辑前，必须经过三道安检：
客户端请求
│
├──► 1. TLS 握手（mTLS 客户端证书验证，或 Token 校验）
│
├──► 2. 认证（Authentication）：你是谁？
│ • X509 客户端证书（kubelet/controller-manager）
│ • Bearer Token（ServiceAccount JWT / OIDC / Webhook）
│ • Bootstrap Token（节点加入集群）
│
├──► 3. 授权（Authorization）：你能做什么？
│ • RBAC（Role/ClusterRole + RoleBinding）
│ • Node 授权（kubelet 只能操作本节点 Pod）
│ • Webhook（对接银行 AD/LDAP/Keycloak）
│
└──► 4. 准入控制（Admission Control）：请求是否合规？
• Mutating（修改请求，如自动注入 Sidecar）
• Validating（校验请求，如 OPA/Kyverno 策略拦截）
普通 HTTP API ：通常只有一层 Authorization: Bearer xxx + 业务层鉴权，没有 K8s 这种协议级、标准化的多阶段安检。
三、APIServer 的协议细节（与普通 HTTP 的微妙差异）
3.1 内容协商：JSON vs Protobuf
APIServer 同时支持两种序列化：
默认：JSON（人类可读，kubectl 默认）
Accept: application/json
高性能：Protobuf（内部组件优先使用，带宽和 CPU 节省 3-5 倍）
Accept: application/vnd.kubernetes.protobuf
银行级优化：集群内部组件（kubelet、controller-manager）应强制使用 Protobuf，减少 APIServer 序列化压力。
3.2 动词（Verb）与 HTTP 方法的映射
K8s 在 RBAC 中使用逻辑动词，不完全等于 HTTP 方法：
|---------|---------------------------|------------------------------------------|
| HTTP 方法 | K8s RBAC Verb | 说明 |
| GET | get / list / watch | list 是集合查询，get 是单个资源，watch 是长连接 |
| POST | create | |
| PUT | update | 全量替换 |
| PATCH | patch | 部分更新（JSON Patch / Strategic Merge Patch） |
| DELETE | delete / deletecollection | |
特殊 ：kubectl apply 底层是 PATCH（Strategic Merge Patch），不是简单的 PUT。
3.3 Strategic Merge Patch（K8s 独创）
普通 HTTP API 的 PATCH 通常是 JSON Merge Patch 或 JSON Patch（RFC 6902）。K8s 发明了Strategic Merge Patch，解决容器列表的合并语义：
原 Deployment
containers:
- name: nginx
image: nginx:1.19 - name: sidecar
image: busybox
用户 PATCH（只改 nginx 版本）
containers:
- name: nginx
image: nginx:1.20
K8s Strategic Merge 结果：保留 sidecar，只更新 nginx
普通 JSON Merge Patch 结果：可能直接替换整个 containers 数组，sidecar 丢失
关键 ：patchStrategy:"merge" patchMergeKey:"name" 注解定义了合并策略，这是普通 HTTP API 没有的。
四、金融级视角：APIServer 调用的安全与审计
4.1 审计日志（等保 3.0 要求）
APIServer 的每个请求都会生成结构化审计事件：
{
"kind": "Event",
"apiVersion": "audit.k8s.io/v1",
"level": "RequestResponse",
"timestamp": "2026-05-12T11:51:00Z",
"verb": "create",
"user": {
"username": "zhangsan@bank.com",
"groups": ["digital-banking", "system:authenticated"]
},
"sourceIPs": ["10.0.1.15"],
"objectRef": {
"resource": "pods",
"namespace": "prod-core",
"name": "payment-api-xxx"
},
"requestObject": { ... }, // 请求体（敏感资源可能省略）
"responseObject": { ... }, // 响应体
"responseStatus": { "code": 201 }
}
银行要求：审计日志必须留存 6 个月，WORM 存储，对接 SIEM。
4.2 API Priority and Fairness（APF）：防止请求洪峰
银行大集群中，某个失控的 CI Job 批量 List Pod 可能挤爆 APIServer。APF 将请求分级：
FlowSchema：区分系统组件、人类用户、服务账号
priorityLevelConfiguration:
- name: system-high # kubelet、controller 高优
- name: operator-medium # 运维人员中优
- name: ci-low # CI 流水线低优，限流排队
普通 HTTP API ：通常用 Nginx/Envoy 限流，但缺乏 K8s 这种基于身份和动词的内置优先级队列。
五、一句话讲清差异
APIServer 的 API 在协议层面就是 HTTP/JSON（或 Protobuf），但在语义层面是"面向终态的、版本化的、事件驱动的、带内置安检链的分布式资源控制系统"。
它与普通 HTTP API 的关系，类似于**"SQL 与 Excel 都是表格"**------表面都是行列数据，但底层哲学和适用域完全不同。