2. Kubernetes 资源模型基础：API资源、资源类型、资源对象、资源规范与状态

Kubernetes 资源模型是集群内所有工作负载与基础设施的抽象表达方式。Helm 作为控制平面与集群之间的适配层，其核心任务正是将 Chart 模板映射为合法的 Kubernetes 资源对象。理解资源模型的四个层次——API 资源、资源类型、资源对象、资源规范与状态——是掌握 Helm 适配机制的前提。

2.1 四层资源模型总览

Kubernetes 资源模型从抽象到具体分为四个层次，每一层解决不同粒度的定义问题：

2.2 API 资源与资源类型（GVK）

Kubernetes 使用 Group（组）、Version（版本）、Kind（种类） 三元组唯一标识一种资源类型。API 资源则是该类型在 REST 接口上的映射路径。

• Group：资源的功能域，如 apps（工作负载）、networking.k8s.io（网络）、batch（批处理）。核心资源（Pod、Service）属于空组 ""，对应 /api/v1。
• Version：API 的成熟度，v1（稳定）、v1beta1（Beta）、v1alpha1（Alpha）。
• Kind：资源的具体类型名称，如 Deployment、Service、ConfigMap。

以下表格列出 Helm 开发中最常用的资源类型及其 GVK：

2.3 资源对象的结构

每个 Kubernetes 资源对象都遵循统一的 YAML 结构，Helm 模板渲染后必须符合此契约：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
  namespace: default
  labels:
    app: my-app
spec:
  replicas: 3
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
        - name: nginx
          image: nginx:1.25
status:
  replicas: 3
  readyReplicas: 3
  conditions:
    - type: Available
      status: "True"

对象结构分为四个顶层字段：

• apiVersion / kind：标识资源类型，Helm 模板中通常直接写死或通过 .Values 控制。
• metadata：元数据，包括 name、namespace、labels、annotations。Helm 通过 .Release.Name 等内置对象动态生成名称和标签。
• spec：期望状态（Desired State），是用户声明的唯一入口。Helm 模板的核心工作就是填充 spec 字段。
• status：实际状态（Actual State），由 Kubernetes 控制器写入，用户和 Helm 不应手动修改。

2.4 资源规范（Spec）与状态（Status）的分离

Kubernetes 采用 声明式模型，其核心机制是 Spec → Status 的持续调和。Helm 只负责管理 spec，status 由集群内部的控制器循环驱动。

以下 SVG 图展示了 Spec 与 Status 的分离关系以及 Helm 在其中的位置：

2.5 资源对象的核心元数据

metadata 字段是 Helm 模板中最常操作的部分，以下字段具有特殊意义：

2.6 资源类型与 Helm 模板的映射关系

Helm 模板中的每个 YAML 文件对应一个资源对象。以下是一个典型的 Helm Chart 模板文件结构及其与资源类型的对应关系：

charts/my-app/
  templates/
    deployment.yaml    →  Kind: Deployment,  apiVersion: apps/v1
    service.yaml       →  Kind: Service,     apiVersion: v1
    ingress.yaml       →  Kind: Ingress,     apiVersion: networking.k8s.io/v1
    configmap.yaml     →  Kind: ConfigMap,   apiVersion: v1
    hpa.yaml           →  Kind: HorizontalPodAutoscaler, apiVersion: autoscaling/v2

每个模板文件的开头必须声明正确的 apiVersion 和 kind，否则 helm install 或 helm upgrade 时会收到 API Server 的校验错误。

2.7 资源模型的版本兼容性

Kubernetes API 版本会演进，Helm Chart 需要声明支持的版本范围。在 Chart.yaml 中通过 kubeVersion 字段约束：

apiVersion: v2
name: my-app
version: 1.0.0
kubeVersion: ">=1.21.0-0 <1.28.0-0"

不同版本的 Kubernetes 可能废弃或移除某些 API 版本。例如：

2.8 本章小结

Kubernetes 资源模型是 Helm 控制平面与集群交互的底层契约。API 资源定义了 REST 端点，资源类型（GVK）唯一标识了资源的身份，资源对象是 Helm 模板的最终产物，而 Spec 与 Status 的分离确保了声明式管理的可行性。Helm 的核心适配工作就是：将 Chart 模板中的 Go 模板语法渲染为合法的、包含正确 apiVersion/kind/metadata/spec 的资源对象，并提交给 API Server 持久化存储。