1. K8s API 基础：API Server 架构、RESTful 设计原则、资源对象模型概述
Kubernetes API 是整个集群的“控制面中枢”。所有对集群状态的查询、变更、编排指令，最终都通过 API Server 暴露的 RESTful 接口完成。理解 API Server 的内部架构、RESTful 设计原则以及资源对象模型，是掌握 K8s API 事务边界与一致性设计的前提。
1.1 API Server 架构
API Server（kube-apiserver）是 Kubernetes 控制面的核心组件，采用无状态水平扩展架构。其内部按请求处理链路划分为多个层级，每个层级负责特定的安全、校验、存储与准入逻辑。
- 认证层（Authentication）： 验证请求者身份，支持 TLS 客户端证书、Bearer Token、HTTP Basic Auth、OpenID Connect 等。
- 授权层（Authorization）： 基于 RBAC、ABAC、Webhook 等策略判断请求者是否有权执行操作。
- 准入控制层（Admission Controllers）： 一组可插拔的插件，在对象持久化前进行变更（Mutating）或校验（Validating）。
- API 路由与版本转换（Routing & Versioning）： 根据请求路径匹配对应的 API 版本（如 v1、apps/v1），并完成内部版本与外部版本之间的转换。
- 存储层（Storage - etcd）： 最终将对象序列化为 JSON 或 Protobuf 格式，写入分布式键值存储 etcd。
1.2 RESTful 设计原则
Kubernetes API 严格遵循 RESTful 架构风格，以资源为中心，通过标准的 HTTP 动词对资源进行增删改查。这种设计使得 API 具有高度的一致性、可缓存性和可发现性。
| HTTP 动词 | K8s 操作 | 幂等性 | 典型路径示例 |
|---|---|---|---|
| GET | 读取单个资源或集合 | 是 | /api/v1/namespaces/{ns}/pods |
| POST | 创建新资源 | 否（每次创建新 UID） | /api/v1/namespaces/{ns}/pods |
| PUT | 全量替换资源 | 是 | /api/v1/namespaces/{ns}/pods/{name} |
| PATCH | 部分更新资源 | 取决于策略 | /api/v1/namespaces/{ns}/pods/{name} |
| DELETE | 删除资源 | 是 | /api/v1/namespaces/{ns}/pods/{name} |
- 资源路径层级：
/apis/{group}/{version}/namespaces/{namespace}/{resource}或/api/{version}/namespaces/{namespace}/{resource}（核心组）。 - 集合与个体： 集合路径（如
/pods）支持GET（列表）和POST（创建）；个体路径（如/pods/{name}）支持GET、PUT、PATCH、DELETE。 - 子资源： 如
/pods/{name}/status、/pods/{name}/log，用于访问资源特定方面的状态或操作。
1.3 资源对象模型概述
Kubernetes 中的所有实体（Pod、Service、Deployment、ConfigMap 等）都被抽象为“资源对象”。每个资源对象遵循统一的元数据结构，并通过 API 版本机制实现演进。
1.3.1 资源对象的通用结构
每个 K8s 资源对象在 API 中表示为 JSON 或 Protobuf 结构，包含以下三个核心部分：
- apiVersion： 标识资源所属的 API 组和版本，如
v1、apps/v1、batch/v1。 - kind： 资源类型名称，如
Pod、Deployment、Service。 - metadata： 包含名称（name）、命名空间（namespace）、UID、资源版本（resourceVersion）、标签（labels）、注解（annotations）等。
- spec： 用户期望的期望状态（desired state），由用户定义。
- status： 集群控制器报告的实际状态（actual state），由系统填充，用户只读。
# 一个典型的 Pod 资源对象 YAML 表示
apiVersion: v1
kind: Pod
metadata:
name: nginx-pod
namespace: default
labels:
app: nginx
spec:
containers:
- name: nginx
image: nginx:1.25
ports:
- containerPort: 80
status:
phase: Running
podIP: 10.1.0.5
conditions:
- type: Ready
status: "True"1.3.2 API 组与版本演进
Kubernetes 通过 API 组（API Group）和版本（Version）对资源进行分类和演进，支持并行存在多个版本，并通过内部版本实现无损转换。
| API 组 | 典型版本 | 包含资源示例 | 说明 |
|---|---|---|---|
| 核心组（空组） | v1 |
Pod, Service, ConfigMap, Secret, Node, Namespace | 最稳定、最基础的资源 |
| apps | v1 |
Deployment, StatefulSet, DaemonSet, ReplicaSet | 工作负载管理 |
| batch | v1 |
Job, CronJob | 批处理与定时任务 |
| networking.k8s.io | v1 |
Ingress, NetworkPolicy | 网络策略与入口 |
| rbac.authorization.k8s.io | v1 |
Role, ClusterRole, RoleBinding, ClusterRoleBinding | RBAC 权限控制 |
1.4 关键设计理念：声明式与最终一致性
Kubernetes API 的设计核心是“声明式”（Declarative）而非“命令式”（Imperative）。用户通过 API 提交期望状态（spec），集群中的控制器（Controller）持续观察实际状态（status）并驱动其向期望状态收敛。这种模型天然支持最终一致性（Eventual Consistency），也是理解 API 事务边界的基础。