📚 课程目录第3章模板制品库定义

3、模板制品库定义：Helm Chart模板、Operator模板、自定义资源模板、版本化存储

在集群升级治理场景中，模板制品库是连接“升级策略”与“运行时状态”的核心资产仓库。它并非简单的文件存储，而是围绕 Helm Chart、Operator、自定义资源（CRD） 三大模板类型，结合严格的版本化存储机制，形成可追溯、可回滚、可审计的升级物料体系。本节将逐一拆解这四类定义及其在观测标签体系中的映射关系。

3.1 模板制品库的四大核心定义

模板制品库的每一类制品都承载不同的升级职责，其观测标签的粒度与维度也各有侧重。下表从定义、用途、版本化策略和关键观测标签四个维度进行对比：

制品类型	定义与用途	版本化策略	核心观测标签（示例）
Helm Chart 模板	Kubernetes 应用的打包与部署定义，通过 values.yaml 实现参数化升级。	Chart.yaml 中 version 字段 + appVersion 字段，支持 SemVer 语义化版本。	`chart.name`, `chart.version`, `chart.appVersion`, `chart.repo`
Operator 模板	封装特定应用或组件的运维逻辑，通过 CR 驱动自动化升级流程。	Operator 镜像 tag + CSV（ClusterServiceVersion）中的 version 字段。	`operator.name`, `operator.version`, `operator.channel`, `operator.installMode`
自定义资源模板	定义 CRD（CustomResourceDefinition）及其对应的 CR（Custom Resource）实例模板，用于扩展 K8s API。	CRD 的 `metadata.generation` + CR 的 `metadata.resourceVersion`。	`crd.name`, `crd.version`, `crd.served`, `crd.storage`
版本化存储	为上述三类制品提供不可变、可追溯的存储后端，通常基于 OCI 制品仓库或 Git LFS。	基于内容寻址（SHA256）或标签寻址（Tag），支持多级快照与回滚。	`artifact.digest`, `artifact.tag`, `artifact.createdAt`, `artifact.signedBy`

3.2 Helm Chart 模板：参数化升级的基石

Helm Chart 是集群升级中最常用的模板类型。在升级治理中，Chart 模板不仅包含应用本身的部署清单，还嵌入了升级相关的观测标签。一个标准的升级用 Chart 模板结构如下：

upgrade-operator-chart/
├── Chart.yaml          # 包含 version: 1.2.0, appVersion: 3.0.1
├── values.yaml         # 定义升级参数：image.tag, replicaCount, upgradeStrategy
├── templates/
│   ├── deployment.yaml
│   ├── service.yaml
│   └── _helpers.tpl    # 注入观测标签的模板函数
└── charts/             # 子Chart依赖

  观测标签注入点： 在 _helpers.tpl 中定义通用标签模板，确保所有 K8s 资源都携带 app.kubernetes.io/managed-by: helm、helm.sh/chart: {{ .Chart.Name }}-{{ .Chart.Version }} 以及自定义的 upgrade.observability/phase 标签。

3.3 Operator 模板：自动化升级的引擎

Operator 模板相比 Helm Chart 更为复杂，它包含 CRD 定义、Controller 逻辑以及升级策略的声明。在升级治理中，Operator 模板的版本化存储需要同时追踪 Operator 本身的版本和它所管理的 CR 版本。

Operator 版本：通过 OLM（Operator Lifecycle Manager）的 CSV 文件中的 version 字段标识，例如 1.2.0。
CR 版本：通过 CRD 的 versions 列表中的 name 字段（如 v1alpha1、v1）和 storage 字段标识。
升级通道：CSV 中的 replaces 和 skips 字段定义了升级路径，观测标签需记录当前 Operator 所处的通道（stable、beta、alpha）。

最佳实践： 在 Operator 模板的 CSV 注解中增加 operator.observability/upgrade-id 标签，用于关联本次升级的工单或变更记录，便于在可观测性平台中快速定位 Operator 升级事件。

3.4 自定义资源模板：扩展 API 的版本化契约

自定义资源模板（CRD + CR）是集群升级中“声明式期望状态”的载体。CRD 的版本化直接决定了集群 API 的兼容性。在升级治理中，CRD 模板的存储必须遵循以下版本化规则：

CRD 版本字段	含义	升级观测标签
`spec.versions[].name`	API 版本名称，如 v1、v1beta1	`crd.apiVersion`
`spec.versions[].served`	该版本是否仍在 API Server 中提供服务	`crd.served` (true/false)
`spec.versions[].storage`	该版本是否为持久化存储版本	`crd.storage` (true/false)
`spec.versions[].schema`	OpenAPI v3 校验 Schema	`crd.schemaHash` (用于检测 Schema 变更)

3.5 版本化存储：不可变制品仓库

版本化存储是模板制品库的“地基”。在集群升级治理中，推荐使用 OCI 制品仓库（如 Harbor、Docker Registry）或 Git LFS 作为存储后端。其核心观测标签围绕制品的不可变性和可追溯性设计：

内容寻址：每个制品包（Chart、Operator Bundle、CRD YAML）在推送时生成 SHA256 digest，作为唯一标识。
签名验证：使用 Cosign 或 Notary 对制品进行签名，观测标签记录签名指纹和签名时间。
多级快照：支持“制品版本 → 升级批次 → 集群环境”的三级快照，便于回滚到任意历史状态。

避坑提示： 不要仅依赖 Tag（如 v1.0.0）作为版本标识，Tag 是可变的。必须同时记录 artifact.digest 标签，确保在升级回滚时能精确拉取到同一份不可变制品。

3.6 模板制品库的观测标签体系总览

下图展示了模板制品库中四类定义之间的层级关系，以及观测标签如何附着在每一层上，形成从“制品存储”到“运行时实例”的全链路可观测性。

3.7 版本化存储的标签设计示例

以下是一个完整的版本化存储标签示例，展示如何通过标签唯一标识一次升级所用的模板制品：

# 制品仓库中的标签（以 Harbor 为例）
artifact:
  repository: upgrade-templates/nginx-operator
  tag: v1.2.0
  digest: sha256:a1b2c3d4e5f6...
  createdAt: 2025-03-15T10:30:00Z
  signedBy: cosign@devops-team

# 关联的升级观测标签
upgrade:
  id: UPGRADE-2025-003
  phase: canary
  targetCluster: prod-east-1
  templateRef:
    chart: nginx-operator
    chartVersion: 1.2.0
    operatorVersion: 1.2.0
    crdVersion: v1

  关键设计原则： 版本化存储的标签应遵循“一次写入，多次读取”的不可变原则。任何对制品的修改都应生成新的 digest，而非覆盖原有标签。观测标签体系中的 artifact.digest 是连接升级事件与制品内容的“黄金钥匙”。