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

Recipe 输入组合——三种输入类型、Workload、Artifacts

一个 Recipe 为其目标 provider 生成 manifest 文件。本章介绍 Recipes 如何由三种正交的输入类型——sourced、synthesized 和 artifacts——组合出其输出,每种输入类型的结构如何,以及哪个 provider 生成哪种输出。Recipe 实体的概念角色(由 Ops 编写、将 Developer Intent 映射到单个物理 provider 的翻译模板)见 04-entity-taxonomy.md;关键字层面的 Recipe 编写接口见 ../language-reference/entities/recipe.md。

设计动机

每个 provider 的原生渲染工具(Helm、Docker Compose)本身已经知道如何渲染 provider 原生的清单。Recipe 的职责是声明这些清单应当包含什么内容:哪些容器镜像、哪些端口、哪些环境变量、哪些卷、哪些服务、哪些资源限制。

Recipe 需要表达的内容,超出了映射到一个 Deployment 和一个 Service 上的固定键集合(例如 image、environment、ports、replicas)所能承载的范围,其中包括:

  • resources(CPU/内存的 requests/limits)
  • 存活探针、就绪探针或启动探针
  • volumeMounts / volumes
  • nodeSelector / affinity / tolerations
  • serviceAccount / securityContext
  • 多容器 Pod、边车(sidecar)
  • ConfigMap / Secret / PVC / CRD 资源
  • 非 ClusterIP 类型的 Service(LoadBalancer、NodePort、Headless)

抽象层需要描述完整的工作负载形态,而不是一组固定的键。下文介绍的三种输入类型就是这一抽象:Recipe 以叠加方式组合其输出,来源包括外部加载的 chart 或模块(source:)、由 provider 合成为 provider 原生清单的抽象 Workload 规范(workload:),以及由 Recipe 直接输出的模板化 provider 原生清单(artifacts:)。

三种输入类型

通过叠加进行组合

从 Recipe 生成 provider 原生清单文件有三种方式,它们通过叠加而非互斥进行组合:

  1. source: — 一个从外部加载的制品(Helm chart、compose 文件),由 provider 以原生方式渲染,并由 valuesMapping: 提供覆盖值。
  2. workload: — 一个抽象的 Workload 规范(平台拥有的 kind),由 provider 合成为 provider 原生清单。该字段接受内联的 YAML 块标量,或指向单个本地文件或库条目的 $import:;分派方式由内容形状决定。
  3. artifacts: — 一个由内联或通过 $import: 加载的 provider 原生清单组成的映射,基于完整的 pillar 上下文进行 Go 模板渲染。每个条目可以内联编写(条目的值为块标量),也可以通过 $import: 指向单个文件或库内容。

这三种方式生成的文件都由编译器输出到边界的输出目录。三者可以在同一个 Recipe 中共存,但须遵守下文的验证规则。合并语义仅限顶层:每种输入类型生成完整的文件;这些文件并列输出;输出文件名冲突是致命错误。

描述性模式名称

这三种“模式”是用于文档和诊断信息的描述性词汇。Recipe 作者不声明模式,只需编写所需的关键字。一个 Recipe 按其主导输入来描述:

主导关键字描述性模式名称
source: + valuesMapping:(无 workload:,无 artifacts)sourced(源渲染)
workload:(无 source:,无 artifacts)synthesized(合成)
artifacts:(无 source:,无 workload:)artifacts-only(非正式称呼:“inline”)
两种或以上的任意组合显式描述(例如“sourced with artifacts”、“synthesized with artifacts”)

不存在名为 mode: 的关键字,也没有枚举。模式是由存在哪些输入而自然呈现的属性。

Recipe 结构一览

apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: ...
version: 1.0.0
spec:
capability: helm | compose | helm-chart | ...
implements: core/...:1.0.0
locals: { ... }
provides: { ... }
# ─── Sourced input (optional, paired) ───
source: ...
valuesMapping: |
# Go template → YAML/JSON overlay values
# OR:
valuesMapping:
$import: ./mappings/api-server.tmpl # local file path
# OR:
valuesMapping:
$import: <Lib>#/mappings/<entry> # MappingLibrary entry
# ─── Synthesized input (optional) ───
workload: |
# Go template → YAML → parsed Workload
# OR (single-source $import for whole-content load from a file or library):
workload:
$import: ./workload.yaml
# ─── Artifacts input (optional, multiple entries permitted) ───
artifacts:
"filename.yaml": |
# Inline Go template → manifest YAML
"other.yaml":
$import: ./artifacts/other.yaml # per-entry $import: for file or library content

上面的每个字段都被 Recipe schema 接受,编译器支持全部三种输入类型——源渲染、Workload 合成和 artifacts 输出。不同之处在于各 provider 的支持情况——哪个 provider 渲染哪种输入类型——详见本章末尾的 Provider 能力矩阵。

加载时验证规则

Recipe schema 和加载验证会强制执行以下组合规则:

  1. valuesMapping: 需要 source:。 没有可供覆盖的 source:,映射后的值就没有接收方。包含 valuesMapping: 但没有 source: 的 Recipe 会产生加载时错误。(允许有 source: 而没有 valuesMapping:——此时 chart 或模块使用其自身的默认值渲染。)
  2. workload: 只接受一个来源——内联或 $import:,不能两者兼有。 Recipe 将 Workload 指定为内联块标量,或指向单个文件的 $import:。根据统一的文件导入词汇,$import: 形式为单一来源;workload: 不支持多来源合并。分派格式错误时产生加载时错误。
  3. workload: 需要支持合成的 provider。 是否支持合成是 provider 自身的属性,而非任何已声明字段的属性。绑定到无法合成的 provider 的 workload: Recipe 会在节点渲染时被拒绝——通过 provider 能力关卡(参见 Provider 能力矩阵)——并给出清晰的诊断信息。按照约定,标准库目录会在支持合成的 provider 上声明 workloadSchema,作为文档化的转换契约,但该关卡依据的是 provider 自身报告的能力,而不是该字段是否存在。
  4. 必须至少存在一种输入类型。 既没有 source:+valuesMapping:、也没有 workload: 或 artifacts: 的 Recipe 不会产生任何输出,属于加载时错误。
  5. 内联与 $import: 的 artifact 条目可以共存。 一个 Recipe 可以内联声明部分 artifacts: 条目,其余条目通过逐条的 $import: 指令声明。每个条目的键命名其自身的输出,因此两种形式的条目之间永远不会相互冲突(参见什么决定每个输出文件的名称)。
  6. 跨输入类型的文件名冲突是渲染时错误。 如果 Recipe 的两种输入类型——源渲染输出、workload 合成输出或 artifact 输出——生成了同名文件,编译器会报告一个致命错误,并指出每个来源。该检查在 Workload 转换之后运行,因此属于渲染时而非加载时。

Workload 类型

归属与位置

Workload 是位于 apiVersion: aggrega.ai/v1beta1 的平台自有类型。其 JSON Schema 2020-12 声明在构建时嵌入编译器二进制文件;catalog 作者不编辑 Workload schema,也不将独立的 Workload YAML 文件作为 catalog 实体编写。Workload 语法只在 Recipe 或 FeatureRecipe 的 workload: 字段中使用(内联,或通过 $import: 导入单个文件或某个 WorkloadLibrary 条目),别无他处。

Workload 是平台类型和编译器概念,而不是实体分类中的独立实体。Recipe 是编写实体;Workload 是 Recipe 的合成输入所采用的形态。

每个 Recipe 一个 Workload

一个 Recipe 最多声明一个 workload:。该 Workload 代表与此 Recipe 所实现的 Component 相关联的单一计算单元。FeatureRecipe 同样最多声明一个自己的 workload:——即通过同一 Workload 类型合成的、归 Feature 所有的计算单元——参见 FeatureRecipe。需要额外附属 workload 的用例通过以下方式表达:

  • artifacts:——在同一 Recipe 中与 workload 并列的额外清单(内联,或通过逐条目的 $import:)。
  • 带资源生成的 Features——作为独立 catalog 实体声明的横切附属 workload(例如附加到数据库的备份 sidecar),由 FeatureRecipe 合成其自己的 workload:(或通过 source: / artifacts: 渲染)。有关 FeatureRecipe 资源生成,参见 14-extensibility.md。

这保留了每个作者一个计算单元的模型:Recipe 合成 Component 的 workload;FeatureRecipe 合成自己的 workload。

完整字段面

Workload 的字段集很大且在不断增长。本章不在此重述——此处的副本会落后于契约而不会有任何提示——而是指向承载其全部内容的两个文档:

  • 生成的 Workload schema 参考——每个字段及其类型、默认值和约束,由已发布的 JSON Schema 生成,并在每次构建时与之比对,因此不可能描述编译器不接受的形态。
  • Workload 编写页面——字段级编写指导:每个字段的含义、每个 provider 将其渲染为什么,以及构建会拒绝哪些组合。

Workload 的 JSON Schema 2020-12 声明具有权威性,并嵌入编译器二进制文件发布。helm 和 compose provider 会合成 Recipe 的 workload:,无论是内联的还是通过 $import: 加载的;各 provider 的支持情况参见 Provider 能力矩阵。

与 featuresSchema 的 Secret 集成

Workload 的 containers.<name>.attachments 块引用 Component 的 featuresSchema 所声明的槽位;它不声明新槽位。有关 featuresSchema 的编写方式,参见 ../language-reference/entities/component.md。

验证契约:

  • 每个 attachments.<KEY>.from 值必须匹配 Component 的 featuresSchema 中声明的槽位名——或者,对于用 connection: <alias> 指定连接的条目,匹配该连接的 socket 在 usesSchema.<socket>.featuresSchema 中声明的槽位。此类条目会在以下任何规则运行之前被改写为该连接的 attachment 在组件上所取的名称(<alias>.<slot>),因此下面每条规则都像对待指定 Component 自身槽位的条目一样对待它。
  • as: 交付机制(env 或 file)必须在该槽位的 inject: 数组中列入允许名单。
  • 在 Component 的 featuresSchema 中标记为 inject: [](黑盒)的槽位不能出现在 Workload 的 attachments: 块中——这些槽位由 Recipe 的内部管道交付(例如通过 Helm existingSecret),而不是通过 Workload 暴露。

示例:

# In the Component
spec:
featuresSchema:
db_password:
required: true
inject: [env, file] # transparent: Workload may dictate delivery
root_password:
required: true
inject: [] # blackbox: Recipe handles internally
# In the Recipe
workload: |
containers:
main:
attachments:
DB_PASSWORD: # OK — db_password slot allows env inject
from: db_password
as: env
# ROOT_PASSWORD: ... # rejected — root_password is blackbox

健康探针:意图,而非机制

Kubernetes 探针和 Docker Compose healthcheck 的形态不同。单一的抽象意图形态可以干净地转换为两者:

health:
ready:
http: /healthz # intent: HTTP GET probe
timeoutSeconds: 5
live:
tcp: 8080 # intent: TCP socket check
timeoutSeconds: 5
startup:
exec: ["check-ready.sh"] # intent: command exec
timeoutSeconds: 30
periodSeconds: 10

Providers 将每个意图转换为其原生形态:

意图Helm(K8s)Compose
http: /pathhttpGet.path: /path, httpGet.port: <alphabetically-first port name>CMD-SHELL "curl -f http://localhost:<port>/path"
tcp: <port>tcpSocket.port: <port>CMD-SHELL "nc -z localhost <port>"
exec: [cmd]exec.command: [cmd]CMD [cmd]

对于未显式指定端口的 http:,在两个目标上都取容器在 containers.<name>.ports 下声明的按字母顺序排列的第一个端口名。未声明任何命名端口的容器不能承载 HTTP 探针,构建会中止并指出该探针。

Compose 将 HTTP/TCP 探针降级为 healthcheck shell 命令,而一个 compose 服务只承载一个 healthcheck:声明了多个探针时,只转换其中一个,并有一条警告列出被丢弃的探针。

卷类型

五种卷类型;无复合类型:

类型语义K8s(helm)Compose
ephemeralTmpfs / emptyDir;随 pod 消亡emptyDir: { sizeLimit }tmpfs: 挂载,不携带大小(编写的 sizeLimit 会由一条警告报告)
configmap只读配置文件ConfigMap 卷引用服务级 configs: 引用,指向 Recipe 的 artifacts: 所声明的顶层 config
secret只读 secret 文件Secret 卷引用只读的绑定挂载 secret 文件
persistent单个 PVC;在 pod 重启后保留PVC 资源 + volume.persistentVolumeClaim命名卷
persistentTemplate每副本 PVC;form: stateful 的配套StatefulSet.volumeClaimTemplates命名卷(降级;发出警告)

Compose 无法表达每副本模板。当 persistentTemplate 转换为 compose 时,它会降级为由所有副本共享的单个命名卷,并发出警告报告该降级。persistentTemplate 卷要求 form: stateful;在任何其他 form 上声明它都会中止构建。

多服务暴露

每个服务是一个独立的暴露。一种常见模式:端口 8080 上的 HTTP 服务(ClusterIP 内部)+ 端口 9090 上的指标服务(ClusterIP)+ 端口 9901 上的管理端点(LoadBalancer):

services:
http:
type: ClusterIP
ports:
web: 8080
metrics:
type: ClusterIP
ports:
prom: 9090
admin:
type: LoadBalancer
ports:
admin: 9901

在 helm provider 下渲染时,每个都会成为独立的 Kubernetes Service 对象,而遇到 Loopback 条目时该 provider 会中止。在 compose 中,NodePort 和 LoadBalancer 服务在 compose 服务的每个主机接口上发布其端口,Loopback 服务仅在主机的回环地址上发布,ClusterIP 和 Headless 服务不发布任何端口。

K8s 输出中的服务名以组件的 instance_id 为前缀以保证唯一性。端口名必须匹配 containers.<name>.ports 中声明的容器端口名。

Provider 侧转换契约:workloadSchema

负责 provider 渲染的 Plugin(pluginType: provider)声明一个 spec.provider.workloadSchema——一个 JSON Schema 2020-12 声明,记录 Workload 字段如何转换为该 provider 的原生输出。这是自描述的转换契约。有关 Plugin 的编写方式(包括 spec.provider 块),参见 ../language-reference/entities/plugin.md。

apiVersion: aggrega.ai/v1beta1
kind: Plugin
metadata:
name: helm-renderer
version: 1.0.0
pluginType: provider
spec:
abiVersion: v1beta1
provider:
workloadSchema: | # how Workload translates to K8s manifests
// Each Workload produces: 1 controller object chosen by workload.form
// (stateless -> Deployment, stateful -> StatefulSet, daemon -> DaemonSet, task -> Job)
// + 1..N Services (one per workload.services entry)
// + 1..N PVCs (one per workload.volumes.*.persistent entry)
// + 1..N ConfigMap volume refs (from workload.volumes.*.configmap.source)
// ...

workloadSchema 字段向 catalog 作者和 IDE 工具传达转换意图。它是有文档记录的转换契约,按约定在进行合成的 providers 上声明——但合成支持由 provider 本身决定,而不取决于该字段是否存在。针对无法合成的 provider 并使用 workload: 的 Recipe,会在节点渲染时经由 provider 能力关卡被拒绝,并给出清晰的错误,无论该 provider 是否声明了 workloadSchema。

Plugin schema 声明了 spec.provider.workloadSchema——其主体在 Plugin 加载时编译为 JSON Schema 2020-12——且 Recipe 侧的 workload: 使用已发布。合成支持在渲染时由 provider 能力关卡强制执行,依据所绑定 provider 报告的能力;workloadSchema 是标准库 catalog 与该能力保持同步的文档化契约,本身并不是关卡的输入。此外,对整个 catalog 运行的 aggrega validate 会在构建之前提早发现绑定到不支持合成的 provider 的 workload: Recipe,前提是 catalog 中包含该 provider 的 Plugin 实体。

辅助资源位于 Workload 之外

Workload spec 没有 additionalResources 字段,没有 extras,也没有内联的 ConfigMap/Secret/CRD 声明。Workload 只对工作负载的形态建模:容器、卷、服务、副本、调度、安全上下文、服务账号——即描述单个计算单元如何运行的一切。

辅助资源在 Workload 之外有两个合理的归属:

  1. Features + FeatureRecipes——用于横切关注点的机制。附加到“任何暴露了指标的服务器”上的 ServiceMonitor 是作为 Feature 的 core/prometheus-exporter。在某个主机名上发布服务器的路由资源也是一个 Feature,由路由形式决定是哪一个:目标协调 Ingress 时为 core/public-ingress,目标运行 Gateway API 时为 core/http-route——每个都由 Manifest 按 Release 选择的 FeatureRecipe 实现。对所有生产工作负载强制执行的 NetworkPolicy 是由生产 Release 在整个边界范围内附加的 Feature。Features 可以正交组合,并可在多个 Recipes 之间复用。关于 FeatureRecipe 资源生成,参见 14-extensibility.md。
  2. Recipe 级 artifacts:——用于属于该 Recipe 特定实现、不值得为其创建 Feature 的资源。例如该 Recipe 需要的一次性 CRD 注册;仅在使用该 Recipe 时才适用的 Recipe 专属 PodDisruptionBudget;该 Recipe 的 Workload 引用的 ConfigMap。每个条目可以内联,也可以通过 $import: 加载;参见下文的 Artifacts 机制一节。

Feature 与 artifact 之间的界线是一种社会约定。如果某个辅助资源是横切的(适用于多个 Recipes,或通过选择器有条件地附加),它就是 Feature。如果它是这一个 Recipe 固有的(该 Recipe 不输出该资源就无法完成其工作),它就是 artifact。作者根据复用和附加语义进行选择;编译器不会对此选择进行监管。

Features 与 Recipe artifacts 一起覆盖了 Recipe 所需的辅助资源。

Artifacts 机制

内联与文件加载的 artifact

artifacts 输入类型将经过模板处理的 provider 原生清单文件直接输出到边界输出中,与任何由 source 渲染或由 workload 合成的输出并列。作者通过两种方式声明它:

spec:
artifacts:
"servicemonitor.yaml": |
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
name: {{ .context.instance_id }}-monitor
spec:
endpoints:
- port: {{ .workload.services.metrics.ports.prom }}
"networkpolicy.yaml":
$import: ./artifacts/networkpolicy.yaml
"crd-registration.yaml":
$import: ./artifacts/crd-registration.yaml

$import: 路径相对于 Recipe 目录,且必须位于该目录之内,因为该 Recipe 的一次发布所携带的每个文件都取自该目录——import 所指定的每个文件都随之一起发布——而目录之外的文件则不会。一种典型的约定是将它们放在 ./artifacts/ 子目录中,但编译器并不强制这一点。map 键为每个输出文件命名——下一节说明这在三种形式中各自的含义。

每个条目(内联或通过 $import: 加载)在输出到输出目录之前,都会基于完整的模板上下文进行 Go 模板处理。

什么决定每个输出文件的名称

该 map 以条目名为键,在每种编写形式中,键都决定该条目输出内容的名称。对于内联条目,键就是输出文件名,按原样使用:

artifacts:
"configmap-config.yaml": |
...
"pdb.yaml": |
...

生成 configmap-config.yaml 和 pdb.yaml。键确定文件名;文件放在何处由目标决定,下文关于各 provider 输出的章节对此进行了说明。

对于文件 $import: 条目,键同样是输出文件名。导入的文件提供内容,但不提供名称,因此希望使用特定输出文件名的作者应将该名称写为键:

artifacts:
"monitor.yaml":
$import: ./artifacts/monitor.yaml
"netpol.yaml":
$import: ./artifacts/subdir/some-other-name.yaml

生成 .../monitor.yaml 和 .../netpol.yaml。第二个条目导入的文件名为 some-other-name.yaml,该名称不会出现在输出中——出现的是键。因此,两个导入恰好同名的不同文件(./extras/shared.yaml 和 ./overrides/shared.yaml)的条目是两个不同的输出,各自以自己的键命名。

对于库 $import: 条目,它将一组文件作为一个单元引入,该条目会展开为组中每个文件各一个输出,每个都以 <key>/<filename> 的形式嵌套在键之下。一个键对应多个文件,因此仅凭键无法为它们命名:它是该组文件所在的目录,而不是其中任何一个文件的名称。

由于每种形式都根据键为其输出命名,键在编写层面被限定为单个文件名可取的形式:以字母或数字开头,后跟字母、数字、点、连字符和下划线。点承载使用方所期望的扩展名,这使键可以直接用作文件名;且该字符集不包含 /,也不允许以 . 开头,因此一个键永远不会拼出多于一个路径段,也永远不会成为父目录段。超出该字符集的键会在工作区加载时、在 aggrega validate 中以及在编辑器诊断中未通过信封校验。

两个携带相同文件名的 artifacts: 输出会在节点渲染时中止构建,无论它们由哪种形式产生。同一个 artifacts: map 中的两个条目永远不会指向同一个输出:键在一个文档内唯一且是单个文件名,因此单文件条目的输出名就是其键,而组条目的所有输出都位于以其键命名的目录之下。因此,每个输出路径的第一段就是产生它的键,不同的键始终对应不同的输出名。中止所覆盖的是跨输入类型的情况——同一文件名由其中两种输入类型提供,例如 chart 模板和 artifact 条目都生成 servicemonitor.yaml——诊断会列出每个提供来源。

Artifacts 的模板上下文

Artifact 模板可以访问完整的支柱上下文:

  • .values、.infra、.context.*、.locals、.provides、.features、.metadata——06-data-taxonomy-and-composition.md 中描述的标准 Aggrega 支柱。
  • .workload——该 Recipe 解析后的 Workload 规范(如存在)。使 artifact 无需重复即可引用 Workload 的值,例如 ServiceMonitor 引用 .workload.services.metrics.ports.prom。
  • .source——解析后的 source: 字段内容(如存在)。

Artifacts 在 Workload 解析之后求值,因此存在时 .workload 可用。对于没有 workload: 的 Recipes,.workload 为 nil;尝试解引用它的模板会以明确的错误失败。对于没有 source: 的 Recipes,.source 为 nil,失败方式相同。

自包含不变式

Artifacts 必须是自包含的。它们只能引用该 Recipe 声明的输入:支柱上下文、该 Recipe 自己的 Workload(如存在)以及该 Recipe 自己的 source: 值。它们不能引用:

  • 同一边界中其他 Recipes 的输出。
  • 该 Recipe 未声明的环境中的 Kubernetes 资源。
  • 假定存在于外部的 Secret、ConfigMap 或其他资源(除非通过已声明的支柱引用)。

被 Workload 的 volumes.*.configmap.source 引用的 ConfigMap artifact,必须由本 Recipe(通过生成该 ConfigMap 的 artifacts:)或由附加到该节点的 Feature 输出。不支持边界内的跨 Recipe 依赖。

该不变式保证了 Recipe 的可复用性:一个 Recipe 可以放入任何满足其支柱契约的 Aggregate + Release 组合中,且没有隐藏依赖。

来源标签

翻译完成后,每个输出的文件都会在其元数据中携带 aggrega.ai/* 来源信息——无论它是由 source 渲染、由 workload 合成,还是由 artifact 模板输出。每个输出面都通过同一组共享的构建器写入这些信息,因此无论由哪种输入类型产生,同一个文件始终携带相同的来源信息。这组信息按值是否满足 Kubernetes 标签值字符集划分:满足标签要求的键作为 labels(可查询);不满足字符集的键——recipe-uri(包含 :)、boundary-path(嵌套路径包含 /)和 sync-wave(负数波次带前导 -)——作为 annotations,其值不受约束。构建不要求其符合标签规则的身份值——聚合名称、环境、提供方名称、编译器和提供方的版本——会以标签所允许的形式写为标签;当该形式与原值不同时,原值也会原样作为同一键下的注解写入(名为 imported/flow 的 Aggregate 会带有标签 imported-flow 和注解 imported/flow)。携带同一 Recipe 输出的所有文件共享相同的来源信息:

metadata:
labels:
aggrega.ai/component-id: api
# ... plus the recommended app.kubernetes.io/name label
annotations:
aggrega.ai/recipe-uri: api-server-helm:1.0.0
aggrega.ai/boundary-path: production

这种划分在三种输入类型中是统一的。(Compose provider 没有 annotation 的概念,且其标签值不受约束,因此它将整组信息作为服务标签输出。)关于编译时的来源标记,请参阅 11-governance-and-compliance.md。

由于 provider 在其自身输出格式承载来源信息的位置写入这些信息,如果某个 provider 的格式对给定文件没有这样的位置,它会原样输出该文件并明确说明。需要了解的情况是 Compose:它的来源信息位置是服务的 labels: 块,因此只提供顶层 volumes:、configs: 或 models: 的 compose artifact 片段不携带来源信息,构建会输出一条 “skipped provenance label injection”(已跳过来源标签注入)警告,并指明该 artifact。对于这种形态的片段,该警告是预期行为,而不是问题的迹象——同一 component 输出的服务携带完整的信息集,输出的字节也不会有任何变化。它排除的是第三种可能:文件未经标记就离开构建且未被指明。

另一个需要了解的情况是 CloudFormation,它的不同之处在于来源信息写入的位置,而不在于是否写入。CloudFormation 模板没有随资源一起传递的文档级元数据块,因此来源信息写入每个资源自身的 Metadata 属性,放在一个包含整组信息的 aggrega.ai/provenance 键下:

"StoreBucket": {
"Type": "AWS::S3::Bucket",
"Metadata": {
"aggrega.ai/provenance": {
"aggrega.ai/component-id": "store",
"aggrega.ai/recipe-uri": "store-recipe:1.0.0",
"aggrega.ai/boundary-path": "stack"
}
}
}

这一位置带来三个特性。Metadata 属性在任何类型的资源上都可用,因此组装后的 stack 所含的每个资源都会被标记——包括许多完全不接受标签(tag)的资源类型,基于标签的标记在这些资源上将无处可放。该标记是添加到作者编写的 Metadata 中,而不是替换它,因此作者自己的条目与其并存。并且由于它按资源而非按模板写入,由多个 component 组装而成的 stack 会携带每个资源各自的贡献者身份——其 component、其 Recipe 和其 boundary——这是单个模板级条目无法表达的。

整组信息一起放在该键下。Metadata 的值是不受约束的 JSON,因此无需进行字符集划分;只有 Kubernetes 运行时才读取的两个键——标准推荐标签名,以及 GitOps 控制器使用的部署排序 annotation——被省略,因为它们都不指代 stack 中的任何内容。普通的 aggrega.ai/sync-wave 来源条目则保留,因为它记录的是 component 声明的波次,而不是向控制器发出指令。

在这里没有位置的形态是不声明任何资源的模板或片段——只提供 Parameters、Mappings、Conditions 或 Rules 的片段。它不携带来源信息,以其原有内容完整地进入组装后的 stack,构建会输出一条 “skipped provenance injection”(已跳过来源信息注入)警告并指明它。与 compose 一样,对于这种形态的贡献,该警告是预期行为:同一 component 在其他位置提供的资源携带完整的信息集,并且无论是否有任何程序在监听,输出的字节都相同。

Per-Provider 的 Artifact 语义

以下各 provider 的语义描述了每个 provider 如何将 artifacts 集成到其原生输出中。

**helm provider:**artifacts 是 Kubernetes YAML 文档,写入以声明它们的 component 命名的目录下,该目录位于存放从 chart 渲染、从 Workload 合成的 manifest 的输出目录内。原因在于命名:渲染或合成的 manifest 由 provider 根据其所属的 component 命名,而 artifact 则以作者编写的键命名,这个键不说明它属于哪个 component——因此绑定到同一个 Recipe 的两个 component 会写入同一路径,而两位作者都无法将它们区分开。该目录就是 component 自身的名称,因此作者在输出中读回的文件名就是他们编写的名称,只是低了一级。

需要不同布局的运维人员可以使用 boundary 的 subDirectory: 模板,它移动的是贡献者输出的每一个文件,而不仅是 artifacts。参见 ../language-reference/path-template-variables.md。

**compose provider:**artifacts 是 compose 片段。顶层键(services:、volumes:、configs:、models:)在 boundary 组合步骤中合并到每个 boundary 的组合 docker-compose.yaml 中。

helm-chart provider(特例):artifacts 不会作为独立文件写入输出目录——渲染流水线归 Helm 所有。helm-chart provider 会将每个 artifacts: 条目放入 chart 本身,条目的编写形式决定其落点。每个条目都会首先使用 Aggrega 的 pillar 上下文进行 Go 模板处理,然后才进行放置;此后两种形式分道扬镳。通过 $import: 加载的条目是 Helm 之前的模板文件:它在 Helm 渲染之前被注入到 chart 的 templates/ 目录中,因此 Helm 会将其与来源 chart 自身的模板一起渲染。内联块标量是松散的 chart 文件:它以编写时的键放在 chart 根目录下,不带 templates/ 前缀,也不合并 provenance 标签,因此 chart 自身的模板可以通过 Helm 的 .Files.Get / .Files.Glob 读取它——即 ConfigMap-from-files 模式。这为 helm-chart provider 提供了一种扩展机制,等同于 artifacts: 为普通 helm provider 提供的机制,同时尊重 Helm 的 chart 模型。

注入的文件落在 boundaries/<bp>/charts/<nodeID>/templates/<authored-key>——bundle 的文件嵌套在该键之下——因此它与来源 chart 的模板并列,Helm 会在下游渲染阶段读取它。内联块标量落在 boundaries/<bp>/charts/<nodeID>/<authored-key>——即 chart 根目录,比 templates/ 高一级——因为通过 .Files 读取的文件必须位于 chart 查找它的位置,而放在 templates/ 下的文件会被当作 manifest 渲染。两种形式都以其编写时的键命名;二者的区别在于 provider 将它们放入的目录。

**helm-chart 分隔符约定。**Aggrega 对 helm-chart artifact 条目(无论是通过 $import: 加载的还是内联的)进行的预模板处理使用 [[ ]] 分隔符,而非默认的 {{ }},这样文件内 Helm 自身的 {{ ... }} 语法可以原封不动地保留到 Helm 的渲染阶段。作者将 Aggrega 侧的替换写为 [[ .context.instance_id ]]、[[ .values.name ]] 等;Helm 侧的替换保持为 {{ .Values.x }}、{{ .Release.Name }}、{{- include "common.labels" . }} 等。作者在同一文件中混用这两组分隔符是受支持的编写方式。

**Provenance 与 helm-chart artifacts。**对于通过 $import: 加载、能在保留 Helm 标记的前提下经过 YAML 往返处理的文件——只使用 [[ ]] Aggrega 上下文,或仅在带引号的标量位置使用 Helm {{ }} 的文件——provenance 会合并到 metadata.labels 和 metadata.annotations 中(按上文的字符集划分)。带有结构性 Helm 模板动作的文件({{- include ... }}、{{- if ... }}、{{- range ... }}、{{- with ... }} 位于输出 YAML 结构而非标量叶子的位置),或在值位置使用不带引号的 {{ ... }} 的文件,无法经受 Aggrega 的 YAML 往返处理;构建会输出一条指明该 artifact 的 “skipped provenance label injection”(已跳过 provenance 标签注入)警告,并将文件原样传递。对于任何使用结构性 Helm 模板动作或不带引号的 Helm 值替换、通过 $import: 加载的 helm-chart artifact 文件,出现此警告是预期行为——这是生产环境 Helm 编写中的常见情况,而非边缘情况。需要在此类文件上添加 provenance 标签的作者,应通过自己在 chart 的 _helpers.tpl 中编写的具名模板(例如名为 aggrega.commonLabels 的模板)或等效的 Helm 侧机制注入,而不是通过 Aggrega 的预模板注入。

**Chart 根目录文件名冲突。**如果通过 $import: 加载的 artifact 的编写键与 chart 根目录文件名(Chart.yaml、values.yaml、.helmignore 等)冲突,Aggrega 的文件名冲突检查不会检测到——artifact 落在 templates/<authored-key>,而 chart 根目录文件落在 chart 根目录,路径前缀使二者在 Aggrega 看来是不同的。作者应避免使用这些键名;使用它们的后果是 Helm 会看到两个文件(一个在 chart 根目录,一个在 templates/ 内),并可能意外渲染 templates 侧的副本。

**terraform provider:**artifacts 是 Terraform 配置文件,按原样输出到 boundary 的 modules/ 树下该 component 自己的目录中。HCL(main.tf)是便捷的默认形式,Terraform JSON(.tf.json)也同等接受;二者都不会被转译或重新格式化。boundary 的根配置将该 component 声明为一个 module 块,其 source 指向该目录,因此整个 boundary 保持为一个依赖图;该目录也是 vendored 模块文件所在的目录,因此同时声明 source: 和 artifacts: 的 Recipe 会将它们并排写入。Provenance 以开头的 Terraform 注释块形式携带;当某个 component 贡献 JSON 主体时,由于 JSON 没有注释语法,所有主体都原样输出,provenance 则放在它们旁边一个仅含注释的配套 .tf 文件中,因此标记绝不会在两者之间重复。参见 terraform provider 页面。

cloudformation provider: artifacts 是栈片段——即一个 component 贡献的资源,而不是一个完整的模板。该 provider 把每个片段规范化为纯 JSON 的长格式内部函数,并将其合并到为该输出目录组装的单个栈中:资源汇入同一个 Resources 映射,component 的 provides 则以作用域限定于发布该值的 component 的名称,作为栈的 Outputs 呈现。片段的其他顶层部分中哪些能在组装后保留,见 What a merged document carries from artifacts:。参见 cloudformation provider 页面。

边界作用域:用于边界共享输出的文件

artifacts 机制还有第二个作用域。上文所述的一切都写入该 component 在其边界输出中的自身位置;而 Recipe 的 spec.boundary.artifacts 是同一种映射——相同的三种形式、相同的键到文件名规则、相同的模板上下文——但改为针对整个边界只写入一次。它用于目标对一个边界所部署的全部内容只读取一次的文件,这类文件无法放在任何 component 自身的位置:Terraform 文档指出,用于被调用的模块不得包含 provider 块,而包含此类块的模块无法通过 depends_on、count 或 for_each 调用,因此 provider 的配置应属于边界的根配置,而不是某个 component 的模块内部。

落地位置。 位于存放该分派组已组装输出的目录中,与 provider 自身组装写入其中的文件并列——对于 terraform,即与根配置并列。编译器针对 Recipe 所渲染的每个 component,基于该 component 的上下文对每个条目求值一次,并由编译器自行写入文件:这些文件都不会交给 provider,也不会在任何文件中标记它来自哪个 component,因为它属于声明了它的每个贡献者。

贡献者如何汇合。 同一分派组的所有贡献者声明的文件按名称合并。以相同字节声明的同一名称即为同一个文件;以不同字节声明的同一名称,或 provider 的组装自身会写入的名称,都会使构建停止,并指出该文件及每个贡献者——这与两个贡献者写入同一输出路径时遇到的拒绝相同。因此,两个 Recipes 都需要的 provider 配置由两者以同一名称写入,并由构建检查二者是否一致。

谁接受它。 放在边界已组装输出旁的文件是否有意义,是 provider 目标的一项属性,因此这是 provider 自身的声明,与其输入类型一样从 provider 自己的声明中读取。若 Recipe 为未作此声明的 provider 声明该块,则会在任何渲染开始之前被拒绝。下方表格的最后一列列出了这一声明;在随编译器分发的 provider 中,terraform 作出了该声明。

artifacts 不是什么

三项结构性区别:

在单个 Recipe 内不跨 provider。 一个 Recipe 在其 spec 顶部恰好声明一个 capability:。该 Recipe 产生的一切——基于 source 渲染的输出、基于 workload 合成的输出以及 artifact 输出——都采用该 provider 的原生格式。helm Recipe 的 artifacts 包含 Kubernetes YAML。compose Recipe 的 artifacts 包含 compose 片段。一个 Recipe 面向一个 provider;每个输出都采用该 provider 的原生格式。

多 provider 组合发生在 Release 层级。边界可容纳混合 provider 的 components;边界求值路径上每个 provider 的贡献者按(路径,provider)独立分派和组装。一个 Release 若包含分别面向 helm、helm-chart 和 compose 的 components,可以将三者放在同一个边界中;分派分组按 provider 对它们进行划分,每个 provider 的贡献者落入边界路径下各自的已组装输出,而运维人员通过所选的边界结构编写跨 provider 的协调。跨 provider 协调是 Release 作者的责任。

不是 Recipes 套 Recipes。 artifacts 不会加载或组合其他 Recipes。它们是内联清单(或指向内联清单的文件路径),使用本 Recipe 的支柱进行模板化,并输出到本 Recipe 的输出中。Recipe 复用通过三种机制实现:Component 的 extends:(针对某个基础 Component 编写的 Recipe 服务于每个扩展它的 Component;继承的是元数据和 schema,而非输出文件——Recipe 本身不声明 extends:);Manifest 的扁平 URI 映射(同一个 Component 可在不同目录中解析为不同的 Recipes——参见 ../language-reference/entities/manifest.md);以及 Features + FeatureRecipes(正交附加的横切关注点)。

不是跨 Recipe 的粘合层。 artifacts 不能引用 Recipe 自身未声明的名称、资源或状态。被 Recipe 的 Workload 引用的 ConfigMap artifact 必须由本 Recipe 输出。期望使用外部预置 Secret 的 artifact 必须通过 .features 支柱获取该 Secret 的名称——来自输出它的附加项已解析的 provides——而不是假定它存在。这就是从 artifact 编写角度表述的自包含不变式(见上文):每个 Recipe 以一种格式输出文件,由一个工具应用,写入一个边界的输出目录。

Provider 能力矩阵

每个 provider 声明它渲染哪些输入类型;一个集中的输入类型关卡在节点渲染时接受受支持的组合,并以统一的诊断拒绝其余组合。能力是 provider 的属性,而非 Recipe 的属性——一个 provider 渲染三种类型中的一个子集。artifacts: 列区分两种情况:artifacts 伴随某个基于源或合成的主输入,以及独立的仅含 artifacts 的 Recipe(没有 source:,也没有 workload:)。最后两列是 provider 的声明:它遵守 omits:,以及它接受 Recipe 在 boundary.artifacts: 下向其 boundary 共享输出贡献的文件(见上文);两者都不是输入类型。

每一列单独阅读。 一行说明的是 provider 逐一单独渲染哪些类型,并不表示两个打勾的类型可以一起声明。由于各类型以叠加方式组合,每个声明的类型都会单独分派和输出,因此一对组合可能因任何一列都未体现的原因被拒绝——最常见的是两种类型都在同一输出名称下生成文件。每个 provider 实际接受哪些组合,在 What each provider accepts, in full 下以文字说明。

Providersource: + valuesMapping:workload:artifacts:(伴随)仅 artifacts(独立)omits:boundary.artifacts:
helm✅✅✅✅✅❌
compose✅✅✅✅✅❌
helm-chart✅❌✅ 使用 [[ ]] 分隔符进行模板化❌❌❌
terraform✅❌✅✅❌✅
cloudformation✅❌✅✅✅❌

此表涵盖随编译器分发的 provider。单独提供的 provider 以相同方式声明它接受的输入类型、是否遵守 omits: 以及是否接受 boundary.artifacts:,编译器也通过相同途径读取该声明——它未列于此处,因为已发布的页面无法列举它从未见过的 provider。

标记为 ✅ 的单元格表示会被渲染;❌ 表示由关卡报告的 provider 能力拒绝。每个节点的 compose 片段按组装路径合并,因此共享同一 directory: 的 boundary 共享一个文件。

每个 provider 完整接受的内容

helm——所有组合。 source: + valuesMapping:、workload:、artifacts:,其中任意两项,或全部三项。它是随编译器分发的 provider 中唯一不拒绝任何组合的,原因在于它为输出命名的方式:每个输出文件都以其中的资源命名,因此 chart 渲染出的清单与合成的 Workload 的清单绝不会落在同一名称上。声明全部三项的 Recipe 会将 chart 的文件、Workload 的文件和 artifact 文件并排输出到 boundary 的输出目录中。

compose——除 source: 与 workload: 同时出现的两种组合外的所有组合。 每种类型单独都能构建,artifacts: 可伴随其中任意一种。source: 搭配 workload: 无法构建,三者同时也不行;Why compose cannot combine a source with a workload 说明了原因,而这并非能力拒绝。

helm-chart——source: + valuesMapping:,单独使用或伴随 artifacts:。别无其他。 它不合成 workload:,也没有仅 artifacts 的形式:唯一输入类型为 artifacts: 的 Recipe 会停止。原因在于此 provider 放置 artifact 的位置——在组件自己的 chart 内部——因此没有 source: 的 Recipe 不会留下可放置 artifact 的 chart。

terraform——三种形式: 单独的 source: + valuesMapping:、单独的 artifacts:,或两者同时。它不合成 workload:。

cloudformation——与 terraform 相同的三种形式,以及相同的唯一排除项。 单独的 source: + valuesMapping:、单独的 artifacts:,或两者同时;不支持 workload:。

被拒绝的输入类型是什么样的

如果 Recipe 声明了其绑定的 provider 不渲染的输入类型,构建会在节点渲染时停止,并且无论 Recipe 在该类型之外还声明了什么都会停止——将 workload: 与 provider 能够渲染的 source: 搭配,并不能让 workload 通过。停止信息会指明 provider、它无法渲染的类型以及它能渲染的类型:

[CATALOG_ERROR E0265] instance unit
provider does not support the node's input kind (node "unit"). provider "terraform" does not support synthesized recipes (this provider supports: sourced, artifacts-only); declare one of the supported input kinds, or target a provider that supports synthesized

仅 artifacts 的拒绝信息形式相同,并指明该形式:provider "helm-chart" does not support artifacts-only recipes (this provider supports: sourced)。当需要持久地标识此停止时——在持续集成关卡、issue 或运行手册中——应记录的标识符是 E0265;所有条件的表格可解析它。

为什么 compose 无法将 source 与 workload 结合

compose provider 为每个组件生成一个片段,并以该组件命名该片段。基于源的渲染和 Workload 合成都会以同一名称生成该组件的片段,因此同时声明两者的 Recipe 会生成两个同名文件,构建会因冲突而停止:

[CATALOG_ERROR E0211] instance unit
rendering node "unit"
caused by: [CATALOG_ERROR] aggregate.yaml at .spec.components.unit
filename collision across input kinds: two input-kind blocks produced a file under one output name (output name "unit.compose-fragment.yaml", produced by "source, workload")

片段的名称来自组件自身的标识符,且没有可供编写的配置项,因此对 Recipe 自身内容的任何修改都无法避免冲突。停止是这一组合的属性,而非任一类型的属性——compose 能渲染 source,也能合成 Workload,表中为两者打勾是正确的。要在 compose 下为一个组件同时使用两种形式,请将它们拆分到两个组件中,或将 source 的内容并入 Workload。

合并后的文档从 artifacts: 中携带哪些内容

有两个 provider 会将各自的贡献者按每个组装路径合并为单个文档:compose 合并为一个 docker-compose.yaml,cloudformation 合并为一个堆栈模板。合并后的文档只能携带其组装器所建模的节,因此 artifacts: 一栏打勾表示的是片段内容被放置在何处,而不是片段中的每个键都会保留下来。

compose 从 artifact 片段中携带 services:、volumes:、configs: 和 models:,以及带 x- 前缀的扩展键。 片段在顶层声明其他任何内容都会使构建停止,并指出该键——networks: 会导致停止,因为网络是按边界派生的,而不是从贡献者累积而来;secrets: 块或顶层 name: 同样如此。compose provider 页面给出了逐键的合并规则以及跨网络路由的替代方案。

cloudformation 携带 Resources、Outputs、Parameters、Mappings、Conditions、Metadata 和 Rules,并根据每个贡献者的 Transform 构建出该段。 各个转换按照 CloudFormation 文档规定的顺序合并,SAM 的 Globals 随读取它的转换一同传递;如果某个转换会改变另一个贡献者内容的部署方式,构建会按名称指出该转换并停止。Description 不会被携带,并且构建会明确告知这一点:它会发出一条不受支持字段的警告,指出该段和该组件;对于栈不携带的其他任何顶层键也是如此,因此不会有任何内容被静默丢弃。该警告仅供参考——输出的模板与没有该警告时逐字节相同,--no-unsupported-field-warnings 可以关闭这一类警告。Outputs 以提供者限定到贡献组件的名称携带,因此两个组件向同一个栈贡献同名输出时,二者会保持区分。组装后栈中的顶层段逐一说明了每个段。

其他三个 provider 不进行合并,因此不存在 artifact 键被组装器丢弃的风险。helm 不组装任何内容:每个 component 的清单按原样进入边界的输出目录。terraform 和 helm-chart 采用嵌套方式——每个 component 的文件放在各自独立的目录中,即一个 Terraform 模块目录或一个子 chart,并由边界处的根文档引用它们——因此 artifact 条目作为一个完整文件放置,而不是被读入共享文档。helm-chart 的 artifact 条目放在何处,以及其分隔符对为何不同,见各 Provider 的 Artifact 语义。