📚 课程目录第4章 Kubernetes资源模型

4. Kubernetes 资源模型：K8s 声明式 API、YAML 结构、资源版本与 CRD

Kubernetes 资源模型是 GitOps 版本差异校验的底层基础。在 GitOps 工作流中，所有期望状态都以 Kubernetes 资源清单的形式存储在 Git 仓库中。理解资源的声明式 API、YAML 结构、版本演进机制以及自定义资源（CRD），是准确识别版本差异、避免校验误报的前提。

4.1 声明式 API 与资源模型

Kubernetes 采用声明式 API 设计，用户通过描述“期望状态”（Desired State）而非“操作步骤”来管理集群。每个 Kubernetes 资源都是一个 API 对象，包含以下核心字段：

字段	说明	校验关注点
apiVersion	资源所属的 API 组和版本	版本差异直接导致校验失败
kind	资源类型（如 Deployment、Service）	类型不匹配时无法比较
metadata	名称、命名空间、标签、注解等	名称/命名空间是唯一标识
spec	期望状态的详细定义	核心差异比较区域
status	集群实际运行状态（只读）	GitOps 不比较 status

GitOps 校验要点： 版本差异校验工具（如 Kustomize、Helm Diff、ArgoCD Diff）只比较 spec 和 metadata 中的关键字段，status 字段会被自动忽略，因为它是集群运行时产生的，不属于期望状态。

4.2 YAML 结构深度解析

一个标准的 Kubernetes Deployment YAML 文件结构如下：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
  namespace: production
  labels:
    app: my-app
    env: prod
spec:
  replicas: 3
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
      - name: app
        image: myregistry/my-app:v1.2.3
        ports:
        - containerPort: 8080
        resources:
          limits:
            cpu: "500m"
            memory: "512Mi"
          requests:
            cpu: "250m"
            memory: "256Mi"

  版本差异校验关键字段：
  metadata.name 和 metadata.namespace — 资源唯一标识
spec.replicas — 副本数变化
spec.template.spec.containers[].image — 镜像版本变化
spec.template.spec.containers[].resources — 资源配额变化
metadata.labels 和 metadata.annotations — 标签/注解变化

4.3 资源版本（apiVersion）演进

Kubernetes API 版本遵循严格的演进路径，不同版本代表不同的稳定性和功能成熟度。版本差异是 GitOps 校验中常见的误报来源。

版本级别	命名规则	示例	稳定性
Alpha	`v1alpha1`, `v1alpha2`	`batch/v1alpha1`	可能随时删除，不推荐生产
Beta	`v1beta1`, `v2beta1`	`rbac.authorization.k8s.io/v1beta1`	功能基本稳定，可能小改
Stable (GA)	`v1`, `v2`	`apps/v1`, `networking.k8s.io/v1`	长期支持，生产推荐

常见版本差异陷阱：

旧版 YAML 使用 extensions/v1beta1 的 Ingress，新版集群已迁移到 networking.k8s.io/v1，直接比较会报错。
Deployment 从 apps/v1beta1 升级到 apps/v1 时，spec 结构有变化（如 spec.selector 变为必填）。
GitOps 校验工具需要配置 API 版本转换规则，否则会产生大量误报。

kubectl api-versions 查看当前集群可用版本

4.4 自定义资源（CRD）与版本差异

CRD（Custom Resource Definition）允许用户扩展 Kubernetes API，定义自己的资源类型。在 GitOps 场景中，CRD 的版本管理比内置资源更复杂。

4.4.1 CRD 的核心结构

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: databases.example.com
spec:
  group: example.com
  names:
    kind: Database
    plural: databases
    singular: database
    shortNames:
    - db
  scope: Namespaced
  versions:
  - name: v1
    served: true
    storage: true
    schema:
      openAPIV3Schema:
        type: object
        properties:
          spec:
            type: object
            properties:
              engine:
                type: string
              version:
                type: string
              replicas:
                type: integer
  - name: v2
    served: true
    storage: false
    schema:
      openAPIV3Schema:
        type: object
        properties:
          spec:
            type: object
            properties:
              engine:
                type: string
              version:
                type: string
              replicas:
                type: integer
              backup:
                type: boolean

  CRD 版本差异校验要点：
  served 字段：控制该版本是否可被 API 服务器响应请求
storage 字段：指定哪个版本的数据实际存储在 etcd 中（只能有一个）
CRD 版本升级时，旧版本资源需要手动或自动转换到新版本
GitOps 校验工具需要理解 CRD 的版本转换规则，否则会误判为差异

4.4.2 CRD 版本转换策略

转换策略	说明	GitOps 校验影响
None	不进行转换，不同版本视为不同资源	版本差异直接报错
Webhook	通过转换 Webhook 在读写时自动转换	校验时需模拟 Webhook 逻辑
Internal	Kubernetes 内部通过 Hub 版本自动转换	校验工具需识别 Hub 版本

4.5 版本差异校验实战建议

最佳实践：

始终使用 Stable（GA）版本的 API，避免使用 Alpha/Beta 版本
在 Git 仓库中统一资源清单的 API 版本，避免混用不同版本
使用 kubectl convert 命令将旧版本资源转换为新版本
对于 CRD，确保所有自定义资源的 apiVersion 与 CRD 定义中 served: true 的版本一致
在 CI/CD 流水线中加入 API 版本兼容性检查步骤

常见错误：

直接复制网上的旧版 YAML 示例，未检查集群支持的 API 版本
CRD 升级后未更新已有的自定义资源实例，导致存储版本与实际版本不一致
GitOps 校验工具未配置 CRD 版本转换规则，产生大量误报