容器与云原生 / 系统课时

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。

Kubernetes API 资源对象字段关系

spec 与 status 如何协作

spec 是用户或上层控制器提交的期望状态,具体结构由资源类型决定。Deployment 的 spec.replicas 表示期望副本数,Pod 的 spec.containers 描述容器。多数业务清单只应声明 spec,不要手工维护 status。

status 记录系统观察到的实际状态,通常由控制器通过独立的 status 子资源更新。Deployment 会报告可用副本数与条件,Pod 会报告阶段、容器状态和节点信息。控制循环不断比较 spec 与现实:存在差距就执行创建、删除或更新,直到状态收敛。

对象还包含两个常见并发控制信号。generation 在期望配置变化时递增,控制器可通过 status.observedGeneration 表示自己已处理到哪个版本;resourceVersion 则用于检测对象是否在读写之间被其他请求修改。

用命令观察字段

下面使用客户端干运行生成一个 Deployment 对象,不会把资源提交到集群。该命令完整展示了类型、元数据、规格和空状态的基本关系。

bash
kubectl create deployment api-model-demo --image=nginx:1.27 --dry-run=client -o yaml

预期输出的关键结构如下,空对象的展示方式可能随 kubectl 版本略有差异。

yaml
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。这样可以区分“配置尚未处理”和“已经处理但执行失败”。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

Kubernetes API 资源模型

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通