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

Helm Provider

helm provider 为 GitOps 使用方(ArgoCD、Flux)生成扁平化渲染的 Kubernetes YAML。该 provider 按 (path, provider) 进行组装:每个以 helm 为目标的节点所渲染的 YAML 都会被路由到对应的组装器,其键由边界求值后的 directory: 与每个 component 的 subDirectory: 拼接而成;该组装器为每个 Kubernetes 资源输出一个 YAML 文件。下游工具直接对这些文件执行 diff 和 apply,无需 Helm 安装步骤。

当边界的 syncWave: <integer> 不为 0 时,每个输出的 Kubernetes 资源都会将其作为 argocd.argoproj.io/sync-wave: "<N>" 注解携带;Helm hook 还会额外携带 helm.sh/hook-weight: "<N>"。ArgoCD 读取 sync-wave 注解,Helm 读取 hook 的权重,二者各自据此对资源排序;处于默认 wave 0 的边界两者都不携带,两个工具都将其读作 wave 0。

本页是 helm provider 的编写参考。关于跨 provider 的输入组合模型,请参阅 architecture/16-recipe-input-composition.md。关于各 provider 的就绪状态,请参阅语言状态 → Providers。

支持的输入类型

helm provider 以不同角色接受全部三种 Recipe 输入类型:

  • Sourced 模式。 带有 source: <chart-path> 的 Recipe 指向磁盘上的 Helm chart 目录。Helm Go SDK 加载该 chart,基础渲染值字典与 chart 的默认值合并,chart 的模板渲染为扁平的 Kubernetes YAML。
  • Workload(合成)模式。 带有 workload:(内联或通过 $import: 加载)的 Recipe 声明一个 Workload 文档。provider 直接根据 Workload 规范为每个节点合成一个或多个 Kubernetes 资源——一个由 Workload 的 form 选定的控制器对象,加上每个服务对应的 Service 和每个持久卷对应的 PVC;参见 Workload(合成)模式。
  • 仅 Artifacts 模式。 带有 artifacts: 且既没有 source: 也没有 workload: 的 Recipe 会输出其作者编写的 manifest,并将构建的来源标签和注解拼接到每个资源自身的 metadata 中。

三者可以组合:一个 Recipe 可以同时声明 chart、Workload 和 artifacts:,每一项各自渲染和输出,并列出现在节点的输出中——参见每个 provider 接受的完整内容。

source: 键集

helm provider 的 source: 指定一个 chart,它接受 source: 字段的两种形式:裸文件系统路径字符串,以及由 url: 携带位置的结构化对象。只要该位置是文件系统路径,它就以声明它的 recipe.yaml 所在目录为基准,而不是以调用构建的目录为基准,并且必须保持在该目录之内:向上越出该目录的路径或绝对路径会被拒绝,因为该 Recipe 的发布所携带的每个文件都取自其目录——参见 entities/recipe.md “Content paths stay inside the Recipe’s own directory”。以这种方式指定的 chart 会随 Recipe 一起发布,包括其下在 Recipe 被固定时所记录的忽略规则保留的每个文件——helm provider 会排除版本控制目录以及 chart 的 templates/ 下的隐藏文件,并遵循 chart 自身的 .helmignore,而作者的 .aggregaignore 拥有最终决定权,如 Which files ship with an entity 所述——而 Recipe 旁边未被其任何声明引用的文件则不会发布。渲染读取的文件与发布所携带的文件相同,因此 chart 无论从你的目录还是从注册表渲染,结果都一致。你书写它的形式不会改变这一点:url: 为 ./charts/api-server 的结构化 source:,其基准与裸字符串 ./charts/api-server 完全相同。

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

结构化 source: 用命名字段表达同样的内容,而其 url: 携带的内容决定是否获取任何东西。当 url: 携带传输协议——OCI chart 用 oci://…,直接 chart 归档用 https://….tgz,或与 chart: 配对的 https:// 仓库根地址——时,chart 会被获取:类型来自 URL 协议或显式的 kind:,aggrega pull 获取 chart 并将其固定在锁文件中,构建则从缓存中解压它。当 url: 指定文件系统路径时,不获取也不固定任何东西——chart 从磁盘读取,其基准与上述裸字符串形式完全相同。

spec:
capability: helm
source:
kind: helm-oci-chart
url: ./charts/api-server # a path, so nothing is fetched and nothing is pinned
version: "1.0.0"

只有 url: 决定从何处读取 chart。其他字段选择要获取的内容,因此对于路径,它们不选择任何东西——但它们仍会以 .source.* 的形式传给 Recipe 自身的模板。

支持将 chart 本地 vendor 作为获取的替代方式,但这不是必需的。schema 接受开放的结构化对象。

源路径下的 chart 必须包含有效的 Chart.yaml。加载 chart 失败的 sourced 渲染会原样呈现底层 Helm SDK 的错误。空的 source: "" 与 helm 无关:它既不表示 sourceless 模式,也不表示 sourced 模式,因此无论 Recipe 面向哪个 provider,它引发的拒绝都相同,并且这一拒绝在读取 Recipe 时发生,即在加载任何 chart 之前,也在分派此 provider 之前。哪些命令会报告它,详见 entities/recipe.md 中的“Source field scheme inventory”和 errors/fatal-halts.md 中的“Recipe source: is an empty string(Recipe 的 source 字段为空字符串)”。

源模式

带有 source: <chart-path> 和 valuesMapping: 的 Recipe 在基础渲染阶段运行以下流水线:

  1. 通过 Helm Go SDK 加载 <chart-path> 处的 chart。
  2. valuesMapping 模板基于该 Recipe 的模板上下文求值。其 YAML 输出被视为该 chart 的值覆盖层。
  3. 覆盖层与 chart 的 values.yaml 默认值合并一次;键冲突时以覆盖层为准(即 Helm 标准的 helm install --values 语义)。覆盖层设为 null 的键会移除 chart 为它提供的默认值——无论在顶层、表内还是依赖的值中——与 helm install --values 的行为相同,因此 chart 的模板会将该键读作不存在;若 chart 未为某个键提供默认值,该键上的 null 会以 null 传入模板。
  4. Helm SDK 基于合并后的值渲染 chart 的模板。
  5. Aggrega 通过渲染后的 YAML 重写,将其来源元数据注入渲染出的清单,确保 sourced 输出带有与 workload 模式输出相同的标签。身份值成为标签(app.kubernetes.io/name、aggrega.ai/component-id、aggrega.ai/provider、aggrega.ai/provider-version、aggrega.ai/environment,以及设置时的 aggrega.ai/aggregate-name、aggrega.ai/compiler-version),每个都以 Kubernetes 接受为标签值的形式写出;Kubernetes 标签无法表示的值成为注解(aggrega.ai/recipe-uri、aggrega.ai/boundary-path、wave 不为 0 时的 aggrega.ai/sync-wave,以及任何其值必须被重写的标签的原样值——名为 imported/flow 的 Aggregate 会获得标签 imported-flow,并在同一键下获得注解 imported/flow)。重写规则见 well-known-annotations.md 中的“提供方输出的来源标签”。
  6. 输出文件平铺在该 Recipe 的输出目录中,每个渲染出的资源一个文件,命名为 <name-basis>-<kind>[-<namespace>]-<name>.yaml——即下文推导 release 名称所用的同一基础名,后接资源自身的 kind、namespace(如有)和名称,各部分均转为小写,其他字符的每一段连续序列缩减为单个连字符。对于普通 component,该基础名是 component 自身的标识,也就是资源的 aggrega.ai/component-id 标签所携带的值;对于由 Feature 附加项作者提供的 chart,基础名仍是宿主 component 的标识,而标签携带附加项自身的标识。不带 kind 或名称的文档改以其模板路径命名。chart 的目录结构被平铺:渲染输出中没有 templates/ 子目录,位于不同子目录、文件名相同的两个模板仍是两个文件,因为名称来自资源而非模板。Recipe 的 artifacts: 块所命名的文件不落在这里:它位于下一级目录中,即以声明它的 component 命名的目录下,因为此类文件以其作者写下的键命名,而非以其携带的资源命名——若没有该目录,绑定到同一个 Recipe 的两个 component 会写入同一路径,且两位作者都无法将它们区分开。

chart 渲染所针对的 namespace 读取自从 boundary 级联而来的 aggrega.ai/namespace 注解,并作为 release namespace 传给 chart;没有 boundary 声明时,chart 针对 default 渲染。若某个 boundary 声明了 namespace,chart 渲染出的每个不带 namespace 的命名空间级资源——没有 metadata.namespace,或该字段写为空或 null——都会在所声明的 namespace 中输出,这正是用 Helm 在该 release namespace 下安装 chart 时它所处的位置,其文件名也带有 namespace 段,与模板写了该字段的资源完全相同。模板写了 namespace 的资源保留它,无论其指向哪个 namespace。集群级资源仍不带 namespace。某个 kind 是否为命名空间级,对于 API 自身提供的 kind 取决于 Kubernetes API 自身的作用域,对于自定义 kind 则取决于同一渲染中的 CustomResourceDefinition(来自 chart 的模板或其 crds/ 目录)为其声明的 scope。两者都无法归类的 kind 的资源保持 chart 写出的原样,构建会报告它,每个 kind 报告一次,并给出该 kind 及其 API 组;kind: List 文档同样如此,其中的条目不会被放置。没有 boundary 声明 namespace 时,不放置也不报告:chart 写出的不带 namespace 的资源原样输出,由应用工具所选择的位置放置。

该报告是构建上的一条警告,构建仍会完成:

warning: node "store" (provider "helm"): resources of kind "Probe" in API group "monitoring.example.org" write no namespace and are left without one rather than placed in namespace "shop": the kind is not one the Kubernetes API serves itself, and no CustomResourceDefinition in this chart's render gives it a single scope, so whether it is namespaced is not known when the build runs, and they land wherever the tool applying the output places them

若 chart 有某个值会渲染该 kind 的 CustomResourceDefinition,或有某个值会自行写入 namespace,则通过 Recipe 的 valuesMapping 设置它即可放置此类资源。

chart 渲染所针对的 Kubernetes 版本

chart 的模板通过 .Capabilities.KubeVersion 读取其渲染所针对的 Kubernetes 版本,许多 chart 据此选择 API 版本、字段乃至整个机制——例如从 1.21 起使用投射的服务账号令牌,低于该版本则使用自带的令牌。构建过程没有可查询的集群,因此版本由你在 Release 声明组件部署位置的地方给出:边界上的 aggrega.ai/kubernetes-version 注解,或组件上的该注解(优先于其边界上的注解),其级联方式与 aggrega.ai/namespace 完全相同。

spec:
boundaries:
production:
annotations:
aggrega.ai/kubernetes-version: "1.31"
components:
api: {}
legacy:
annotations:
aggrega.ai/kubernetes-version: "1.28" # this component deploys to an older cluster

该值的读取方式与 helm template --kube-version 读取其标志的方式相同,因此它接受该标志所接受的形式,chart 读到的内容也与该标志给出的完全一致:"1.31" 读作 v1.31,"v1.31.2" 读作 v1.31.2,数字之后的文本按原样保留在 .Capabilities.KubeVersion.Version 中——"1.29.3-gke.100" 读作 v1.29.3-gke.100——而整体打印的 .Capabilities.KubeVersion 读取的版本不含该文本。用 semverCompare 比较 .Capabilities.KubeVersion.Version 的 chart 会把这样的后缀视为预发布版本,因此不带 -0 下限的约束(如 ">=1.21")不会匹配它;带有首尾空格的值会连同空格一起读取——" 1.30 " 读作 "v 1.30 "——并直接导致此类比较失败:在 chart 会比较版本的地方,请只写版本本身。不是版本的值——"one.two"、"latest"、单个数字——会以“插件无法表示的值”这一条件终止构建,并指出该值、组件及其边界;chart 绝不会改用其他版本渲染。参见 A Kubernetes version the helm provider cannot render a chart for(helm provider 无法为其渲染 chart 的 Kubernetes 版本)。空值视为未设置。

若没有注解指定版本,chart 将按同一 helm 版本的原生 helm template 所针对的版本渲染,即构建该 provider 所用的 Kubernetes 客户端库的版本:基于客户端库 v0.37 构建的 provider 按 Kubernetes v1.37.0 渲染。因此,chart 在 Aggrega 中的渲染结果与其作者用 helm template 渲染的结果相同,且默认值仅在构建 provider 所用的客户端库变化时才会变化。只要你部署到的集群版本与此不同,就请指定该版本:按比集群更新的版本渲染的 chart 可能会输出该集群不提供的 API 版本。

只有版本可以通过这种方式设置。chart 读取的其他所有能力——.Capabilities.APIVersions 和 .Capabilities.HelmVersion——都是 helm 库内置的值,因此集群通过已安装的 CustomResourceDefinition 提供的 API 不会报告给 chart。chart 自身 Chart.yaml 中的 kubeVersion 范围不会与该版本比较:helm template 会拒绝范围不包含其渲染版本的 chart,而构建会照常渲染它。该注解只影响从源渲染的 chart:合成的 Workload 和 artifacts: 主体不读取 .Capabilities,而 helm-chart provider 会将其 chart 原样不渲染地传递下去,在安装时再渲染。

排除已渲染的文档。 此 provider 遵循 Recipe 或 FeatureRecipe 声明的 omits: 条目,且仅在此模式下遵循:合成的 Workload 和 artifacts: 主体在渲染时不应用它们。chart 渲染的每个文档——无论来自模板还是其 crds/ 目录中的文件——都会与适用于本次构建的每个条目进行匹配,任一条目指定的文档都会被排除。条目通过文档自身携带的字词指定文档,这些字词也是构建其输出文件名和渲染事实的依据:其 kind、其 metadata.name,以及仅在条目指定了命名空间时,文档所在的命名空间——即其模板写入的命名空间,或在此 provider 按上文所述放置文档时边界声明的命名空间。它绝不是 chart 仅仅据以渲染的命名空间:未声明命名空间时,chart 针对 default 渲染,但模板未写入命名空间的文档不在任何命名空间中,因此指定 default 的条目不会匹配它。不带 kind 或 name 的文档不匹配任何条目。被排除的文档会先渲染,在所有文件名确定后再丢弃,因此保留的每个文档的命名和写入方式与没有这些条目时完全相同,而被排除的文档不会进入构建之后的任何环节——不生成文件,不参与拒绝两个贡献者落到同一名称的比较,不产生 Feature 读取的渲染事实,也不会交给任何流水线步骤。provider 会报告每个条目匹配了多少文档,未匹配任何文档的条目会终止构建;参见 An omits entry left out nothing the source rendered(omits 条目未排除源渲染的任何内容)。

chart 渲染时所用的 Helm release

该 provider 使用 v4.3 版的 Helm 4 SDK 进行渲染,因此 chart 读取到的内容与 Helm 4 自身的 helm template 提供的相同,并且相同的 chart 和 values 在每次构建中都渲染出相同的字节。针对 Helm 3 编写和检查的 chart 可能会观察到以下 Helm 4 行为:

  • .Capabilities.HelmVersion 报告 Helm 4 的版本 v4.3。
  • 默认 Kubernetes 版本为 v1.37.0,因为 v4.3 版的 Helm 4 是基于客户端库 v0.37 构建的,而 .Capabilities.APIVersions 是该客户端库的 API 版本集合。请按照chart 渲染所针对的 Kubernetes 版本中的说明,指明你的集群运行的版本。
  • 值为 null 的 chart 默认值会被丢弃。 chart 的 values.yaml 设为 null 的键——无论位于顶层还是表内——都不会出现在 .Values 中,除非 Recipe 提供的 values 设置了它,因此 hasKey 报告它不存在,toYaml 会省略它,chart 的 values.schema.json 也会针对不含该键的 values 进行检查。
  • 块标量在 --- 之前保留其末尾换行符。 若一个文档以块标量结尾,且同一模板中其后还有另一个文档,则该标量的最后一个换行符会被保留,因此写作 | 而非 |-。
  • .Chart 是以字段名为键的映射。 .Chart.Name、.Chart.Version、.Chart.AppVersion 及其他字段的读取方式与以前相同,但 toYaml .Chart 或 toJson .Chart.Maintainers 会以 Name、AppVersion 等形式打印键,并包含空字段;chart 元数据中不存在的字段读取为空,而不会导致渲染失败。
  • .Capabilities.KubeVersion.Version 按原样保留版本文本,如上文针对 aggrega.ai/kubernetes-version 注解所述。
  • 包含多个 YAML 文档的 values.yaml 会被整体读取,后面的文档合并覆盖前面的文档。
  • 空文件的 .Files.Lines 不返回任何行,而不会导致渲染失败。
  • Helm 4 新增的模板函数——mustToYaml、mustToJson、mustToToml、mustToDuration 以及 duration… 转换函数——可供 chart 的模板使用。
  • 被设置两个别名的依赖会为每个别名分别提供该依赖自身依赖项的一份副本。
  • values schema 校验仅在边缘情况下接受或拒绝的结果有所不同:带引号的电子邮件本地部分、NaN 和无穷大数值、在 enum 和 const 中将数字与非数字进行比较,以及 propertyNames、contentSchema 或后续数组项校验失败时所报告的位置。

引擎本身无法执行的模板——例如通过不存在的表读取某个值——以 Helm 4 的形式报告:模板的文件、行和列单独占一行,随后对于失败所经过的每个模板,缩进列出正在执行的内容和消息。chart 自身的 fail 或 required 保持其单行的 execution error at (<file>:<line>:<col>): <message> 形式,模板函数返回的错误也是如此。

release 名称的推导方式

源 chart 基于一个 release 名称渲染,该名称以 .Release.Name 的形式传入每个模板。chart 通常以它为资源命名,因此 release 名称是集群内的一个身份标识,而不是构建上的一个标签。

release 名称是渲染资源的输出文件名前缀所用的同一基础值的编码形式,因此两者是同一个名称写了两次。对于普通 component,该基础值是 instance_id;对于附加到边界上的 Feature,则是它所携带的组合身份。对于由 Feature 附加的作者提供的 chart,该基础值是宿主 component 的名称:chart 自身的模板基于 release 名称渲染,如果改为从附加推导,就会在资源已部署的集群中重命名 chart 声明的资源。这些资源仍在其 aggrega.ai/component-id 标签中携带附加自身的身份——资源叫什么与资源属于谁在这里是两个独立的问题,只有对普通 component 而言答案才相同。Helm release 名称接受的字符集比身份可携带的更窄:小写字母、数字、连字符和点,以小写字母或数字开头和结尾,最多 53 个字符。对于目标不接受的字符,推导不做替换,而是将其转写,因此两个仅在标点或大小写上不同的 component 身份总会得到两个不同的 release 名称。

  • 小写字母和数字完全按编写原样保留。
  • 只要连字符后面的字符被直接保留且不是小写 z,该连字符就按编写原样保留。连字符后跟小写 z 表示开始一个转义,因此在该位置编写的连字符本身会被转写——api-zone 变为 api-zhzone,正是这一点使任何名称都能无需猜测地反向解析。后面没有任何字符的连字符出于同样的原因也会被转写,因此 db- 得到 db-zh。
  • 其他每个字符都写作 -z 后跟一个表示该字符的字母:d 表示点,u 表示下划线,s 表示路径分隔符,h 表示上述规则不保留的连字符。其余任何字符(包括大写字母)写作 x 加该字符的六位十六进制码点;不构成任何字符开头的字节写作 b 加其自身的两位值。
  • 空值写作 -ze,任何非空值都不会产生它。

尽管 Helm 允许 release 名称中出现点,点仍会被转写而不是直接保留,因为 Helm 要求点的两侧都是小写字母或数字,而推导会自行插入连字符。

由于附加到同一 component 上的两个 Features 都基于该 component 的 release 名称渲染,两个都以 .Release.Name 为资源命名的 chart 会产生两个同名资源。此 provider 会报告其自身渲染产生的每个资源所携带的名称,其作用域为该资源的 kind,对于集群保存在命名空间中的 kind,还包括其命名空间;当两个贡献者落在同一名称上时,构建会拒绝,而不是生成应用后只保留最后一个的输出——参见 ../errors/fatal-halts.md “The same name is derived more than once inside the output(同一名称在输出中被推导出多次)”。集群保存在所有命名空间之外的 kind——ClusterRole、CustomResourceDefinition,或由同一次渲染中的 CustomResourceDefinition 以作用域 Cluster 声明的自定义 kind——其作用域仅为 kind 本身,分类方式与上文命名空间放置的分类完全相同,因此同一输出中两个 component 以同一名称各写一个此类对象时会被拒绝,即使 Release 将它们放在不同的命名空间中。解决方法是组合名称,所需的坐标取决于具体布局。同一 component 上的两个附加已共享宿主,因此需要传入模板的是附加:通过 FeatureRecipe 的 valuesMapping: 将 .attachment_name 传入 chart,并将其设置到 chart 用于构建资源名称的那个值上。一个 chart 附加到两个 component 的情况则相反——release 名称已按宿主区分,因此以 .Release.Name 命名的资源在每个宿主上都有自己的名称,而字面名称则没有。通过 artifacts: 交付资源的 FeatureRecipe 按相同条件报告:此 provider 读取每个输出文档携带的名称,无论该文档来自 chart 模板还是 artifacts 主体,因此附加到两个 component 的此类主体中的字面名称同样会中止构建。artifacts 主体是模板,因此请用 .context.rendered_name(宿主的 release 名称,按宿主区分,且使用 Kubernetes 名称允许的字符)以及在需要按宿主区分时用 .attachment_name 组合名称;在单独放置 artifact 集、不报告 release 名称的宿主上,改用 .context.instance_id 组合。并非每个名称都会被报告,因此未中止的构建并未比较其输出最终携带的所有内容。编写 chart 时最可能遇到的是声明 generateName 的资源,其名称留给集群补全,因此尚无可比较的内容。上面链接的页面列出了完整集合。

因此,instance_id 为 api 时得到 release 名称 api,data.main-db 得到 data-zdmain-db,db_host 得到 db-zuhost。仅由小写字母、数字和推导所保留的连字符构成的身份会按编写原样出现。相同的输入总是产生相同的名称。

Helm 的两个条件是基础值的属性,而非推导的属性:release 名称必须以小写字母或数字开头,且最多 53 个字符。首字符被转写的基础值,其名称会以每个转义开头的连字符开头;含有被转写字符的基础值,编码后会比编写时更长。构建会就这两点询问此 provider,并在构建时根据答复采取行动,而不是把拒绝留给集群在应用时处理——参见 ../errors/fatal-halts.md “The target will not accept a name derived from an authored identity(目标不接受从编写的身份推导出的名称)”。如何处理答复取决于基础值由谁编写。你编写的名称会被拒绝而不是被修改,拒绝信息会指出你编写的字段以及可用的长度预算;Aggrega 组合的名称则会被缩短,直到此 provider 接受为止。

集群对以 component 命名的资源有一条比 Helm 更严格的规则:Service 名称必须以字母开头,而 release 名称可以以数字开头。chart 通常以 release 名称命名其 Service,合成 workload 的 Service 也以它开头,因此此 provider 还会拒绝以数字开头的 component 名称,将其报告为目标无法使用的 Service name。任何长度都无法修复首字符,因此该拒绝不给出长度。所以,请以小写字母作为 instance_id 的开头,并保持其足够短,使编码形式仍能符合限制。

**更改推导 release 名称所用的基础值,会重命名 chart 以 .Release.Name 命名的集群资源以及此 provider 为该 component 合成的每个资源,而 Kubernetes 不会原地重命名资源。**应用工具会以新名称创建资源并删除旧名称下的资源,对于有状态资源,这意味着绑定到旧名称的存储会被释放。请将此类更改视为需要规划的替换——排空、迁移或排期——而不是要滚动发布的更新。

Workload(合成)模式

带有 workload:(内联或通过 $import: 加载)的 Recipe 会根据 Workload 的抽象意图合成 Kubernetes 资源。Workload 的 schema 记录在 entities/workload.md;本节介绍 helm provider 输出的内容。

对每个节点:

  • 一个控制器对象,由 Workload 的 form 选择:stateless(及默认值)输出 Deployment,stateful 输出 StatefulSet,daemon 输出 DaemonSet,task 输出 Job,scheduled 输出 CronJob,其 spec.schedule 为 Workload 的 schedule 字段(5 字段 cron 表达式或 @ 宏);没有 schedule 或 schedule 格式错误的 scheduled workload 会明确中止。声明了 suspend: true 的 scheduled workload 输出的 CronJob 带有 spec.suspend: true,因此在恢复之前不会按计划启动任何运行,但仍可以手动从该 CronJob 创建 Job;未声明它的 workload 则完全不输出 suspend 键。Deployment 和 StatefulSet 带有副本数;DaemonSet、Job 和 CronJob 不带。stateful Workload 要求在 Workload 中恰好声明一个 type: Headless Service 来管理 StatefulSet;provider 将 StatefulSet 的 serviceName 连接到该 Service 的渲染名称,如果未声明 headless Service(或声明了多个),构建会中止。persistentTemplate 卷是 form: stateful 的配套项——在任何其他 form 上声明它都会中止,并给出指明修复方法的消息。
  • Workload 上每个声明的 services: 条目对应一个 Service,暴露该服务规范列出的命名端口。条目的 type 成为 Service 的类型——ClusterIP、NodePort 和 LoadBalancer 原样保留,Headless 则成为带有 clusterIP: None 的 ClusterIP Service。Loopback 条目则会中止构建,并指明节点和服务:Kubernetes Service 没有绑定到主机回环地址的类型,而 NodePort Service 监听哪些节点地址是整个集群的设置,因此该条目会被拒绝,而不是以它未要求的可达范围进行渲染。参见 A service type the helm provider cannot render(helm provider 无法渲染的服务类型)。
  • 每个 persistent 卷对应一个 PersistentVolumeClaim,其大小和形态取自卷的规范。persistentTemplate 卷不输出独立的 claim:它成为 StatefulSet 自身 spec 中的一个 volumeClaimTemplates 条目,这正是它是 form: stateful 配套项的原因。

资源名称。 该模式为组件输出的每个资源都以组件的 release 名称命名——即 sourced chart 渲染时所依据的同一名称,按release 名称如何派生所述派生——provider 将该名称作为 {{ .context.rendered_name }} 报告给构建。控制器对象直接使用 release 名称;每个 Service 为 <release name>-<service key>;每个独立 claim 为 <release name>-<volume>,pod 的卷恰好引用该 claim;以文件形式交付的 secret 从名为 <release name>-secret-<slot> 的 pod 卷挂载,其中 slot 以集群接受的字母表写出,方式与 release 名称相同——因此 slot server_certificate 从 <release name>-secret-server-zucertificate 挂载,通过连接读取的 slot 中连接名称之后的点也以同样方式写出;StatefulSet 的 serviceName 是它输出的 headless Service 的名称;仅通过外部名称暴露的 Workload 输出一个使用 release 名称的 Service。因此组件 api 输出 Deployment api 和 default Service api-default,组件 my_api 输出 my-zuapi 和 my-zuapi-default——这些名称集群可以接受,而按原样编写的标识则不行。发布这些 Service 之一地址的 Recipe 用 {{ .context.rendered_name }} 构建它,如 ../templates/rendered-resource-names.md 所示;对于名称不含下划线和大写字母的组件,release 名称等于其 instance_id,因此其名称与标识完全一致。Feature 附件合成的 workload 是唯一的例外:它以附件自身的组合标识命名——即其 aggrega.ai/component-id 标签所携带的值——因为附件依据其宿主组件渲染,在那里派生的 release 名称会以宿主命名附件的 workload,并与宿主自身的 workload 冲突。该标识从不包含大写字母:宿主名称或附件名称中的大写字母会被写成转义,与资源名称拒绝的其他所有字符一样,因此组件 myApi 上的附件 worker 输出 Deployment cfr--my-zx000041pi--worker 和 default Service cfr--my-zx000041pi--worker-default,该 workload 携带的每个名称都是集群接受的名称。

取决于 Workload 的名称长度。 其中两个名称受集群各自的限制,构建会在 Workload 解析完成后检查这两者,而不是把拒绝留给集群在应用时进行。CronJob 名称最多 52 个字符,比集群的其他名称更短,因为控制器会以 CronJob 的名称加上后缀来命名每次运行的 Job;仅对 scheduled Workload 进行检查。每个 Service 名称 <release name>-<service key> 最多 63 个字符。超出任一限制时,结果取决于名称由谁编写,与 release 名称的情况完全相同:你编写的组件名称会被拒绝,构建在你编写的 spec.components 键处中止,并给出名称的种类、其长度以及你的名称可用的长度预算——参见 ../errors/fatal-halts.md 中的“The target will not accept a name derived from an authored identity(目标不接受从编写的标识派生的名称)”;组合而成的标识(例如 Feature 附件的 workload 据以命名的标识)会被缩短,直到每个名称都符合限制。Service 名称由你的组件名称和 workload 声明的键(在 Recipe 或 FeatureRecipe 中)构成,因此拒绝会指明该键以及 workload 声明它的位置 spec.workload.services.<key>;如果某个键没有为任何组件名称留出空间,则必须缩短该键本身。因此,承载 scheduled Workload 的组件的编码名称最多可达 52 个字符,而组件 web 可以带有最长 59 个字符的 Service 键。附加到整个边界的 Feature 会在其 Workload 解析之前确定其标识,因为其输出在何处组装可能取决于该标识,所以对于它合成的资源,这两个限制都不检查。

每个输出的资源都带有完整的 Aggrega 来源标签和注解,以及一对连接 Deployment/StatefulSet 与其 Services 的选择器(app: <instance_id>)。标签值接受按原样编写的标识,因此选择器保留它,而上述名称使用 release 名称。渲染出的 Deployment 中的容器名称是 Workload 的容器键,其中的 . 和 _ 字符被替换为 -(Kubernetes 名称规范化)。

端口传输协议。 声明了传输协议的容器端口会在渲染出的 containerPort 上将其原样输出为 protocol:,引用该容器端口的每个 Service 端口都带有相同的值——传输协议只在容器端口上声明一次,因此暴露方式不会与之冲突。未声明传输协议的端口在两种资源上都不输出 protocol 键,沿用集群的默认值。Workload 接受的三个值(TCP、UDP、SCTP)都原样输出;helm 无需降级,因为 Kubernetes 能直接表达其中每一个。

在节点网络上运行。 声明了 hostNetwork: true 的 Workload 会在渲染出的 pod spec 上输出 hostNetwork: true,因此 pod 在节点自身的网络命名空间中运行,其容器打开的端口可通过节点地址访问。Kubernetes 能直接表达这一选择,因此没有任何降级。该声明只影响 pod spec:它不添加、删除或改写任何端口,输出的 Services 有无该声明完全相同。未声明它的 Workload 完全不输出 hostNetwork 键。

资源数量。 provider 复制到清单中的每个数量都原样输出,并且每个都会先按照 Workload → Resource quantities 所述的数量格式进行检查:每个容器和 init 容器的 resources.requests 与 resources.limits 值——cpu、memory 以及每个扩展资源,如 nvidia.com/gpu——以及每个卷的 ephemeral.sizeLimit、persistent.size 和 persistentTemplate.size。检查针对 Recipe 模板求值后的 Workload 运行,因此通过 infra 或 Release 参数传入的值按其渲染结果判断。不符合格式的值会以 TRANSLATION_ERROR 中止构建,并指明节点、该字段在 Workload 中的路径以及该值——例如 containers.main.resources.requests.cpu: "lots" is not a quantity: it does not begin with a number——否则 chart 会顺利构建,却在安装时被集群拒绝。留空的 cpu、memory 或 sizeLimit 会从清单中省略,因此不检查;留空的扩展资源值或持久化大小仍会被输出,因此会被拒绝。检查只判断格式:集群能否调度该数量,不是 provider 在构建时能知道的。

输出文件命名有两种形式。控制器对象按 release 名称及其 kind 命名——<release name>-deployment.yaml、<release name>-statefulset.yaml、<release name>-daemonset.yaml、<release name>-job.yaml、<release name>-cronjob.yaml。每资源文件按其所含资源命名,kind 放在最后:<release name>-<svcName>-service.yaml 和 <release name>-<volName>-pvc.yaml,各自取自该资源自身的 metadata.name,遵循 entities/workload.md 中的合成名称约定。仅通过外部名称暴露的 Workload 输出 <release name>-service.yaml,因为没有可携带的 service 键。

渲染事实

除了渲染出的文件之外,该 provider 还会针对每个节点报告四项渲染事实:它所输出的 Kubernetes 文档关于其 pod、选择器、端口以及各自输出到的命名空间的信息。附加到该组件的 FeatureRecipe 可在 .context.render_facts 读取该组件自身的事实;设置了 readsCallerRenderFacts: true 的 FeatureRecipe 还会在 .context.used_by 的每个条目上读取连接到其宿主的组件的事实;设置了 readsTargetRenderFacts: true 的 FeatureRecipe 则会在 .context.uses 的每个条目上读取其宿主所连接的组件的事实。借此,Feature 可以根据这些组件的渲染实际输出的内容,指明调用其宿主的组件的 pod,或其宿主所访问的组件的 pod(例如一条恰好放行这些 pod 的网络策略),而无需任何人手动重复声明标签。以下名称和条目是该 provider 的契约。

事实每个条目对应每个条目包含
pod_template_labels所输出的每个 pod 模板:Deployment、StatefulSet、DaemonSet、ReplicaSet 或 Job 的 spec.template,CronJob 的 job 模板,以及裸 Pod(其自身即为模板)承载该模板的资源的 kind、name 和 namespace;labels,即模板的标签
controller_selectors所输出的每个 Deployment、StatefulSet、DaemonSet、ReplicaSet、Job 和 CronJobkind、name、namespace;match_labels,即其选择器的 matchLabels
service_selectors所输出的每个 Servicename、namespace;selector,即其流量发往的标签
container_portspod 模板中声明了 ports 列表的每个容器,包括 init 容器承载该模板的资源的 kind、name 和 namespace;container,即容器名称;ports,每个端口一个条目,包含其 name、container_port 和 protocol

这些事实的读取方式:

  • **每项事实都是列表。**模板总是遍历事实,即使其中只有一个条目;不存在可单独读取的单一值。
  • **每次渲染都报告全部四项。**只要该 provider 渲染节点,就会报告每一项;若渲染未输出其描述的任何内容,则报告为空列表——chart 只输出一个 ConfigMap 的组件会报告四个空列表。其他 provider 的渲染不报告这些名称,而无人报告的名称读取为空。
  • **在每条路径上都从输出内容读取。**这些事实来自渲染所输出的文档,无论由哪种模式生成:chart 渲染出的清单、合成 Workload 的清单,以及作者通过 artifacts: 放置的清单——后者报告的正是这些清单所包含的内容。它们与该 provider 为构建的重名检查所报告的资源名称在同一遍处理中、针对相同的文档读取。资源自身的溯源标签是其内容的一部分,因此裸 Pod 的 labels 包含这些标签;chart 或 artifact 的 pod 模板则保留其作者所写的标签。
  • **条目可以来自组件自身的渲染,也可以来自其 Features 的渲染。**一个组件可能由多次调用渲染(例如一个 chart 加上一次 artifacts: 放置),同一名称从这些调用中得到的列表会按调用运行的顺序合并为一个。在 .context.used_by 和 .context.uses 上,连接另一端组件的事实还会在其自身事实之后并入附加到该组件的 Features 所渲染的内容;.context.render_facts 只包含组件自身的渲染。
  • **按输出顺序排列。**条目遵循渲染输出资源的顺序。标签映射与上下文中的其他映射一样是键控映射,因此遍历它的模板按键顺序访问其键。
  • **文档省略的内容,条目也省略。**通过 generateName 命名的资源没有 name;未写 metadata.namespace 的资源没有 namespace,将其写为空或 null 的资源同样没有,因为这也未指定命名空间;未写 matchLabels 的控制器(例如依赖集群生成选择器的 Job)没有 match_labels;没有选择器的 Service 没有 selector;没有名称或协议的端口两者皆无。其他写为空的部分报告为空。protocol 仅在文档写出时才报告,因此需要它的模板须自行写出集群自身的默认值 TCP。只要文档写出 container_port,它就是数字。
  • **namespace 是文档所写的值,从不猜测。**它是资源自身的 metadata.namespace——对于 pod 模板,是承载它的资源的命名空间,即其 pod 运行的位置;写在 pod 模板内部的命名空间不会被读取。合成 Workload 会在其输出的每个资源上写入其边界声明的命名空间,因此其条目携带该命名空间。chart 的条目携带其输出文档所写的内容:若边界声明了命名空间,则为该命名空间(无论是 chart 模板投射它,还是 provider 将资源放入其中,参见Sourced 模式),除非某个模板固定了自己的命名空间,此时条目携带该命名空间;若未声明,则在模板投射时为 release 命名空间 default,在模板未写时为空。未写命名空间时,条目不携带 namespace,而不是边界或集群的默认值,因为这样的资源会落在应用输出的工具所放置的位置,而这在构建运行时无法得知。模板可用 optional 区分两者:{{ optional . "namespace" "" }} 恰在文档未写命名空间时为空,因此在组件 pod 旁放置内容的 Feature 可以区分 pod 命名空间已知的组件和未知的组件。
  • 按 kind 和 API 组识别。Pod 和 Service 在 core 组中读取,四种控制器在 apps 中读取,Job 和 CronJob 在 batch 中读取,适用于该组的任意版本。其他组中恰好使用这些 kind 名称的自定义资源不会被当作它们读取。选择器的 matchExpressions 不报告,包裹在 kind: List 文档中的资源以及通过 YAML 合并键写入的值也不报告。

**事实看不到的内容。**它们描述构建输出的文档,而不包括集群之后创建的任何内容。控制器在运行时根据自定义资源创建的 pod(例如某个 operator 的数据库集群)不出现在任何输出文档中,因此必然缺失;变更型准入控制器在应用清单时添加的标签同样如此。必须放行此类 pod 的 Feature 应从该自定义资源自身的文档中获取其标签,就像作者在没有这些事实时所做的那样。

一个 FeatureRecipe,恰好只放行调用其宿主的组件的 pod 进入宿主的 pod,并通过宿主的控制器选择器选中宿主自身的 pod:

apiVersion: aggrega.ai/v1beta1
kind: FeatureRecipe
metadata:
name: admit-callers
version: 1.0.0
spec:
capability: helm
implements: example/admit-callers:1.0.0
readsCallerRenderFacts: true
artifacts:
allow-callers.yaml: |
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
name: {{ .context.rendered_name }}-allow-callers
spec:
podSelector:
matchLabels:
{{- range .context.render_facts.controller_selectors }}
{{- range $k, $v := .match_labels }}
{{ $k }}: {{ toJson $v }}
{{- end }}
{{- end }}
policyTypes:
- Ingress
ingress:
- from:
{{- range .context.used_by }}
{{- range .render_facts.pod_template_labels }}
- podSelector:
matchLabels:
{{- range $k, $v := .labels }}
{{ $k }}: {{ toJson $v }}
{{- end }}
{{- end }}
{{- end }}

对于被组件 web 调用的宿主 api(web 的 Workload 由本提供程序合成),该策略选择 app: "api",并放行一个携带 web 的 Pod 模板全部标签的 podSelector,即其输出的 Deployment 的 spec.template.metadata.labels 所含的相同标签。由于该 FeatureRecipe 设置了这个键,其挂载会在所有组件都渲染完成后才渲染,因此无论构建先处理 api 还是另一个组件,这些事实都已就绪;未设置该键时,在 .context.used_by 上读取 render_facts 的模板会在任何内容渲染之前使构建停止。

策略 from 中的 podSelector 匹配策略自身命名空间中的 pod,因此上述策略放行的是输出到其所应用命名空间中的调用方。对于条目携带其他 namespace 的调用方,可将其 podSelector 与针对该命名空间 kubernetes.io/metadata.name 标签的 namespaceSelector 配对来放行;Kubernetes 会在每个命名空间上设置该标签。

Provider 特有的行为

  • Chart 下载仅使用 Helm 的内置处理程序。 从 Helm 仓库获取的 chart 使用 Helm 自身内置的 http 和 https 处理程序下载。Helm 下载器插件(无论是为 helm 命令安装的,还是位于构建运行目录中的)都不会被调用,因此该目录中的内容无法改变 chart 的获取方式。

  • 来源信息注入。 sourced 路径和合成路径最终得到相同的标签与注解集合;sourced 渲染通过后渲染的 YAML 重写(在 Helm SDK 完成渲染之后)注入它们,因此 chart 作者无需在自己的模板中传递 Aggrega 标签。

  • 环境变量顺序:读取 Secret 的条目在前。 合成容器的 env 列表包含两类条目:每个以 as: env 交付的 attachments 条目通过 valueFrom.secretKeyRef 从 Secret 读取其值,每个 variables 条目则携带普通的 value。provider 先写入所有读取 Secret 的条目,再写入所有普通变量,每类均按编写顺序排列,并将 envFrom 来源单独列在 envFrom 下。Kubernetes 展开 env 值中的 $(NAME) 引用时,只使用同一容器中列在它之前的条目,绝不使用列在它之后的条目,因此这种顺序使普通变量可以通过引用组合读取 Secret 得到的值,而密钥本身仍保留在 Secret 中:

    containers:
    api:
    image: "api:1.0"
    variables:
    DATABASE_URL: "postgres://app:$(DB_PASSWORD)@db:5432/app"
    attachments:
    DB_PASSWORD: { from: db-credentials, as: env }

    渲染出的容器将 DB_PASSWORD 列在 DATABASE_URL 之前,因此进程收到的 URL 中已填入密码。变量也可以引用在它之前编写的任何变量,这使编写顺序在 variables 内保持意义。Init 容器遵循相同的顺序。如果某个容器将同一个名称既作为 variables 条目、又作为以 as: env 交付的 attachments 条目给出,构建会中止,而不是写入两个条目,因为否则将仅由这种顺序决定进程看到哪个值(参见 A container gives one environment variable two values(容器为同一个环境变量给出了两个值))。

  • 命名空间级联:两种模式以不同方式作用于资源。 两者都从边界注解级联中读取 aggrega.ai/namespace,并且在没有边界声明命名空间时都不会自行创造命名空间。在合成模式下,provider 直接写入 metadata.namespace,当级联未产生值时则完全省略该字段。在 sourced 模式下,provider 将该值作为 chart 的 release 命名空间提供(级联未产生值时为 default),由 chart 自身的模板决定是否投射它;在声明了命名空间的情况下,provider 随后会将其写入 chart 渲染出的每个未带命名空间的命名空间级资源中(参见 Sourced 模式)。因此,声明了命名空间时,两种模式都会将每个命名空间级资源放入其中(chart 自行固定的命名空间以及 provider 无法归类的 kind 除外)。未声明时两者就会分开:投射 release 命名空间的 chart 会将资源放入 default,而合成输出不写命名空间;不写命名空间的 chart 则不将资源放入任何命名空间,于是它们落在应用清单的工具所放置的位置。标准库 FeatureRecipes 所携带的本地 chart 则通过其 valuesMapping 直接读取级联值:这样,在没有边界声明命名空间时它们可以省略该字段,与合成输出一致,而仅靠 release 命名空间无法表达这一点,因为它永远不为空。

示例详解

Sourced 模式——指向 vendored chart 的 Recipe:

apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: api-server-helm
version: 1.0.0
spec:
capability: helm
implements: core/api-server
source: ./vendor/charts/api-server
valuesMapping: |
image: "{{ .values.image }}"
replicaCount: {{ optional .infra `replicas` 2 }}
service:
type: ClusterIP
port: {{ .values.port }}
env:
LOG_LEVEL: "{{ optional .values `log_level` "info" }}"

Workload 模式——声明内联 Workload 的 Recipe:

apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: api-server-workload
version: 1.0.0
spec:
capability: helm
implements: core/api-server
workload: |
apiVersion: aggrega.ai/v1beta1
kind: Workload
replicas: {{ optional .infra `replicas` 2 }}
containers:
api:
image: "{{ .values.image }}"
ports:
web: {{ .values.port }}
services:
svc:
type: ClusterIP
ports:
web: {{ .values.port }}

交叉引用