企业官网建设流程全解析

incubator/raw是 Helm Charts 仓库（GitHub 加速计划 / chart / charts）incubator 目录下的一个通用 Chart：它允许用户把任意一组 Kubernetes 资源（如LimitRange、PriorityClass、Secret）直接写进values.yaml，由 Chart 统一注入默认metadata.labels后安装到集群。本文将以该 Chart 的官方文档为主体，结合其模板源码与 CI 测试配置，完整讲解 raw 资源与 templated 资源的两种用法、安装命令，以及标签合并的底层实现原理，帮助读者掌握一套"无需为每种 K8s 资源单独写 Chart，即可用 Helm 统一交付"的实践方法。

一、Chart 定位：给没有"家"的 Kubernetes 资源一个统一入口

incubator/raw的定位非常明确：接收一份 Kubernetes 资源清单，将清单中的每一项资源与一份默认的metadata.labels合并，然后把合并后的结果安装到集群（见 incubator/raw/README.md）。

其核心设计是两类资源入口：

• raw 资源：定义在resources键下，是字面意义上的"原始"资源，直接以 YAML 形式列出apiVersion、kind、metadata等字段；
• templated 资源：定义在templates键下，是一段 Helm 模板文本，可以引用{{ .Values.xxx }}等模板变量，适合注入运行时才确定的参数（如密钥）。

官方文档列出的典型使用场景包括以下资源类型：

• LimitRange：为命名空间设置 Pod / 容器的资源限额范围；
• PriorityClass：定义 Pod 优先级类，供调度器在资源紧张时决定抢占顺序；
• Secret：以 Helm 方式创建和管理敏感配置。

这类资源往往不隶属于某个具体应用，又没有对应的独立 Chart，incubator/raw恰好提供了一个"杂项资源统一入口"。Chart 的description字段也印证了这一点："A place for all the Kubernetes resources which don't already have a home"（见 incubator/raw/Chart.yaml）。

需要说明的是：该 Chart 已标记为deprecated: true（版本 0.2.5，见 incubator/raw/Chart.yaml），整个仓库也于 2020 年 11 月 13 日起停止更新并归档。本文内容基于仓库现状整理，适用于理解该 Chart 的设计思路，新项目建议优先参考 Helm 3 时代的原生include/tpl组合或 Operator 方案。

二、Raw 资源：直接把 YAML 资源清单交给 Helm

2.1 设计思路

Raw 资源的使用方式最为直接：把完整的 Kubernetes 资源对象写进values.yaml（或独立的-f文件），Helm 渲染时会为每个对象自动补上metadata.labels，无需手工维护繁琐的标签。

2.2 STEP 1：创建包含 raw 资源的 YAML 文件

以下示例来自官方文档（文件可命名为raw-priority-classes.yaml），一次性定义 8 个PriorityClass，覆盖"公共命名空间级"与"应用级"两个优先级档次：

# raw-priority-classes.yaml resources: - apiVersion: scheduling.k8s.io/v1beta1 kind: PriorityClass metadata: name: common-critical value: 100000000 globalDefault: false description: "This priority class should only be used for critical priority common pods." - apiVersion: scheduling.k8s.io/v1beta1 kind: PriorityClass metadata: name: common-high value: 90000000 globalDefault: false description: "This priority class should only be used for high priority common pods." - apiVersion: scheduling.k8s.io/v1beta1 kind: PriorityClass metadata: name: common-medium value: 80000000 globalDefault: false description: "This priority class should only be used for medium priority common pods." - apiVersion: scheduling.k8s.io/v1beta1 kind: PriorityClass metadata: name: common-low value: 70000000 globalDefault: false description: "This priority class should only be used for low priority common pods." - apiVersion: scheduling.k8s.io/v1beta1 kind: PriorityClass metadata: name: app-critical value: 100000 globalDefault: false description: "This priority class should only be used for critical priority app pods." - apiVersion: scheduling.k8s.io/v1beta1 kind: PriorityClass metadata: name: app-high value: 90000 globalDefault: false description: "This priority class should only be used for high priority app pods." - apiVersion: scheduling.k8s.io/v1beta1 kind: PriorityClass metadata: name: app-medium value: 80000 globalDefault: true description: "This priority class should only be used for medium priority app pods." - apiVersion: scheduling.k8s.io/v1beta1 kind: PriorityClass metadata: name: app-low value: 70000 globalDefault: false description: "This priority class should only be used for low priority app pods."

注意其中两个关键字段：

• value：优先级数值，越大优先级越高。示例中公共类（common）取值范围为 7000 万 ~ 1 亿，应用类（app）为 7 万 ~ 10 万，两者差距悬殊，可确保公共关键性 Pod 在资源竞争时优先被调度；
• globalDefault：示例中仅app-medium为true，表示未显式指定priorityClassName的 Pod 默认使用该优先级类。整个集群的globalDefault应保持唯一，否则 Kubernetes 会因冲突而拒绝创建。

该示例同样作为默认注释保存在 incubator/raw/values.yaml 中，可直接复制使用。

2.3 STEP 2：安装 raw 资源

官方文档给出的安装命令为（Helm v2 语法，使用--name指定 release 名称）：

helm install --name raw-priority-classes incubator/raw -f raw-priority-classes.yaml

执行后，Helm 会将resources下的每一项资源逐一渲染为独立的 Kubernetes 清单，并自动追加默认标签（详见下文"合并与标签注入"一节），随后在集群中创建 8 个PriorityClass对象。

2.4 可验证的最小示例

仓库的 CI 目录提供了一个最小化的 raw 资源用例 incubator/raw/ci/resources-values.yaml，仅包含单个PriorityClass，适合快速验证 Chart 渲染是否正常：

resources: - apiVersion: scheduling.k8s.io/v1beta1 kind: PriorityClass metadata: name: common-critical value: 100000000 globalDefault: false description: "This priority class should only be used for critical priority common pods."

三、Templated 资源：把模板变量注入 Kubernetes 资源

3.1 设计思路

当资源内容需要依赖运行时参数（例如 Secret 的取值来自外部加密文件）时，raw 资源的静态写法就不够用了。incubator/raw支持在templates键下书写 Helm 模板，模板中可引用{{ .Values.mysecret }}这类变量，再由 Helm 渲染引擎求值后输出为资源清单。

3.2 STEP 1：创建包含 templated 资源的 YAML 文件

官方文档示例（文件可命名为values.yaml）：

# values.yaml templates: - | apiVersion: v1 kind: Secret metadata: name: common-secret stringData: mykey: {{ .Values.mysecret }}

这里的关键在于templates下的每一项都是一段以|块标量书写的多行模板文本，模板内的{{ .Values.mysecret }}会在渲染时被替换为来自 values 的真实值。

由于 Secret 中往往存放敏感数据，官方文档建议用helm-secrets这类工具对包含mysecret的 YAML 文件进行加密。先创建明文文件：

# secrets.yaml mysecret: abc123

再执行加密：

$ helm secrets enc secrets.yaml

加密后的secrets.yaml即可安全地提交到 Git 仓库；解密与渲染由 helm-secrets 插件在安装时自动完成。

3.3 STEP 2：安装 templated 资源

通过-f同时传入模板文件与加密后的 secrets 文件：

helm secrets install --name mysecret incubator/raw -f values.yaml -f secrets.yaml

渲染结果为：一个名为common-secret的Secret对象，其stringData.mykey的值为abc123。文件合并时，后传入的secrets.yaml提供了templates模板所需的mysecret变量。

3.4 同时使用两种资源入口

resources与templates可以共存于同一个 values 文件中。仓库的 CI 综合用例 incubator/raw/ci/values.yaml 展示了这种组合：

resources: - apiVersion: v1 kind: Secret metadata: name: common stringData: foo: bar mysecret: abc134 templates: - | apiVersion: v1 kind: Secret metadata: name: common-secret stringData: mykey: "{{ .Values.mysecret }}"

渲染后会得到两个资源：静态定义的Secret/common与模板求值后的Secret/common-secret。而 incubator/raw/ci/templates-values.yaml 则单独演示了仅含一个ConfigMap模板的最小场景：

templates: - | apiVersion: v1 kind: ConfigMap metadata: name: raw

四、底层实现：一次合并，统一注入标签

incubator/raw的全部渲染逻辑只有一份模板文件 incubator/raw/templates/resources.yaml，核心是"逐项遍历 + 与默认标签模板合并"：

{{- $template := fromYaml (include "raw.resource" .) -}} {{- range .Values.resources }} --- {{ toYaml (merge . $template) -}} {{- end }} {{- range $i, $t := .Values.templates }} --- {{ toYaml (merge (tpl $t $ | fromYaml) $template) -}} {{- end }}

逐行拆解：

1. include "raw.resource" .调用辅助模板生成一份默认元数据（含metadata.labels），再用fromYaml解析为 map，得到$template；
2. range .Values.resources：遍历resources列表，对每一项执行merge . $template。Helm 内置的merge语义是后传入者优先，即$template中的默认标签会覆盖资源自身同名字段，最终toYaml序列化输出；
3. range $i, $t := .Values.templates：遍历templates列表，先用tpl $t $对模板文本求值（$即顶层 context，因此模板内可访问.Values.mysecret等），再fromYaml解析为 map，最后同样与$template合并输出。

4.1 默认标签从哪里来：raw.resource辅助模板

默认标签由 incubator/raw/templates/_helpers.tpl 中的raw.resource定义：

{{- define "raw.resource" -}} metadata: labels: app: {{ template "raw.name" . }} chart: {{ template "raw.chart" . }} release: {{ .Release.Name }} heritage: {{ .Release.Service }} {{- end }}

即每个被管理的资源都会自动获得四个标签，这也是 Helm 官方 Chart 约定俗成的标签规范：

4.2 命名辅助函数：raw.name与raw.chart

同一份_helpers.tpl中还定义了命名规则（与 Helm 官方模板规范一致）：

• raw.name：优先使用nameOverride，否则取.Chart.Name，并做trunc 63 | trimSuffix "-"截断处理；
• raw.chart：格式化为Chart.Name-Chart.Version，把+替换为_后再截断到 63 字符（DNS 命名规范限制，同时保证 Chart 版本升级不会产生标签值歧义）；
• raw.fullname：在fullnameOverride为空时，若 release 名已包含 Chart 名则直接使用 release 名，否则拼接为Release.Name-Chart.Name，同样截断到 63 字符。该函数虽未直接在资源渲染中使用，但保留了标准命名能力，便于扩展。

4.3 values 默认值：resources: []与templates: []

incubator/raw/values.yaml 中两个核心键的默认值均为空列表：

resources: [] templates: []

这意味着用户可以在自己的 values 中通过追加式覆盖（Helm 的-f多文件合并语义）自由扩展这两个列表，而无需改动 Chart 本身。文件中还以注释形式内嵌了完整的 PriorityClass 示例与 Secret 模板示例，作为开箱即用的参考文档。

五、使用注意事项与弃用说明

1. Helm 版本前提：文档中的helm install --name ...与helm secrets install --name ...均为 Helm v2 时代的命令行语法；在 Helm 3 中安装位置参数与 release 命名方式已变化，直接照搬需要调整为helm install <release> <chart> -f ...。
2. helm-secrets插件：templated 资源示例依赖helm secrets子命令（对应 helm-secrets 插件）完成加密与解密，使用前需先安装该插件；不敏感的场景也可直接使用明文 values 文件配合helm install -f。
3. 资源级联删除与标签：被管理的资源与 release 生命周期绑定，helm delete时会一并删除；由于所有资源都被注入统一的app/release/heritage标签，可方便地通过kubectl get <kind> -l release=<name>审计与筛选。
4. 弃用状态：Chart 自身在 incubator/raw/Chart.yaml 中标记deprecated: true，整个仓库亦于 2020 年 11 月 13 日归档停止更新。本文仅用于理解其设计模式与历史实现，生产环境建议评估其他活跃维护的方案。

六、总结

incubator/raw用一份不足 20 行的核心模板（incubator/raw/templates/resources.yaml）实现了"任意 K8s 资源 + 默认标签统一注入"的通用能力：静态资源走resources键，模板化资源走templates键，配合merge与raw.resource辅助模板完成标签合并。对于LimitRange、PriorityClass、Secret这类"散装"资源，它提供了一种低成本、可审计的 Helm 化交付思路；其"遍历 + 合并默认标签 + 模板求值"的实现，也为读者自行编写通用 Chart 提供了可直接借鉴的范式。