跳转到内容
AggregaAggrega
选择语言: 简体中文
本页面由机器翻译。阅读英文原文。

Helm-Chart Provider

helm-chart provider 为每个装配路径生成一个打包好的 Helm umbrella chart。helm provider 输出扁平的 Kubernetes YAML,供 GitOps 直接使用;而 helm-chart 输出一个 chart 脚手架——一个 umbrella Chart.yaml + values.yaml,外加每个参与节点各一个子 chart——下游工具可以通过 helm install 安装它,或将其纳入版本库以便按环境进一步定制。该 provider 按 (path, provider) 进行装配:每个绑定到 helm-chart Recipe 的节点,都会在边界求值后的 directory: 与各组件的 subDirectory: 拼接而成的路径处参与构成 umbrella。求值为同一路径的两个边界会合并为一个 umbrella chart,并将每个参与者列为子 chart 依赖。

从源 chart 复制而来的子 chart 模板携带的是其作者编写的内容:边界的 syncWave: <integer> 值、hook 上的 helm.sh/hook-weight 以及 Aggrega 来源标签,只有在 chart 自己写入它们时才会出现在这些模板中。为其渲染的每个资源加上 argocd.argoproj.io/sync-wave: "<N>"、helm.sh/hook-weight: "<N>" 和来源标签的,是 helm provider。该 provider 添加到子 chart 中、经 $import: 加载的 artifact 带有来源标签和 argocd.argoproj.io/sync-wave 注解,但不带 helm.sh/hook-weight(参见下文“artifacts: 注入规则”)。ArgoCD 读取 sync-wave 注解,Helm 读取 hook 的权重。

本页是 helm-chart provider 的编写参考。关于 helm 与 helm-chart 的划分,请参阅 Status 页面的 Providers 一节;关于跨 provider 的输入组合模型,请参阅 architecture/16-recipe-input-composition.md。

支持的输入类型

helm-chart provider 接受两种输入类型:

  • Sourced 模式。 带有 source: <chart-path> 的 Recipe 指向磁盘上的一个 Helm chart 目录。该 chart 作为子 chart 被原样复制到 umbrella 结构中,唯一的例外是 chart 自身的 name——参见“umbrella 所拥有的 chart 名称”;在单个节点层面不执行任何渲染或模板处理。Aggrega 的职责是组合(跨边界节点组装 umbrella),而不是模板求值。
  • $import: 加载的 artifacts: 模式。 一个 Recipe 若以逐条目 $import: 的方式编写 artifacts: 条目,即声明了额外的模板文件,helm-chart provider 会在复制源 chart 之后将其注入子 chart 的 templates/ 目录。每个文件都会先使用 [[ ]] 分隔符针对 Aggrega 的模板上下文进行预模板处理(参见下文“artifacts: 注入规则”),因此同一文件中的任何 {{ }} Helm 模板都会保留到下游的 helm install 渲染中。

以 helm-chart 为目标且声明了 workload: 的 Recipe 会在渲染之前被拒绝,所给出的拒绝与任何 provider 对其未声明的输入类型给出的拒绝相同——它指出该 provider 支持的类型,并将作者指向一个能够合成的 provider:

provider does not support the node’s input kind (node “api”). provider “helm-chart” does not support synthesized recipes (this provider supports: sourced); declare one of the supported input kinds, or target a provider that supports synthesized(provider 不支持该节点的输入类型(节点“api”)。provider“helm-chart”不支持合成的 recipe(该 provider 支持:sourced);请声明受支持的输入类型之一,或以支持合成的 provider 为目标)

这种划分是有意为之:workload 合成(将抽象的 Workload 转换为 Kubernetes 资源)专属于 helm provider。helm-chart 的职责是为作者已经制作好的 chart 进行 umbrella + 子 chart 组合。

以 helm-chart 为目标的 Recipe 还可以声明内联内容的 artifacts: 条目(其值为块标量、在 Recipe 中内联携带文件内容,而不是 $import: 加载的引用)。内联内容条目会以其编写时的键放置在子 chart 根目录下——没有 templates/ 前缀,也不拼接来源信息。chart 自身的模板通过 Helm 的 .Files.Get / .Files.Glob 读取这类松散文件(即经典的从文件生成 ConfigMap 的模式),因此 chart 根目录下的文件是一种合法的一等形态,而不是错误。

两种形式在放置之前都会使用 [[ ]] Aggrega 分隔符进行求值,因此任一形式的内容都可以读取 Recipe 的 pillar 上下文;任一内容中的 {{ }} 都保持不变,并在下游 helm install 时成为 Helm 指令。两种形式的区别在于文件落在何处,以及是否将来源信息合并到其中:

  • $import: 加载的条目是模板文件:求值之后(参见下文“artifacts: 注入规则”),它会被注入子 chart 的 templates/ 目录并合并来源信息,因此 Helm 会将其与 chart 自身的模板一起渲染为清单。
  • 内联内容条目是松散的数据文件:求值之后,它落在 chart 根目录,内容与求值结果完全一致,不带任何合并的来源信息,供基于 .Files 的方式使用。

artifacts: 注入规则

当 helm-chart Recipe 通过逐条目的 $import: 声明 artifacts: 条目时,每个 $import: 值都是一个模板文件的路径,相对于该 Recipe 自身所在的目录(即磁盘上包含该 Recipe YAML 的目录)解析。该 provider:

  1. 读取每个文件的内容。
  2. 使用 Aggrega 定界符 [[ ]],基于该 Recipe 的模板上下文(即该 Recipe 的 valuesMapping: 求值所依据的同一上下文)对内容进行预模板化。文件内容中的 {{ }} 保持不变——它们会在 helm install 时成为 Helm 模板指令。
  3. 将每个文件写入 umbrella 组装路径下的 charts/<instance-id>/templates/<authored-key>,bundle 的文件嵌套在该键之下。条目编写时所用的键决定文件名;$import: 路径选择其内容,对文件名没有任何影响,因此该路径内的目录结构永远不会出现在输出中。

[[ ]] / {{ }} 双定界符规则是关键细节。一个典型的经 $import: 加载的 artifact 文件可能会混合 Aggrega 阶段的插值(例如 [[ .values.image ]])和 Helm 阶段的插值(例如 {{ .Release.Namespace }})。每对定界符在各自的阶段生效:Aggrega 在编译时、文件落地之前解析 [[ ]];Helm 在 umbrella 交付后、安装时解析 {{ }}。

源 chart 的模板与经 $import: 加载注入的 artifact 之间若发生文件名冲突,会引发 CATALOG_ERROR——诊断信息会指出发生冲突的输出路径(例如 templates/cm.yaml)以及产生它的两种输入类型。作者可通过重命名 artifact 的键或 chart 自身的模板来解决冲突。

source: 键集

helm-chart provider 的 source: 指定一个 chart,它接受 source: 字段的两种形式,其解读方式与 helm provider 的 source: 键集所述完全相同:纯文件系统路径字符串,以及由 url: 承载位置的结构化对象。当 url: 指定文件系统路径时,不会获取任何内容,chart 从磁盘读取;当它带有传输协议(例如 oci://…,配合 kind: helm-oci-chart)时,aggrega pull 会获取并固定该 chart,构建时将其从缓存复制到 umbrella 中作为子 chart,条件与从磁盘读取的 chart 相同。

spec:
capability: helm-chart
source: ./charts/api-server # filesystem path to a chart directory
valuesMapping: |
image: "{{ .values.image }}"
replicaCount: {{ optional .infra `replicas` 2 }}

源路径上的 chart 必须在其根目录包含有效的 Chart.yaml;缺少该文件会在复制运行前报出明确的错误。复制时保留 chart 的目录布局:组合后,templates/、values.yaml、Chart.yaml 及其他所有文件都会出现在子 chart 目录中。每个文件都以你写入的字节原样到达,包括注释、键顺序和引号;唯一的例外是 chart 自身 Chart.yaml 中的 name 字段,它由 umbrella 设置,参见“umbrella 所拥有的 chart 名称”。

未能指定 chart 的两种方式都会被拒绝,而这两种拒绝来自 不同的地方。这一点值得了解,因为切换 capability 时只有其中一种会改变。存在却未声明任何内容的 source: 会在 任何 provider 运行之前被编译器拒绝,因此无论 Recipe 指定哪个 capability,结果都相同;诊断信息会提示你在无源模式下省略该字段, 或指定一个非空路径。完全省略 source: 是 合法的写法(Recipe 正是以此请求无源模式),而它在此处被拒绝 是因为 helm-chart 只声明了有源输入类型,所以编译器 以与任何 capability 被请求其未声明的输入类型时相同的消息拒绝这种组合。属于 helm-chart 自身的是这一声明,而不是 它自己的某种拒绝:对于由 workload: 块生成的 Kubernetes 资源, 请改用 helm capability。

声明了 omits: 的 Recipe 会被拒绝。omits: 键将源渲染出的文档排除在构建之外,而此 provider 在构建时不渲染任何 文档:它将 chart 复制到 umbrella 中,chart 的 模板在 umbrella 安装时才渲染。既然没有渲染任何内容,也就 没有可排除的内容,因此此 provider 不声明支持该键, 声明了该键的 Recipe 或 FeatureRecipe 会在复制任何内容之前被拒绝,参见 The provider does not support omits(该 provider 不支持 omits)。 对于放在 Recipe 旁边的 chart,可以改为在那里的 .aggregaignore 中添加一行来排除 chart 的某个文件,从下次固定该 Recipe 时生效;对于输出必须去掉某个文档的已获取 chart,请通过支持该键的 helm provider 来渲染它。

按路径组合——umbrella 结构

该 provider 对每个装配路径分两个阶段运行:

  1. 逐贡献者复制。 对于每个绑定到 helm-chart Recipe 的节点,该 provider 将源 chart 的完整目录树复制到一个子 chart 槽位中。文件以扁平方式落入逐贡献者的输出映射;装配器将 charts 指定为其贡献者所在的子目录,编排器在装配 umbrella 时在其中为每个贡献者分配一个独立目录——对于 component 是 charts/<instance_id>/。Feature 附件同样是贡献者——无论它是内置(vendor)一个 chart,还是通过 helm provider 渲染清单——它获得的目录位于该 component 目录的旁边而非其内部;参见“附件的 chart 落在何处”。
  2. 逐 (path, provider) 的 umbrella 装配。 该路径的所有逐节点复制完成后,装配器在装配路径的根目录输出 umbrella 的 Chart.yaml + values.yaml。umbrella 为每个贡献节点声明一个依赖,并将逐节点的值路由到以 instance id 为键的子块下。当装配路径接收来自多个边界的贡献者时(共享 directory: 的边界),每个贡献者都作为依赖落入同一个 umbrella。

umbrella 的 Chart.yaml 结构如下:

apiVersion: v2
name: <effective-chart-name> # see "Chart-name resolution" below
version: 0.1.0
description: Aggrega umbrella chart for boundary "<assembly-path>"
dependencies:
- name: <encoded-instance-id> # the name the placed sub-chart carries
version: <user-chart-version> # from the source chart's Chart.yaml
alias: <encoded-instance-id> # see "How a name is derived" below
repository: file://charts/<instance_id> # the sub-chart's own directory

chart 名称解析

umbrella 的 chart name 通过边界注解级联解析。每个贡献边界的有效 aggrega.ai/chart-name 注解(沿边界树向上遍历、经级联解析得到的值)决定 umbrella 名称;解析得到的值会像其他任何标识一样针对 chart 名称位置进行编码,因此仅包含字母、数字、下划线以及下文规则所保留的连字符的值会原样进入 chart。当装配路径接收来自多个边界的贡献者时,每个贡献者的有效 aggrega.ai/chart-name 必须解析为同一个值;不一致会中止构建,并给出指明冲突值及相关贡献边界的诊断信息。

级联自然地化解了 DRY 方面的矛盾:在父边界上声明一次 aggrega.ai/chart-name,子边界即可通过级联继承;没有共同父边界的兄弟边界必须显式声明相同的值。在其整个级联中都未声明 aggrega.ai/chart-name 的边界,会回退为使用 aggregate 名称和组装路径(即 umbrella 在 dist/ 下的输出目录,例如 boundaries/data/helm-chart),二者分别编码后按下文所述方式连接。

每个依赖条目的 name 是所放置的子 chart 所带的名称——即该 component 实例自身经编码的标识,与 alias 的值相同——原因见“umbrella 所拥有的 chart 名称”。其 version 仍取自源 chart 自身 Chart.yaml 中的版本。alias 将子 chart 的值限定在 values.yaml.<alias>.* 之下,这与 Helm 的 umbrella 值约定一致,从而在安装 umbrella 时逐实例的值能正确传递。

component 的子 chart 目录完全按编写时的样子保留 instance_id,因此 charts/<instance_id>/ 就是其文件落入的位置,也是依赖的 repository 所指向的位置。因此,同一源 chart 的两个实例可以共存而不会发生文件系统冲突,并且各自在自己的 alias 下保留自己的值块。

依赖的 name 与其 repository 是不同的字符串,这是有意设计的。 name 是该位置的 chart 所声明的名称,因为 Helm 依据子 chart 自身声明的名称将依赖绑定到子 chart;repository 则是该 chart 所在的位置。对于 component,二者恰好相同,因为都源自同一个 instance id。对于 Feature 附件,二者不同——声明的名称带有附件的组合标识,而目录则由其两个坐标连接而成——因此把其中一个当作另一个来读取,指向的将是不存在的东西。

附件的 chart 落在何处

内置一个 chart 的 Feature 附件会在其所附加的 component 旁边获得一个独立目录,位于 charts/ 下一级:

charts/
├── api/ # the component's own chart
├── api--guardrail/ # a Feature attached to `api` under `guardrail`
└── api--audit/ # a second Feature attached to the same component

附加到边界而非 component 的 Feature 没有可指明的宿主 component,因此其目录仅为其实例名称:charts/aux/。

为何放在旁边而非内部。 Helm 在 charts/* 处发现子 chart——只查找一级,而不是递归遍历。放在更深层级的 chart 不是任何 chart 的子 chart;它只是另一个子 chart 目录中的数据,只能通过 .Files 访问。因此,放在 component 自身 chart 目录内部的 chart 会被复制到输出中,会使构建成功,却不会为你部署的内容贡献任何资源——而且不会有任何报告。将每个贡献者放在各自的顶层目录,正是附件资源得以渲染的原因。

umbrella 还会将该附件声明为其依赖之一。两部分缺一不可:存在于 charts/ 下却不在 dependencies: 中的 chart 会产生 lint 错误,而在 dependencies: 中声明却没有对应子 chart 存在的 chart 会使 umbrella 拒绝加载。

两个坐标是连接(join)而非直接拼接。 目录名由宿主和实例组合而成,二者先各自应用下文所述的同一转义规则,再以 -- 连接。如果直接以 -- 拼接会产生歧义:名为 a--b 的宿主加实例 c,与宿主 a 加实例 b--c,会得到同一个目录。先对每个坐标编码可以将二者区分开,因此坐标内编写的 -- 会显示为 -zh-。

目录名允许的字符。 大小写 ASCII 字母、数字、句点和下划线按你编写的样子原样保留,因此 API--aux 和 web.api--aux 的结果符合预期。你编写的连字符,只要其后的字符属于上述字符之一就会保留,因此 web-api--aux 保持不变;连续两个连字符会被转义,因为这一对字符就是连接符。其他任何字符都按与 chart 名称相同的规则转义。之所以如此划定字符集,是因为这些目录名既是磁盘上的路径,又是依赖的 file:// 指针所解析的位置,而在文件名中没有问题的字符可能会截断 URL 或导致其被重新解码。

值跟随声明的名称,而非目录。 子 chart 的值限定在该 chart 所声明的名称之下,因此上述 chart 的值按 api--guardrail 的声明名称——cfr-zh-api-zh-guardrail——寻址,而不是按其目录寻址。

你无需自己编写那个键。 你在附件上编写值,umbrella 的 values.yaml 会为你组合好,相应的块已位于所放置 chart 的寻址地址上。对于附加到 component 的 Feature,这就是你在附件上声明的 values:,由 FeatureRecipe 自身的 valuesMapping: 读取;对于附加到边界的 Feature,则是你在那里声明的 infra:,因为附加到边界的 Feature 没有 component 值支柱。无论哪种情况,valuesMapping: 解析得到的映射都会成为 umbrella 中该附件自己的块:

# the umbrella's values.yaml, composed for you
api: # the component's own chart
replicaCount: 3
cfr-zh-api-zh-guardrail: # the chart the Feature attached under `guardrail` brought
auditEndpoint: "https://audit.internal"

这是这些值唯一的路径。 Feature 带来的 chart,其文件按作者编写的样子原样到达——除了“umbrella 所拥有的 chart 名称”中所述的那一个 manifest 字段——因此没有任何东西会把你的值写入该 chart,提供这些值的是 umbrella 的块。块未到达的 chart 并不是损坏的 chart:它会渲染自身 values.yaml 附带的默认值并报告成功,因此如果你希望在编写时看出差异,请给默认值设一个你能注意到的值。

其 FeatureRecipe 通过 helm provider 渲染的附件

helm capability 的 FeatureRecipe 附加到此目标上的组件时,带来的是已完成的 Kubernetes 清单,而不是 chart。这些清单完全按照 helm provider 渲染的样子落入该附件自己的目录,provider 为该目录提供使其成为 Helm 可安装 chart 的两样东西:一个最小的 Chart.yaml,以版本 0.1.0 声明附件自己的名称;以及一个模板 templates/rendered.yaml,它通过 Helm 的 .Files.Get 按名称输出每个渲染出的 YAML 文件:

charts/api--guardrail/
├── Chart.yaml # apiVersion: v2, name: cfr-zh-api-zh-guardrail, version: 0.1.0
├── guardrail-config.yaml # the manifest the helm provider rendered
└── templates/
└── rendered.yaml # {{ .Files.Get "guardrail-config.yaml" }}

声明的名称与同一附件若 vendor 一个 chart 时该 chart 会声明的名称相同,因此 umbrella 的依赖条目及其 values 块的寻址方式与上文所述完全一致。.Files.Get 原样返回文件的字节,而不会再次对其求值,因此带有字面模板花括号的清单——告警规则的 {{ $labels.instance }}、仪表板的查询——安装时这些花括号保持完整。其值已在 helm provider 渲染这些清单时解析进去,因此 umbrella 的 values.yaml 在该名称下携带的块不会被任何东西读取。

umbrella 所拥有的 chart 名称

**Aggrega 在你 vendor 的 chart 中唯一改动的,是该 chart 自身的 name 字段。**在放置后的 chart 的 Chart.yaml 中,name 被设为贡献该 chart 的实体的编码标识。

对于 component,即 component 实例自身的标识——与依赖的 alias 取值相同——umbrella 的依赖条目也使用该值,因此两侧始终一致。

Feature 附件带来的 chart 本身就是一个贡献者,它声明自己的标识,而不是重复其所附加的 component 的标识。该标识由你编写的两项内容组成——承载该附件的 component,以及 Feature 附加时所用的名称——前面带有一个简短的开头,标明它是附件的标识而非 component 的标识;组合后的值随后通过下文的推导写入 chart 名称位置,与其他任何标识完全相同。

因此,将一个 vendor chart 的 Feature 以名称 guardrail 附加到名为 api 的 component 上,会放置一个声明 cfr-zh-api-zh-guardrail 的 chart,而该 component 自身的 chart 仍声明 api。两者是独立的贡献者,各自声明自己的名称,而不是都声明宿主的名称。

chart 中的其他内容均不会被改动。其他每个文件都按你编写的原样逐字节到达;在 Chart.yaml 中,其他每个字段、每条注释、键的顺序和引号都与编写时完全一致。manifest 中其他位置嵌套的、恰好也叫 name 的键——例如维护者的名字——保持不变。

**为什么 umbrella 需要该字段。**chart 的 name 是 Helm 将 umbrella 的依赖绑定到的对象。它由 chart 的作者编写,而对于从上游获取的 chart,作者并不是部署它的人——因此同一装配路径中的两个 component 完全有可能 vendor 两个 manifest 声明相同名称的 chart。如果两个子 chart 都保留该共享名称,umbrella 的两个依赖都会解析到 Helm 先加载的那一个:一个 component 的 chart 会渲染两次,另一个则完全不渲染,而每个 component 的 values 仍会到达,因此输出看起来完整却是错误的。从 component 实例推导放置后的名称,彻底消除了共享名称,这就是无需拒绝任何情况的原因——包括两种别无他法的情况:在两个 component 下 vendor 同一个 chart,此时名称按构造必然共享;以及 vendor 一个并非你编写的 chart,其名称你无法更改。

**你唯一能观察到的变化。**读取自身 chart 名称的模板——{{ .Chart.Name }},以及由它派生的任何内容,例如常见的 {{ .Chart.Name }}-{{ .Release.Name }} 资源命名惯用法——读取的是编码后的实例标识,而不是源 chart 的 Chart.yaml 中写的名称。在设置该字段之前,这类模板读到的本来就是这个值,因为 Helm 按父 chart 绑定子 chart 所用的 alias 来报告子 chart;设置该字段只是让磁盘上的文件与渲染结果一致。因此在下文的示例中,api-east 子 chart 中的模板读到的是 api-east。

如果资源名称必须带有 chart 编写时的名称,请将该名称放入 chart 的 values.yaml 并从中读取——value 属于你,Aggrega 不会改动它。

名称如何推导

Helm chart 名称和 Helm 依赖 alias 各自接受的字符集,都比 aggregate 名称、boundary 路径或 instance_id 可包含的字符集更窄。推导不会替换目标不接受的字符,而是将其显式写出,因此仅在标点上不同的两个标识总会得到两个名称——在某个 alias 下写入的值只能到达该 alias 所指的子 chart。

  • 字母、数字和下划线完全按编写原样保留。
  • 只要连字符后面的字符被直接保留且不是小写 z,连字符就按原样保留。连字符后跟小写 z 会开启转义,因此处于该位置的原有连字符本身也会被显式写出——api-zone 变为 api-zhzone,这使得任何名称都能无歧义地还原。
  • 其他每个字符都写作 -z 后跟一个表示该字符的字母:d 表示点,s 表示路径分隔符,h 表示上述规则未保留的连字符。其余字符写作 x 加上该字符的六位十六进制码点;不构成任何字符开头的字节写作 b 加上其两位数值——因此即使名称不是有效文本,也会被区分地写出,而不会被合并。
  • 空值写作 -ze,任何非空值都不会产生它。
  • 当两个标识组成一个 chart 名称时——由 aggregate 名称限定组装路径——它们用 -- 连接。单个编码标识从不包含这对字符,因此连接后的名称能无歧义地表明各部分分别是哪个标识。

因此,instance_id data.main-db 得到 alias data-zdmain-db,而 aggregate fullstack-app 与组装路径 boundaries/data/helm-chart 得到 chart 名称 fullstack-app--boundaries-zsdata-zshelm-chart。相同的输入始终产生相同的名称。

umbrella 的 values.yaml 以 alias 为键:

api-server: # sub-chart alias = encoded instance_id
image: "registry/api-server:v2"
replicaCount: 3
billing-svc:
image: "registry/billing:v1"
replicaCount: 2

当子 chart 的 valuesMapping: 针对其模板上下文求值时,得到的 values 映射会自动填充这个以 alias 为键的子块。这适用于 umbrella 的每个贡献者,而不仅限于 component:vendor chart 的 Feature 附件本身就是一个贡献者,因此其 FeatureRecipe 的 valuesMapping: 会填充一个属于它自己的块,以其放置后的 chart 所声明的名称为键。参见“附件的 chart 放在哪里”。

valuesMapping: 设为 null 的键会以 null 写入其块中。使用 Helm 4 安装时,umbrella 自身 values.yaml 中的 null 仅在安装时也为该子 chart 提供了 values 的情况下,才会移除子 chart 对该键的默认值;若安装时未为其提供任何 values,则 null 会被丢弃,子 chart 的默认值保持有效。传给 helm install 的 values 中的 null 在任何情况下都会移除默认值。

Provider 特有的行为

  • 子 chart 必须有 Chart.yaml。 复制操作要求源路径根目录下存在 Chart.yaml。缺少该文件会在 umbrella 步骤运行之前中止构建。
  • 放置后的 chart 的 name 归 umbrella 所有。 它被设为贡献该 chart 的对象的编码标识:对于组件实例,是该实例自身的标识;对于由 Feature 附加项带来的 chart,是该附加项自身的标识。这也是 Aggrega 在 vendored chart 内部唯一修改的内容。参见“umbrella 拥有的 chart 名称”。
  • 源 chart 必须声明版本和名称。 依赖项条目的版本取自源 chart 自身 Chart.yaml 所声明的版本。因此,未声明版本的 chart 会中止构建,而不会被赋予一个版本:如果依赖项固定到子 chart 并不具有的版本,umbrella 的各实例值将无法到达该子 chart。出于同样的原因,如果 chart 的 Chart.yaml 未声明名称、包含多个 YAML 文档或无法解析,构建也会中止:umbrella 无法组合它读取不了的子 chart。
  • 编码后的别名和 chart 名称。 如果 instance_id、aggregate 名称或边界路径包含 Helm chart 名称或依赖项别名不接受的字符,它会按上文“名称如何派生”所述,在渲染出的 umbrella 中以编码形式出现。仅由字母、数字、下划线以及派生规则保留的连字符构成的标识,会与编写时完全一致地出现。
  • file:// 仓库指针。 umbrella 的依赖项条目使用 file:// 仓库指针,指向子 chart 自身的目录:对于组件是 file://charts/<instance_id>,对于由 Feature 带来的 chart 则是该附加项自身的目录。这是树内子 chart 的本地文件系统约定,使 helm dependency build 无需调用外部注册表即可解析 umbrella。该指针指向的是位置,而不是 chart 声明的名称;对于附加项,两者不同。如果指针指向的目录不存在,拒绝它的是 helm dependency build 这一步。
  • helm-chart 层面不进行模板渲染。 该 provider 不调用 Helm SDK 的渲染管线,只负责复制和组合。需要预渲染扁平清单的作者应改用 helm provider 的 sourced 模式。

完整示例

一个包含两个节点的边界,每个节点都绑定到一个指向同一源 chart 的 helm-chart Recipe:

# Recipe — used by both `api-east` and `api-west` instances
apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: api-server-helmchart
version: 1.0.0
spec:
capability: helm-chart
implements: core/api-server
source: ./charts/api-server
valuesMapping: |
image: "{{ .values.image }}"
replicaCount: {{ optional .infra `replicas` 2 }}

组合完成后,该边界求值得到的组装路径(默认为 dist/<boundary-directory>/<capability>/,因为 subDirectory: 默认为 {{ .capability }})包含:

dist/<boundary-directory>/helm-chart/
├── Chart.yaml # umbrella; lists api-east and api-west as dependencies
├── values.yaml # alias-keyed: api-east + api-west values blocks
└── charts/
├── api-east/ # ./charts/api-server, name: api-east
│ ├── Chart.yaml
│ ├── values.yaml
│ └── templates/
│ └── deployment.yaml
└── api-west/ # ./charts/api-server, name: api-west
├── Chart.yaml
├── values.yaml
└── templates/
└── deployment.yaml

两个子 chart 都是同一个源 chart 的副本,且各自在其 Chart.yaml 中带有自己实例的名称——正是这一点使同一个 chart 能在单个 umbrella 中被 vendor 两次。两个副本中的其他内容均与源 chart 完全相同。

针对此布局执行 helm install <release-name> dist/<boundary-directory>/helm-chart,会将两个实例作为单个 Helm release 安装,由 umbrella 中按别名索引的值驱动各子 chart 的模板。

交叉引用