容器与云原生 / 系统课时
Kubernetes API 资源模型
Kubernetes API 资源模型
Kubernetes 把集群中的工作负载、配置和权限都表示为 API 资源对象。本课将拆解对象的身份信息、期望状态与实际状态,并通过一个 Deployment 清单观察控制器如何围绕这些字段持续协调。
学习目标
- 说明
apiVersion、kind、metadata、spec和status的职责。 - 理解期望状态与实际状态之间的协调关系。
- 能从资源对象中定位名称、标签、版本与运行条件。
资源对象由哪些部分组成
每个 Kubernetes 对象都通过 apiVersion 和 kind 确定使用哪套 API 模式。apiVersion 通常由 API 组与版本组成,例如 apps/v1;核心资源省略组名,直接使用 v1。kind 表示对象类型,例如 Pod、Deployment 或 Service。
metadata 描述对象身份与检索信息。常用字段包括 name、namespace、labels 和 annotations。对象创建后,API Server 还会补充 uid、resourceVersion、generation 与时间戳等系统字段。命名空间级资源的名称只需在当前命名空间内唯一;集群级资源没有 namespace。

spec 与 status 如何协作
spec 是用户或上层控制器提交的期望状态,具体结构由资源类型决定。Deployment 的 spec.replicas 表示期望副本数,Pod 的 spec.containers 描述容器。多数业务清单只应声明 spec,不要手工维护 status。
status 记录系统观察到的实际状态,通常由控制器通过独立的 status 子资源更新。Deployment 会报告可用副本数与条件,Pod 会报告阶段、容器状态和节点信息。控制循环不断比较 spec 与现实:存在差距就执行创建、删除或更新,直到状态收敛。
对象还包含两个常见并发控制信号。generation 在期望配置变化时递增,控制器可通过 status.observedGeneration 表示自己已处理到哪个版本;resourceVersion 则用于检测对象是否在读写之间被其他请求修改。
用命令观察字段
下面使用客户端干运行生成一个 Deployment 对象,不会把资源提交到集群。该命令完整展示了类型、元数据、规格和空状态的基本关系。
kubectl create deployment api-model-demo --image=nginx:1.27 --dry-run=client -o yaml预期输出的关键结构如下,空对象的展示方式可能随 kubectl 版本略有差异。
apiVersion: apps/v1
kind: Deployment
metadata:
creationTimestamp: null
labels:
app: api-model-demo
name: api-model-demo
spec:
replicas: 1
selector:
matchLabels:
app: api-model-demo
strategy: {}
template:
metadata:
creationTimestamp: null
labels:
app: api-model-demo
spec:
containers:
- image: nginx:1.27
name: nginx
resources: {}
status: {}此时 status 为空,因为对象尚未交给 API Server,也没有控制器执行协调。真正创建后,系统会为元数据补充服务端字段,并逐步更新可用副本、条件和观察版本。
读取对象时的检查顺序
先看 apiVersion 与 kind,确认资源模式;再看 metadata.name、namespace 和标签,确认对象身份与选择关系;随后读取 spec 判断期望配置;最后检查 status.conditions、副本计数或阶段,定位尚未收敛的部分。
排障时不要只看单个布尔状态。应同时比较期望值、当前值、条件的 reason 与 message,并确认控制器的 observedGeneration 是否追上最新 generation。这样可以区分“配置尚未处理”和“已经处理但执行失败”。