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

Workload

Workload 类型的架构角色——它为何存在、如何与另外两种 Recipe 输入类型(sourced 和 artifacts)组合,以及完整的 schema 范围——见 ../../architecture/16-recipe-input-composition.md。本页介绍 Workload 的编写范围:Recipe 作者如何编写 Workload 内容,编译器在何时求值哪些内容,Workload 字段如何与 Component 的 featuresSchema 交互,以及 Workload 中的模板可以读取哪些支柱。

编写位置

Workload 内容以内联方式或从文件编写,位于 Recipe 或 FeatureRecipe 中(参见 FeatureRecipe)。一个 Recipe 至多声明一个 workload:;FeatureRecipe 同样至多声明一个自己的 Workload:

# Inline (block scalar)
spec:
workload: |
apiVersion: aggrega.ai/v1beta1
kind: Workload
# ...

或

# File-loaded via $import: (path relative to the Recipe directory)
spec:
workload:
$import: ./workload/workload.yaml

两种形式在解析后产生相同的 Workload 对象;选择哪种只关乎编写的便利性。第三种形式按裸名称标识,从 WorkloadLibrary 条目导入多个 Recipes 共享的 Workload:$import: <Library>#/workloads/<entry>。根据统一的文件导入词汇,$import: 只接受单个来源——关于更广泛的 $ref: / $import: 区别,参见 ../vocabulary/cross-document-ref.md。

Workload YAML 不作为独立的目录实体编写。不存在 catalog/workload/ 目录;Workload 语法仅作为 Recipe 或 FeatureRecipe 所使用的内容存在——以内联方式编写、写在其旁边的文件中,或写在 WorkloadLibrary 条目中。YAML 中的 apiVersion 和 kind 声明(apiVersion: aggrega.ai/v1beta1、kind: Workload)用于在 schema 校验时标识嵌入的内容;它们并不使 Workload 可被独立寻址。

模板求值

Workload 内容在解析之前会基于完整的支柱上下文进行 Go 模板渲染。当 Recipe 作者编写如下模板时……

replicas: {{ optional .infra `replicas` 1 }}

……编译器会在渲染的 Workload 子阶段对该模板求值,根据节点的 infra 载荷解析 .infra.replicas,并将生成的 YAML 作为 Workload 文档解析。Recipe 的 locals 在 Workload 求值之前解析,因此 Workload 模板可以在 .locals 下读取已解析好的它们。

Workload 模板中可访问的支柱:

  • .values — 在 Aggregate 中声明、由开发者编写的认知载荷。
  • .infra — 在 Release 中声明、由运维编写的物理规格。
  • .parameters — 在解析时已完成插值;凡是开发者或运维在编写中引用了 .parameters.<name> 的地方,都可通过 .values / .infra 看到其值。
  • .locals — Recipe 私有状态,在 locals 前导部分解析并在源解析时发布;在每个 Workload 模板求值位置均可用。
  • .context.instance_id — 节点的扁平化实例 ID;按身份命名合成资源的 provider 所生成资源名称的前缀。
  • .context.rendered_name — 自行为合成资源派生名称的 provider 赋予它们的名称,例如 helm 的 release 名称;仅在 provider 报告了该名称时存在。参见 ../templates/rendered-resource-names.md。
  • .context.inject — 拦截后的注入管道,已在注入映射期间被任何 FeatureRecipe 的 injectMapping 重写。
  • .context.uses — 从该节点出发的增强拓扑边,每条边携带目标已解析的 provides、labels 和级联注解,并在 .context.uses.<alias>.features.<slot> 下携带该连接所带的附件。
  • .features — 节点自身的附件,每个附件携带其 type、values、infra 和已解析的 provides。以 Component 在 featuresSchema 中声明的槽位命名的附件会填充该槽位(见下文)。连接所携带的附件不在其中;它在其连接下读取,Workload 通过指明该连接来交付它(参见交付连接所携带的凭据)。

完整的支柱访问契约参见 ../vocabulary/data-pillars.md,Workload 求值在模板求值序列中的位置参见 ../templates/expansion-matrix.md。

字段语义要点

完整的 Workload schema 见 ../../architecture/16-recipe-input-composition.md 中的“The Workload Kind”一节。下面的编写约定涵盖 Recipe 作者在字段层面所做的决定。

form

form 声明工作负载的抽象控制器形态,即它具有的运行时生命周期类型,与任何目标平台无关。它是单个字符串,取值为 stateless、stateful、daemon、scheduled、task、reference 之一,省略时默认为 stateless:

  • stateless:可互换、水平扩展的副本,没有每副本身份(常见的长期运行服务)。
  • stateful:具有稳定的每副本身份和每副本存储的副本。persistentTemplate 卷是此形态的配套项。
  • daemon:每个符合条件的主机一个实例。
  • scheduled:周期性的、按时间触发的运行。
  • task:一次运行直至完成。
  • reference——自身没有容器:该组件代表一个外部端点,以 endpoint(主机或 URL,按原样传递)和可选的 port 给出。helm provider 将其输出为类型为 ExternalName 的 Service;compose provider 不为其输出任何内容。

形态本身不携带任何平台原生资源类型。每个合成 Workload 的目标 provider 都将形态映射为其自身的原生形态:

formKubernetes (helm)Compose
statelessDeploymentservice(无持久卷)
statefulStatefulSetservice + 命名卷
daemonDaemonSet中止构建
scheduledCronJob中止构建
taskJob中止构建

terraform 和 cloudformation provider 渲染 sourced 和仅含 artifacts 的 Recipes,不合成任何 Workload:声明了 workload: 且绑定到二者之一的 Recipe 会中止构建,并指出该 provider 支持的输入类型。

当目标 provider 对某种形态没有清晰的映射时,构建会显式中止,而不是把工作负载降级为歪曲意图的形态:选择目标边界无法表达的形态是构建时错误,而非静默降级。compose provider 遇到 daemon、scheduled 和 task 时中止。helm provider 为 scheduled 生成 CronJob(见下文 schedule),仅在其 schedule 缺失或格式错误时中止。

apiVersion: aggrega.ai/v1beta1
kind: Workload
form: stateful
containers:
db: { image: "postgres:16", ports: { db: 5432 } }
volumes:
data:
persistentTemplate:
size: "20Gi"
services:
headless:
type: Headless
ports:
db: 5432

schedule

schedule 是 form: scheduled 工作负载的 cron 调度,即为周期性形态提供重复周期的配套字段。它是采用一种规范格式的单个字符串:

  • 标准的 5 字段 crontab 表达式:分钟、小时、日、月、星期(例如 0 0 * * * 表示每天午夜,*/15 * * * * 表示每十五分钟),或
  • 宏 @hourly、@daily、@weekly、@monthly、@yearly 之一。

当 form: scheduled 时,schedule 为必填,且仅在此时有意义。没有 schedule 的 form: scheduled 工作负载、既不是 5 字段表达式也不是可识别宏的 schedule(6 字段且以秒开头的表达式、无法识别的 @ 标记,或含非法字符的字段),或在任何其他形态上设置的 schedule,都会导致构建时中止,并指出修复方法。helm provider 将该值原样传入生成的 CronJob 的 spec.schedule。

apiVersion: aggrega.ai/v1beta1
kind: Workload
form: scheduled
schedule: "0 2 * * *" # daily at 02:00
containers:
report:
image: "reporter:1.0"
command: ["/report"]

suspend

suspend 暂停 form: scheduled 工作负载的周期性调度。它是布尔值,默认为 false。设置 suspend: true 时,调度资源仍会连同其 schedule 一起渲染,但在恢复之前不会按该调度启动任何运行,而且仍可以从该资源手动启动一次运行。这正是只应在有人请求时才运行的任务所需的形态。

helm provider 将该字段输出为 CronJob 的 spec.suspend: true。在 Kubernetes 上,kubectl create job <name> --from=cronjob/<cronjob> 会从已暂停的 CronJob 启动一次运行,而一旦 spec.suspend 重新为 false,调度即恢复。suspend: false 的渲染结果与省略 suspend 完全相同,因此在设置之前,该字段不会改变任何输出。compose provider 没有调度形态,对任何 form: scheduled 工作负载都会中止构建,无论是否暂停。

在任何其他形态上设置 suspend: true 都会在构建时中止,并指出修复方法:其他形态都没有可供它暂停的调度。

apiVersion: aggrega.ai/v1beta1
kind: Workload
form: scheduled
schedule: "0 2 * * *" # documents when it would run; nothing starts it while suspended
suspend: true
containers:
report:
image: "reporter:1.0"
command: ["/report"]

replicas

表示工作负载副本数的单个整数。省略时默认为 1。可使用模板表达式由 Ops 声明的规格驱动副本数:

replicas: {{ optional .infra `replicas` 1 }}

containers 与 initContainers

containers 是以容器名为键的有序映射。容器 0(第一个映射键)对 Kubernetes 输出中的 pod-spec 顺序以及默认容器语义很重要。initContainers 是 init 容器条目的有序列表,每个条目带有 name、image,以及与主容器相同的变量/密钥/卷挂载编写形态。

initContainers 条目上的 name 是可选的。省略它的条目命名为 init-<index>,其中 index 是该条目在列表中的位置,从 0 开始计数。由于名称在渲染输出和任何提及该容器的诊断中标识容器,值得引用的条目也值得显式命名。

保持作者顺序是 Workload 模型的一项关键契约:编译器在每次构建中都按 Recipe 作者声明的顺序分别生成 containers、volumes、services、容器 ports、容器 variables 和容器 attachments。Recipe 作者可以依赖这一有序形态:当运行时发生的事情依赖顺序时(sidecar 启动、环境变量中的 $(VAR) 链式引用、引用先前声明卷的 volumeMounts),在上述每个集合内,编写顺序就是运行时顺序。容器的环境由其中两个集合组合而成,在两者之间,执行合成的 provider 先写入读取 attachment 的条目(以 as: env 交付的 attachments),再写入普通 variables,每类条目内按编写顺序。因此在 Kubernetes 目标上,变量可以用 $(NAME) 引用其容器中任何读取 attachment 的变量以及在它之前声明的任何变量(见 helm provider 的环境变量顺序)。如果容器把同一个名称既作为 variables 条目、又作为以 as: env 交付的 attachments 条目给出,构建会中止,因为仅凭该顺序就会决定进程看到两个值中的哪一个(见 A container gives one environment variable two values(容器为一个环境变量提供了两个值))。

容器字段的编写遵循以下约定:

  • image 通常是引用 .values.image(开发者所选镜像)的模板表达式,可选用 .infra.* 覆盖来添加特定环境的镜像仓库前缀。
  • variables 是用于环境变量的普通 string → string 映射。该映射通过 Go 模板表达式融合两种不同的数据来源:开发者支柱字面量(模板表达式读取 .values / .infra / .locals 的条目,其载荷源自该 Component 的支柱)和跨组件管道数据(模板表达式读取 .context.inject.env.<KEY> 的条目,其载荷源自另一个组件的 provides: 并经拓扑管道路由)。两种来源流入同一个 variables 映射;作者根据值是组件本地的还是跨组件派生的,为每个条目选择其一。常见模式:LOG_LEVEL: "{{ .values.log_level }}" 属于开发者支柱(组件本地);DB_HOST: "{{ .context.inject.env.DB_HOST }}" 属于跨组件管道(该值源自目标组件的 provides.host,经调用方的 uses[].inject.env.DB_HOST 声明路由)。两种形式都会编译为渲染后 Deployment 上的单个 Kubernetes env: 列表;双来源语义只存在于编写时。
  • attachments 引用该 Component 的 featuresSchema 中声明的槽位,或通过指定连接名,引用该连接的 socket 声明的槽位(见下文集成一节)。
  • ports 是命名端口映射(web: 8080、admin: 9901);端口名与容器作用域内的端口名对应,并通过 services.<service>.ports.<portname> 引用。使用目标默认值以外传输协议的端口改用展开形式编写,见下文 端口传输协议。
  • volumeMounts 按名称引用在该 Workload 的 volumes: 部分中声明的卷。
  • resources 声明容器的 requests 和 limits:cpu 和 memory 数量,以及可选的用于 GPU 和其他设备的扩展资源键(见下文 GPU 与设备工作负载)。
  • health 使用意图形态(http: /path、tcp: <port>、exec: [cmd, ...]),见下文健康探针一节。

volumes

每个卷只能是一种类型:ephemeral、configmap、secret、persistent 或 persistentTemplate。在单个卷声明中这些类型互斥;每种类型都有各自的必填字段:

volumes:
app-config:
configmap:
source: "{{ .locals.app_cm }}"
data:
persistent:
size: "10Gi"
class: "gp3"
cache:
ephemeral:
sizeLimit: "1Gi"

persistentTemplate 在 StatefulSet 形态的转换中生成每副本一个的 PVC;在 compose 转换中,它降级为单个共享的命名卷,并随构建报告一条警告。生成的文件本身不带任何关于该降级的说明——它与没有该警告时逐字节相同。

**各 provider 的转换。**每个 provider 将五种卷变体转换为其原生形态:

变体Helm / helm-chart(K8s)Compose损失说明
ephemeralemptyDir: { sizeLimit }服务级 tmpfs: 条目,指明挂载路径(内存中)Compose 的 tmpfs 以内存为后端;helm 的 emptyDir 默认以节点磁盘为后端——底层存储介质存在语义差异。sizeLimit 不会出现在 compose 输出的任何部分:生成的条目只有挂载路径。编写了 sizeLimit 会产生一条指明它的 unsupported-field 警告,该警告随构建报告,而不写入生成的文件。
configmapConfigMap 卷引用(使用由 Recipe 的 artifacts: 或某个 Feature 生成的 ConfigMap 资源)服务级 configs: 引用,指明该 configmap,挂载在卷挂载的路径上;对应的顶层 configs: 条目来自 Recipe 的 artifacts:两个目标都按名称引用 configmap,且都不读取其内容,因此编写形态是对称的。compose 失去的是 K8s ConfigMap 在滚动发布时更新的语义:compose 配置固定为构建所生成的内容。若某个引用没有可解析的顶层条目,构建会停止,而不是生成一个在运行时悬空的挂载。
secretSecret 卷引用(使用凭据附件所指明的 Secret——由其 FeatureRecipe 生成的,或已存在的)对环境变量形态的 secret 使用 env_file:,对路径形态的 secret 使用绑定挂载的 secret 文件Compose 缺少一等的 Kubernetes Secret 语义。路径形态的 secret 有意不采用 configmap 变体的 configs: 路径:内联的 config 条目会把 secret 的值以明文写入生成的 compose 文件,而编译器从不将 secret 解析为明文。绑定源是运维人员在 compose 主机上使其可访问的路径,处于任何 vault-fetch CRD 生命周期之外。
persistentPVC 资源 + volume.persistentVolumeClaim命名卷Compose 命名卷是扁平的主机侧抽象;helm 的 PVC 支持存储类、访问模式和容量声明,而 compose 会忽略这些。
persistentTemplateStatefulSet.volumeClaimTemplates(每副本 PVC;form: stateful 的配套)命名卷(降级——所有副本共享单个卷,并报告一条警告)Compose 无法表达每副本模板。将 persistentTemplate 转换为 compose 时,会生成单个命名卷,降低的保真度作为警告随构建报告,而不写入生成的文件。依赖每副本卷隔离的 Workloads 不应以仅 compose 的边界为目标。

控制器形态由 workload 的 form 选择,而不是由其卷决定。当 form: stateful 时生成 StatefulSet;persistentTemplate 卷是该 form 的配套——它在已具备 StatefulSet 所提供的每副本身份的 workload 上声明每副本存储。在任何其他 form(或默认的 stateless)上声明 persistentTemplate 卷是构建时错误,并指明修复方法:declare form: stateful。反之是允许的——form: stateful 的 workload 无需声明 persistentTemplate 卷。需要 StatefulSet 语义的作者直接设置 form: stateful。

在 helm provider 上,form: stateful 的 workload 需要一个 headless 管理 Service:在同一 Workload 中声明恰好一个 type: Headless 的服务。provider 将 StatefulSet 的 serviceName 连接到该 headless Service(它提供 StatefulSet 所需的稳定的每 pod 网络身份)。如果未声明 headless 服务——StatefulSet 没有可指明的管理 Service——或声明了多个,导致管理 Service 不明确,构建都会停止。StatefulSet workload 仍可在这一个 headless 管理服务之外声明其他非 headless 服务(例如用于客户端访问的 ClusterIP 服务)。

资源数量

以下 Workload 值是数量——以 Kubernetes 表示资源的记法写出的量:容器(或 init 容器)的 resources.requests 和 resources.limits 中 cpu、memory 及每个扩展资源键的值,以及卷的 ephemeral.sizeLimit、persistent.size 和 persistentTemplate.size。Workload schema 将它们都定义为字符串类型,且不约束其形式。为目标合成 Workload 的 provider 会检查它生成的每个数量,并且检查的是经 Recipe 模板求值后的 Workload,因此通过 infra、Release 参数或任何其他模板输入传入的值,都按其渲染出的字符串来判定。

一个数量由以下部分组成,前后不带任何其他内容:

  • 可选的符号,+ 或 -;
  • 至少含一位数字的数——2、0.5、.5 或 1.;
  • 至多一个指数——e 或 E、可选符号,再接数字,如 1e3 或 5E-2——或一个单位后缀:十进制后缀 n、u、m、k、M、G、T、P 或 E(10⁻⁹ 到 10¹⁸,以千为步长),或二进制后缀 Ki、Mi、Gi、Ti、Pi 或 Ei(1024 到 1024⁶)。

500m、0.5、2、128Mi、1.5Gi、1e3、5n 和 4u 是数量;lots、1.5 cores、1 gigabyte、10 GB 和 1e1.5 不是——指数必须是整数。数后单独的 E 是表示 10¹⁸ 的十进制后缀(12E);其后跟数字时则开始一个指数(1E3)。

这正是 Kubernetes 自身的数量解析器接受的形式,仅有一处有意的不同:数部分不含数字的字符串——m、Ki、+、.、e5——会被拒绝,而 Kubernetes 会将其读作零。这样的字符串恰恰是模板在所插入的值为空时留下的结果:cpu 为空时,"{{ .infra.cpu }}m" 渲染为 m。拒绝它,会把空输入变成一次指明该字段的停止,而不是变成一个无人报告的零大小请求。

各目标如何处理数量:

  • helm 按原样生成每个数量,但先按上述形式逐一检查。不符合的值会使构建停止,错误中指明节点、该字段在 Workload 中的路径——containers.main.resources.requests.cpu、initContainers[0].resources.limits.memory、volumes.data.persistent.size——以及该值。参见 Helm Provider → Workload(合成)模式。
  • compose 根据解析出的值将 cpu 和 memory 转换为其自身的单位:cpus 变为十进制核数(500m → 0.5),memory 变为精确的字节数(1.5Gi → 1610612736)。不是数量的值会使构建停止,compose 无法精确表示的数量同样如此——负数、不是整数字节的内存量(1500m),或精度超过一个核的九位小数的 cpu 量——错误会说明遇到的是这两种情况中的哪一种。nvidia.com/gpu 计数以同样方式读取并变为设备数,因此不是整数个设备的值也会停止。compose 不生成其他扩展资源,也不生成卷大小,因此两者都不检查:任何其他扩展资源键和 ephemeral.sizeLimit 会被丢弃并给出警告,而持久卷大小不影响其输出中的任何内容。参见 Compose Provider → 容器资源。

该检查只判定形式。集群能否调度该数量,或该数量是否适合其设备,都不在检查范围内。

services

服务暴露的有序映射。每个服务声明其类型(ClusterIP、Headless、NodePort、LoadBalancer、Loopback)——即其端口的可达范围——以及一个命名端口映射。端口名称必须与 Workload 中其他位置声明的容器端口名称一致:

services:
http:
type: ClusterIP
ports:
web: 8080 # must exist in containers.<name>.ports

在单个 Workload 上声明多个服务很常见,用于分别暴露内部和外部流量(内部 ClusterIP 供集群内消费者使用,LoadBalancer 用于外部流量,ClusterIP 用于 Prometheus 抓取)。

服务端口的可达范围。 由 type 声明,每个目标以各自的方式渲染:

type可达范围helmcompose
ClusterIP该 workload 的对等方,位于目标自身的网络上类型为 ClusterIP 的 Service不发布任何端口;对等方在 compose 网络上访问该端口
Headless同上,但没有集群地址类型为 ClusterIP 且带 clusterIP: None 的 Service不发布任何端口
NodePort超出目标自身的网络类型为 NodePort 的 Service每个端口发布在所有主机接口上,形式为 <service port>:<container port>
LoadBalancer超出目标自身的网络类型为 LoadBalancer 的 Service与 NodePort 相同
Loopback仅限主机自身的回环地址中止构建,并指明该服务每个端口发布在 IPv4 回环地址上,形式为 127.0.0.1:<service port>:<container port>

服务端口的编号与它所指明的容器端口是两个数字,正如 Kubernetes Service 的 port 和 targetPort 一样:helm 将条目的编号写为 Service 的 port,并按名称指向容器端口;compose 则将条目的编号发布在主机上,映射到容器端口的编号。两个数字相等时,compose 在两侧都写该数字。

Loopback 用于同一台机器上的程序(如在主机上运行的浏览器或代理)需要访问、而其他任何程序都不应访问的端口。在 compose 上,绑定仅限 IPv4 回环地址:IPv6 回环地址 ::1 不会被绑定,因此应通过 127.0.0.1 访问该端口,而不是通过可能解析为 ::1 的名称。声明的传输协议会像任何已发布端口一样写在条目上,如 127.0.0.1:5514:5514/udp。

当两个条目指向同一端口时,可达范围更广的一方胜出:由 NodePort 或 LoadBalancer 条目发布的端口会发布在所有接口上,即使 Loopback 条目也指向它,无论两者谁先声明。

在 helm 上,Loopback 条目会中止构建,而不是渲染成与其含义不符的内容。Kubernetes Service 没有绑定到主机回环地址的类型——NodePort Service 监听哪些节点地址是整个集群的设置,而非单个 Service 的设置——因此 ClusterIP Service 会丢失该条目要求的可达范围,而 NodePort Service 会将端口发布在集群允许的每个节点地址上。中止信息会指明节点和服务;参见 A service type the helm provider cannot render(helm provider 无法渲染的服务类型)。

合成名称约定。 当 helm provider 合成 Workload 的服务时,每个 Service 的 metadata.name 由该 workload 自身控制器所带的名称和服务的编写键确定性地派生。对于组件的 Workload,该名称就是节点的 release 名称:<release name>-<service-key>。release 名称是 component 的标识按 Kubernetes 名称允许的字母表写出的结果——与 chart 渲染所用的名称相同,在 Recipe 的模板中可通过 {{ .context.rendered_name }} 读取——因此只要标识中不含下划线和大写字母,它就等于 instance_id。在节点 api-server 上声明 services.http 的 Workload 会生成名为 api-server-http 的 Service;同一 Workload 在节点 billing 上生成 billing-http,在节点 my_api 上生成 my-zuapi-http。输出文件名遵循相同的约定:<release name>-<service-key>-service.yaml。发布此类 Service 地址的 Recipe 应基于 {{ .context.rendered_name }} 构建地址,而不是 {{ .context.instance_id }},后者在两者不同时不对应任何 Service——参见 ../templates/rendered-resource-names.md。

由 Feature 挂载的 FeatureRecipe 合成的 Workload 以挂载自身的组合标识而非 release 名称命名:即其资源在 aggrega.ai/component-id 标签中所带的值,由宿主组件和写在 features: 下的键组成,并以开头的 cfr-- 为前缀。在那里派生的 release 名称会是宿主的名称,从而会按宿主自身资源的名称来命名挂载的资源。因此,对于节点 front-door 上的挂载 stats,其 Workload 声明了 services.scrape 的 FeatureRecipe 会生成 Deployment cfr--front-door--stats 和 Service cfr--front-door--stats-scrape。该第一段永远不等于 instance_id,FeatureRecipe 的模板上下文中也没有任何键携带它:在挂载的模板中,{{ .context.rendered_name }} 和 {{ .context.instance_id }} 都指向宿主(front-door),而 {{ .attachment_name }} 仅为键本身(stats),因此在宿主声明了 scrape Service 时,{{ .context.rendered_name }}-scrape 指向的是宿主自身的该 Service,而永远不会是挂载的——参见 ../templates/rendered-resource-names.md。输出文件位于挂载输出的每个文件都带有的前缀之后——宿主名称和挂载名称,各自后跟 --——因此该 Service 被写入 front-door--stats--cfr--front-door--stats-scrape-service.yaml。

该约定有两个实际后果。第一,跨节点冲突在构造上不可能发生——名称前缀使边界内各节点的服务彼此区分,因为两个不同的标识总会得到两个不同的 release 名称,挂载的标识同时包含其宿主和其键,而且组件名称不得以 cfr-- 开头(以其开头的组件会使构建中止——参见 Component identity cannot be stamped on what it emits(无法将 Component 标识标记到其输出上)),因此两个各自声明 services.http 的 Workload 会生成名称互不重叠的不同 K8s Service 资源。唯一的残余情况是挂载标识对目标而言过长:它会围绕整体的摘要被缩短,而两个缩短后的标识原则上可能相同——参见渲染输出上的来源标签。第二,Workload 不能两次声明同一个服务键——在解析 Workload 的 YAML 时,两次指定同一键的 services: 映射会被拒绝,构建会中止并指出该键及其所在行。

仍然存在的冲突风险在于 K8s 名称长度边界:Kubernetes Service 名称上限为 63 个字符,当两段都较长时,合成的 <release name>-<service-key> 形式可能超出该限制。Aggrega 编译器不强制执行该限制;构建会输出该 Service,而 Kubernetes 会在应用时拒绝它。实例 ID 嵌套较深(例如 data-layer.regional.eu-west.primary)且服务键较长的作者,应将组合长度控制在 63 个字符以内。挂载的 Workload 同样如此:对目标而言过长的组合标识会被缩短,但附加在其后的服务键不会,因此带有长键的挂载 Service 仍可能超过 63 个字符,且构建不会中止。

Provider 特定说明(compose)。 compose provider 根据 IR 的 uses 边自动推导 depends_on。这些条目以无门控方式输出——无论目标是否声明了 healthcheck,它们都带有 service_started 语义——因此,所有依赖都来自 uses 边的服务会输出短格式列表(depends_on: [<target>])。尚未实现以目标的健康状态为边推导条目设置门控。当某个条目确实带有条件时,会输出长格式,等待 init container 就是以这种方式表达的;参见 providers/compose.md。

端口传输协议

容器端口可以用两种等价形式之一编写。裸数字是简写形式,不声明传输协议,因此由目标应用其自身的默认值——在每个有默认值的目标上都是 TCP:

containers:
main:
image: "{{ .values.image }}"
ports:
web: 8080

展开形式同时携带端口号和传输协议,当端口承载的不是该默认协议时,就需要使用这种形式:

containers:
main:
image: "{{ .values.image }}"
ports:
web: 8080 # short form — no transport declared
dns:
port: 53
protocol: UDP # TCP | UDP | SCTP
sigtran:
port: 2905
protocol: SCTP

两种形式可以在同一个 ports 映射中自由混用,无需声明传输协议的端口保持简写形式。

传输协议只在容器端口上声明一次。 services.<service>.ports 条目指向一个容器端口,并沿用该端口的传输协议,因此服务暴露不可能与容器打开的端口不一致。服务端口上没有 protocol 键,编写该键会被拒绝。

该字段为何存在。 部署目标会把未指定的传输协议视为流式协议。需要数据报端口的组件——实时媒体、电话、域名解析、私有网络、游戏服务器——否则只能声明端口号,于是整个栈部署后所有检查都会通过,却没有任何客户端能连上,因为流量是数据报,而打开的端口不是。声明传输协议正是让这一点得以表达的方式。

编译器不解释该值。 它不会从端口的名称中推断传输协议,也不会检查所声明的传输协议是否与端口背后进程实际使用的协议一致:该值是你声明、由目标引擎输出的数据。名为 dns 且不带 protocol 键的端口是 TCP 端口,名为 web 且声明了 protocol: UDP 的端口是 UDP 端口。

各目标的行为。

目标未声明传输协议的端口已声明的传输协议
helmcontainerPort 和 Service 端口都不带 protocol 键原样输出为容器端口以及每个指向它的 Service 端口上的 protocol:
compose发布为 <host>:<container>,不作改动发布为 <host>:<container>/tcp 或 /udp;SCTP 在 compose 中没有对应写法,会中止构建,而不是发布一个承载不同传输协议的端口

没有任何服务发布的容器端口根本不会出现在 compose 文件中——这是 compose 对容器端口的一贯行为——因此在这种端口上声明的传输协议无处可写,也不会导致中止。

健康探针——意图形态

每个容器在其自己的 health: 键(containers.<name>.health)下以抽象的意图形态声明探针;Workload 没有顶层 health。每个 provider 在合成时将意图翻译为其原生的探针形态。

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

三种意图形式(http:、tcp:、exec:)在单个探针声明中互斥。对于未显式指定端口的 http:,端口解析取容器在 containers.<name>.ports 下声明的按字母顺序排在首位的端口名称——两个目标采用同一规则,因此无论由哪个目标渲染,探针读取的都是同一个端口。未声明任何命名端口的容器不能携带 HTTP 探针:构建会中止,并给出指明出错探针的翻译错误。

各 provider 的翻译。 每个 provider 在合成时将抽象的探针意图翻译为其原生形态:

意图Helm(K8s)Compose损失说明
http: /pathhttpGet.path: /path, httpGet.port: <alphabetically-first port name>CMD-SHELL "curl -f http://localhost:<port>/path"Compose 缺少原生的 HTTP 探针形态;CMD-SHELL 包装依赖容器镜像中存在 curl。
tcp: <port>tcpSocket.port: <port>CMD-SHELL "nc -z localhost <port>"Compose 缺少原生的 TCP 探针形态;CMD-SHELL 包装依赖容器镜像中存在 nc。
exec: [cmd, ...]exec.command: [cmd, ...]CMD [cmd, ...]一对一映射;两个 provider 都原样携带命令列表。

Compose 的 CMD-SHELL 包装通过可由 shell 求值的谓词来近似 HTTP 和 TCP 探针。compose 缺少的是原生探针形态,而不是计时字段:编写的 periodSeconds、timeoutSeconds、failureThreshold 和 initialDelaySeconds 会作为 interval、timeout、retries 和 start_period 带入 healthcheck——逐字段映射见 providers/compose.md 的“Probes”一节。原生的 exec: 形态完全不需要包装,在两个目标上均一对一翻译。

包装后的探针是静默转换的:生成的 docker-compose.yaml 中没有任何标记,也没有诊断报告这种包装。在这条路径上,构建确实会报告的是完全不进入任何输出的探针槽位:一个 compose 服务只携带一个 healthcheck,因此当 Workload 声明了 ready:、live: 和 startup: 中的多个时,只转换优先的槽位(优先顺序依次为 live、ready、startup),并发出一条 unsupported-field 警告,指明被转换的槽位和被丢弃的槽位。

Provider 特定说明(compose)。 在面向 compose 的 Workload 上编写 health: 块,并不会让 depends_on 的顺序以健康状态为门控:compose provider 从 uses: 边推导出的 depends_on 条目始终使用 service_started 语义,无论目标 Workload 是否声明了健康探针。以目标的健康状态为这些条目设置门控尚未实现:能够携带此类条件的长格式本身已经会生成(用于 init 容器等待),因此缺少的是以健康状态为边设置门控的选择,而不是表达它的结构。完整的推断规则见 providers/compose.md。

K8s 形态的透传字段——scheduling、serviceAccount、podSecurityContext

Workload schema 接受三个可选的顶层字段,它们主要用于在保留 Aggrega 结构形态的同时,通过 helm provider 传递 Kubernetes 原生原语。compose provider 会转换其中在 Compose 中有对应物的子集,其余部分则忽略并发出警告。Aggrega 校验外层形态,但不检查内部内容(参见下文的校验范围)——K8s 原生的内部值会原样透传到 helm 渲染的 pod spec 中。

scheduling

scheduling 将四个 K8s 原生调度原语——nodeSelector、affinity、tolerations、topologySpreadConstraints——归入一个按用途组织的块中。每个子字段的形态与对应的 Kubernetes pod-spec 字段完全一致:

apiVersion: aggrega.ai/v1beta1
kind: Workload
scheduling:
nodeSelector:
disktype: ssd
region: us-east-1
tolerations:
- key: dedicated
operator: Equal
value: gpu-workloads
effect: NoSchedule
affinity:
podAntiAffinity:
preferredDuringSchedulingIgnoredDuringExecution:
- weight: 100
podAffinityTerm:
labelSelector:
matchLabels: { app: "{{ .context.instance_id }}" }
topologyKey: kubernetes.io/hostname
topologySpreadConstraints:
- maxSkew: 1
topologyKey: topology.kubernetes.io/zone
whenUnsatisfiable: ScheduleAnyway
containers:
app: { image: "..." }

Provider 转换。 helm provider 将每个子字段原样传入渲染后的 pod spec。compose provider 对这四项都不转换:它省略整个 scheduling 块,并发出一条指明该块的警告。

serviceAccount

serviceAccount 是一个普通字符串,携带 workload 运行时所用的 ServiceAccount 的名称:

apiVersion: aggrega.ai/v1beta1
kind: Workload
serviceAccount: "{{ .context.rendered_name }}-runner"
containers:
app: { image: "..." }

该名称由 {{ .context.rendered_name }} 构建,即 helm provider 用来命名 workload 自身资源的 release 名称,因此无论 component 叫什么,它都是集群可接受的名称。该字段引用一个已存在的 ServiceAccount,而不会创建它。配套的 RBAC 资源(ServiceAccount 对象本身,以及 Role / RoleBinding / ClusterRole / ClusterRoleBinding)应通过以下两种渠道之一提供:

  • Recipe artifacts:——当 RBAC 是该 Recipe 固有的一部分时(该 Recipe 知道它为特定任务需要特定的 Role)。
  • 带有资源生成的 Features——当 RBAC 是横切关注点时(例如一个 Workload-Identity FeatureRecipe 为每个带有特定标签的 component 附加绑定 IAM 的 ServiceAccount)。

设置了 serviceAccount: 却未确保所指定的 ServiceAccount 存在,会在 apply 时导致 K8s 运行时错误,而不是构建时错误——workload schema 校验不会交叉检查 ServiceAccount 是否存在(根据 AOT 纯度不变式,编译时无法访问集群状态)。

compose provider 会忽略 serviceAccount: 并发出警告;Compose 没有等价的身份绑定概念。

podSecurityContext

podSecurityContext 携带 pod 级的安全原语——UID、GID、fsGroup、supplementalGroups——它们作用于 pod 中的每个容器:

apiVersion: aggrega.ai/v1beta1
kind: Workload
podSecurityContext:
runAsUser: 1000
runAsGroup: 3000
fsGroup: 2000
supplementalGroups: [4000, 5000]
containers:
app: { image: "..." }

字段语义。 四个字段均为整数(数字形式的 UID/GID,而非字符串);runAsUser 和 runAsGroup 设置容器进程的有效 UID/GID;fsGroup 设置挂载到 pod 中的卷的属组;supplementalGroups 为每个容器的进程组添加额外的 GID。

Provider 转换。 helm provider 将该块原样传入渲染后的 pod spec。compose provider 没有 fsGroup 或 supplementalGroups 的等价物,会逐一省略并发出警告;runAsUser/runAsGroup 在该 Workload 生成的每个服务上(包括 sidecar 和 init 容器)转换为 Compose 的 user: 1000:3000 形式,而旁边没有 runAsUser 的 runAsGroup 会被省略并发出警告。每个容器和 init 容器还各自带有自己的 securityContext——runAsUser、runAsGroup、runAsNonRoot、readOnlyRootFilesystem、allowPrivilegeEscalation 以及 capabilities.add / capabilities.drop。helm provider 在容器上输出它;compose provider 将 readOnlyRootFilesystem 输出为 read_only,将 capabilities.add / capabilities.drop 输出为 cap_add / cap_drop,并将 runAsUser / runAsGroup 输出为容器自身的 user,以取代 pod 的设置;它会省略 runAsNonRoot、allowPrivilegeEscalation 以及未配 runAsUser 而写出的 runAsGroup,并各自发出警告;当容器自身的 runAsUser 使 pod 的 runAsGroup 被排除在外时,它也会发出警告。providers/compose.md 给出了逐字段的映射。

GPU 与设备工作负载

需要专用硬件(GPU 或其他厂商提供的设备)的工作负载表达两个相互独立的关注点:启用设备的节点所暴露的 pod 级运行时(runtimeClassName),以及工作负载按容器申领的设备数量(容器 resources 下的扩展资源键)。典型的 GPU 工作负载会同时声明两者,但二者各自独立,任一个都可以在没有另一个的情况下出现。

这两个字段都描述计算——pod 以及在设备上运行的容器——因此它们属于运行容器的工作负载。只携带外部端点、自身不声明任何容器的工作负载没有可供附加的 pod 或容器:在这种仅含端点的工作负载上设置 runtimeClassName 会使构建中止,并指出 runtimeClassName 以及其 Workload 声明了该字段的 Recipe;而没有容器时,也无处放置设备资源请求。

runtimeClassName

runtimeClassName 是单个字符串,指定 pod 运行所用的 RuntimeClass,即启用设备的节点所暴露的容器运行时,例如名为 nvidia 的 GPU 运行时。它是 pod 级选择器:作用于工作负载中的每个容器。编译器将该名称作为确定性指针原样传递;集群在调度时将其解析为管理员已配置的 RuntimeClass。Aggrega 不检查是否存在匹配的 RuntimeClass(它在编译时无法访问集群状态),因此没有对应已配置 RuntimeClass 的名称会在应用时表现为调度错误,而不是构建时错误。

扩展资源键

容器的 resources.requests 和 resources.limits 承载普通的 cpu 和 memory 数量,并在其旁承载扩展资源键:以完全限定的 <domain>/<name> 名称(如 nvidia.com/gpu 或 amd.com/gpu)为键、限定于厂商或领域的设备数量。域段至少包含一个点,正是这个点将扩展键(nvidia.com/gpu)与裸的 cpu 和 memory 数量区分开来。每个值都是字符串数量("1"、"2"),编译器原样传递,helm provider 在输出前检查其格式(参见资源数量);集群的设备插件在调度时解析并分配设备。

完整示例——GPU 推理工作负载

apiVersion: aggrega.ai/v1beta1
kind: Workload
runtimeClassName: nvidia
containers:
inference:
image: "{{ .values.image }}"
resources:
requests:
cpu: "2"
memory: "8Gi"
nvidia.com/gpu: "1"
limits:
nvidia.com/gpu: "1"

该工作负载为其 pod 选择 nvidia 运行时,并为 inference 容器申领一个 GPU。GPU 数量同时出现在 requests 和 limits 中:设备不可超额分配,因此其请求值与限制值设为相同。

Provider 转换。 这些是 Kubernetes 原生概念。helm provider 在渲染后的 pod spec 上输出 runtimeClassName,并将每个扩展资源键原样输出到容器的 resources.requests / resources.limits 下,因此它们通过 Kubernetes 输出到达集群。compose provider 将 nvidia.com/gpu 的计数在容器的服务上预留为同等数量的 NVIDIA GPU(参见 Compose Provider → 容器资源);单台主机没有运行时类的概念,也没有其他扩展资源键的对应物,因此声明了 runtimeClassName 或其他键的工作负载在 compose 目标上渲染时不包含它们。

在节点的网络上运行

默认情况下,workload 运行在自己的网络命名空间中:其容器只能看到自己的 接口,流量通过目标的地址转换到达它们。hostNetwork: true 请求另一种安排:workload 运行在节点自身的网络命名空间中,因此它 能看到节点的接口,其容器打开的端口可以通过节点自身的 地址访问,中间没有任何转换。

有一整类软件需要这样做。实时媒体、电话、虚拟专用网络 以及类似流量会在载荷中携带对端的地址,因此在传输中被改写的地址 到达时描述的是对端无法访问的位置;在节点的地址上运行,才能让 两者保持一致。

apiVersion: aggrega.ai/v1beta1
kind: Workload
hostNetwork: true
containers:
media:
image: "{{ .values.image }}"
ports:
rtp:
port: 7881
protocol: UDP

它声明什么,不声明什么

hostNetwork 选择的是一个网络命名空间,仅此而已。

  • 它不声明端口。 workload 打开的端口仍然在 containers.<name>.ports 下声明,与不使用它时完全相同,含义也不变。 声明 hostNetwork 既不会添加端口,也不会免去声明端口的必要。
  • 它不声明端口的数量。 需要大量连续端口的应用(例如根据机器处理器数量确定端口范围大小的媒体 服务器)会在自己的配置正文中配置该范围,取值由其运维人员提供,方式与它配置启动时读取的其他任何内容 相同。这是应用设置而非 workload 设置,不属于 workload 契约的范畴。
  • 不做任何推断。 编译器不从该值中解读任何含义,也不从其他任何内容推导出它: 不从端口名称推导,不从 component 的类型或标签推导,也不从声明的端口数量推导。当且仅当 workload 明确声明时,它才在节点的网络上运行。

由于它描述的是计算,hostNetwork 应用于运行容器的 workload。仅携带外部端点的 workload 不声明容器,因此没有可供选择的网络命名空间: 在仅含端点的 workload 上声明 hostNetwork 会中止构建,并指出 hostNetwork 以及 其 Workload 声明了它的 Recipe。

Provider 转换

helm provider 在渲染出的 pod spec 上输出 hostNetwork: true,这正是 Kubernetes 表达同一选择的方式。该声明只影响 pod spec,不涉及其他任何内容:无论有无该声明,输出的 Service 都完全相同。

compose provider 在 workload 自身的服务上输出 network_mode: host。由 compose 对网络的建模方式 会带来一个结果:处于该模式的服务不会连接到边界 网络,因为 compose 将连接到网络与采用主机命名空间视为 二选一,而非可叠加。因此,其对端通过主机自身的地址访问它,而不是 通过服务名称访问(这正是主机网络在任何目标上的含义),边界上的其他服务 均不受影响。

在该目标上,有两种形态与之组合。sidecar 容器无需声明任何内容即可随主服务进入 主机网络,因为它通过指名主服务来采用主服务的命名空间。init 容器则不然:它会成为主服务所等待的 服务,因此它以自身身份加入边界网络,而不是采用一个会使 这种等待形成循环的命名空间。因此,同时声明 hostNetwork 和 initContainers 的 workload 会让 自身服务运行在节点的网络上,而其 init 服务留在边界网络上。这比 pod 形态提供的单一共享命名空间 更为受限,compose provider 会通过 unsupported-field 警告指出这一点,而不是留到运行时才被发现。

未声明 hostNetwork 的 workload 在其输出中不带有该键:该键直接缺失,而不是输出为 false。

与 Component 的 featuresSchema 的附件集成

Workload 的 containers.<name>.attachments 块引用在 Component 的 featuresSchema 中声明的凭据槽位;对于指名某个连接的条目,则引用该连接的 socket 所声明的槽位(参见传递连接所携带的凭据)。它不声明新槽位。关于 featuresSchema 的编写方式,参见 ../entities/component.md。from 指名的是槽位,而不是所生成的 Secret 的名称。

containers.<name>.attachments 条目会渲染为对 Secret 资源的引用:Kubernetes secretKeyRef(用于 as: env)或基于 secret 的卷(用于 as: file),两者都按名称指向该 Secret。合成器根据槽位公开的 provides 解析该名称和数据键:条目渲染出的 secretKeyRef.name 是槽位的 .features.<slot>.provides.name,数据键是 .features.<slot>.provides.key。Recipe 作者只需编写 from: <slot> 和 as: env;合成器读取已解析的 provides,而不会重新推导名称。这与源 Recipe 为 existingSecret 读取的 .features.<slot>.provides.<key> 相同:同一个凭据槽位以完全相同的方式同时供给源 Recipe 使用方和合成 Workload 使用方(源/workload 对称)。

该集成受四条校验规则约束:

  • 每个 attachments.<KEY>.from 值都必须与 Component 的 featuresSchema 中声明的槽位名称匹配;对于指名某个连接的条目,则须与该连接的 socket 中声明的槽位名称匹配。未知的槽位名称属于加载时错误。
  • as: 传递机制(env 或 file)必须出现在 Component 为该槽位声明的 inject: 允许列表中。若 Workload 对一个 featuresSchema 条目指定了 inject: [env] 的槽位声明 as: file,则属于加载时错误。
  • 在 Component 的 featuresSchema 中标记为 inject: [](黑盒传递)的槽位完全不能出现在 Workload 的 attachments: 块中。这些槽位由 Recipe 的内部管道传递(例如 Helm chart 的 existingSecret 参数),而不是通过 Workload 公开传递。
  • 被引用的槽位必须是可引用的:其填充必须为某个 Secret 资源发布 provides 定位符(name、key),该 Secret 可以由其实现输出,也可以是已存在的。由 inject 传递的凭据(将值写入 inject 管道且不发布定位符)所填充的槽位没有可指向的对象;从 Workload 的 attachments: 条目引用它属于加载时错误。inject 传递的凭据通过槽位的 inject 管道(读取 .context.inject.env.<KEY> 的 variables 条目)到达容器,而不是通过 attachments: 条目。

Provider 说明。 Helm 渲染上文所述的 secretKeyRef/secret 卷引用。compose provider 没有原生的从 secret 读取环境变量的原语;面向 compose 的 Workload 上的 as: env 附件条目会渲染为值为空的环境条目,并附带指出该条目的警告(参见 compose provider 页面),而可引用性规则(与能力无关)仍然适用。

示例:

# In the Component catalog entity
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's Workload
workload: |
containers:
main:
attachments:
DB_PASSWORD: # OK — db_password slot allows env inject
from: db_password
as: env
# ROOT_PASSWORD: ... # rejected at load time: blackbox slot

传递连接所携带的凭据

Component 的 socket 可以在 usesSchema.<socket>.featuresSchema 中声明经由它连接的每个连接所填充的槽位,这样访问多个目标的 component 会为每个连接持有一个凭据,而不是为所有连接共用一个。这样的附件不在 component 自身的 .features 中,而是位于其连接之下,即 .context.uses.<alias>.features.<slot>。Workload 条目通过在槽位旁指名该连接来传递它:

  • 在容器的 attachments 条目上,在 from: <slot> 旁写 connection: <alias>;
  • 在容器的 envFrom 条目上,在 secret: <slot> 旁写 connection: <alias>;connection 只能与 secret 并列使用。

两种形式在每个容器和每个 init 容器上都可使用。<alias> 是该连接在 component 的 uses 块中(位于 Aggregate 或 Release 上)所使用的名称,也就是 Recipe 在 .context.uses 下读取该连接所用的键;<slot> 是该连接所经由的 socket 声明的槽位。

在上述任何规则读取 Workload 之前,每个指名连接的条目都会被改写为该连接在该槽位中所携带的附件在 component 上采用的名称:别名、一个点号和槽位(gpt.credential)。随后每条规则在改写后的条目上的运行方式,与在指名 Component 自身槽位的条目上完全相同:socket 槽位的 inject: 允许列表约束 as:,声明了 inject: [] 的 socket 槽位不能被引用,填充它的附件必须可引用,provider 根据该附件已解析的 provides 解析 Secret 的名称和数据键,因此每个连接的条目都引用该连接自己的凭据。声明了 sensitive: true 的 socket 槽位,对该条目的读取方式与 Component 槽位的声明完全相同。provider 接收的是改写后的条目;connection 键不会传到 provider。

有三种条目会被拒绝,每种拒绝都会指出它所指名的内容:

  • 指名了 component 未使用的连接的条目:拒绝信息会指出该连接、该槽位,以及 component 实际使用的连接;
  • 指名了连接的 socket 未声明的槽位的条目:拒绝信息会指出该槽位、该连接、该 socket,以及它声明的槽位;
  • 自行写出组合名称(from: gpt.credential)的条目。连接的槽位通过指名连接来指名,因此组合名称从来不是访问它的第二种方式。

若连接在该槽位中不携带附件,条目就没有可引用的对象,可引用性规则会拒绝它。由 FeatureRecipe 渲染的 Workload 只限于其所实现的 Feature 声明的槽位,而这些槽位不涉及宿主 component 的任何连接,因此其中指名连接的条目会以指名了 component 未使用的连接为由被拒绝。

示例:

# In the Component catalog entity
spec:
usesSchema:
models:
featuresSchema:
credential:
sensitive: true
inject: [env]
# In the Recipe's Workload — the component draws connections `gpt` and `nim`
# through the `models` socket, each carrying its own `credential`
workload: |
containers:
main:
attachments:
MODEL_KEY_GPT:
from: credential
connection: gpt
as: env
MODEL_KEY_NIM:
from: credential
connection: nim
as: env

在 helm 上,MODEL_KEY_GPT 渲染为一个 secretKeyRef,指向 gpt 连接的凭据所发布的 Secret,MODEL_KEY_NIM 则指向 nim 连接的凭据所发布的 Secret。在 compose 上,指名连接的 as: env 条目输出时值为空,并附带与指名 Component 自身槽位的条目相同的部分支持提示。

验证范围

每个 Workload 都在 Recipe 加载时、任何渲染运行之前接受验证。验证分为两个阶段:

  • Schema 验证。 Workload 值与内嵌的 aggrega.ai/v1beta1 Workload schema 进行合一。错误会携带字段路径和被违反的约束(例如 .containers.main.health.ready: multiple oneOf branches matched (branches [0, 1] of 3): expected exactly one)。Schema 验证会强制执行 schema 中声明的每个类型、枚举、范围和析取——包括封闭集合的控制器 form(stateless、stateful、daemon、scheduled、task、reference 之一)、封闭集合的服务 type(ClusterIP、Headless、NodePort、LoadBalancer、Loopback 之一)、整数端口范围(1..65535)、探针形态析取(http、tcp、exec 恰好其一),以及卷变体析取(ephemeral、configmap、secret、persistent、persistentTemplate 恰好其一)。
  • 交叉引用验证。 Workload 的 attachment 引用会对照 Component 的 featuresSchema 进行检查——对于指名某个连接的条目,则对照该连接的 socket 所声明的槽位——(槽位归属、as: 交付允许列表、黑盒排除),并对照每个被引用槽位已解析的 provides 进行检查(可引用性——填充必须发布 name/key)。这些是跨实体检查,仅靠 schema 验证无法完成。

两个阶段产生相同的、以 CATALOG_ERROR 为前缀的消息形态;失败会在产生任何渲染输出之前终止构建。Recipe 作者会得到有针对性的反馈,指出失败的确切字段以及拒绝它的约束。

K8s 形态的透传字段(scheduling.affinity、scheduling.tolerations、scheduling.topologySpreadConstraints、ConfigMap 和 Secret 卷中的 items 列表、lifecycle httpGet 钩子)只做结构验证——Aggrega 的 schema 约束它们是否存在及其外层形态,而这些由 K8s API 定义的值的内部形态由 provider 负责(helm provider 将它们原样交给 K8s pod spec;compose provider 视情况拒绝或降级处理它们)。使用形态错误的 affinity 值的 Workload 会通过 Aggrega 验证,错误改为在 provider 合成期间暴露。

同样,资源数量对 schema 而言是字符串:两个阶段都不检查其格式。负责合成的 provider 会在求值后的 Workload 上检查,并在值不符合数量格式时中止——参见资源数量。

辅助资源应置于 Workload 之外

Workload 只描述工作负载的形态:容器、卷、服务、副本、调度、安全上下文、服务账号。它没有 additionalResources 字段,也不支持内联的 ConfigMap / Secret / CRD 声明。

Recipe 作者通过 Workload 之外的两个渠道输出辅助资源:

  • Recipe 级别的 artifacts::用于该 Recipe 固有的资源(该 Recipe 的 Workload 引用的某个特定 ConfigMap、该 Recipe 所需的一次性 CRD 注册)。该字段是由具名条目组成的映射;每个条目可以内联编写,也可以通过逐条目的 $import: 加载。三种编写方式参见 ../../architecture/16-recipe-input-composition.md 中的 Artifacts Mechanism 一节。
  • 带资源生成的 Features:用于通过 Release 选择器附加的横切关注点(附加到每个暴露指标的组件上的 ServiceMonitor Feature、附加到每个生产工作负载上的 NetworkPolicy Feature)。FeatureRecipe 的编写接口参见 ../entities/featurerecipe.md。

Workload 始终专注于工作负载形态;横切的和 Recipe 固有的辅助清单各有其编写位置。

常见 Workload 模式

Workload schema 覆盖面很广——涵盖单容器 HTTP 服务器、多容器 sidecar 模式、init 容器链、批处理作业以及带持久卷的有状态服务。其中三种模式出现得足够频繁,在每个 Recipe 中从零编写样板代码会造成浪费。下面的代码块是可复制粘贴的模板,Recipe 作者可以根据具体组件加以调整。

多个 Recipes 共享的模式可以作为 WorkloadLibrary 条目发布一次,并通过 $import: <Library>#/workloads/<entry> 导入;这里的模板是可供改编的起点,也可以按这种方式发布。

模式 1——暴露指标的服务器

一个典型的 Web 应用,在一个端口上提供应用流量,并在另一个端口上暴露供 Prometheus 抓取的指标。在 Workload 中设置两个 service——一个用于应用,一个用于指标——可以让服务网格策略和负载均衡器配置清晰地分离。

apiVersion: aggrega.ai/v1beta1
kind: Workload
replicas: {{ optional .infra `replicas` 2 }}
containers:
app:
image: "{{ .values.image }}"
ports:
web: {{ optional .values `port` 8080 }}
metrics: {{ optional .values `metrics_port` 9090 }}
variables:
LOG_LEVEL: "{{ optional .values `log_level` "info" }}"
health:
ready:
http: /healthz
timeoutSeconds: 5
live:
http: /healthz
timeoutSeconds: 5
services:
http:
type: ClusterIP
ports:
web: {{ optional .values `port` 8080 }}
metrics:
type: ClusterIP
ports:
metrics: {{ optional .values `metrics_port` 9090 }}

指标 service 通常通过在 Release 层面附加 Feature 来添加用于 Prometheus 发现的注解(例如 feature.aggrega.ai/prometheus-scrape: "true");Workload 本身不包含特定于 provider 的抓取注解。

模式 2——批处理作业

一个运行至完成、而非无限期提供流量的工作负载。该模式设置 form: task,完全省略 services:——批处理作业不暴露端口——并依赖目标 provider 的任务形态(在 helm provider 上为 Kubernetes Job;compose provider 没有任务形态,遇到 form: task 会中止构建)。helm provider 会固定一个对 Job 有效的 pod restartPolicy(除非容器声明 OnFailure,否则为 Never),因为 Job pod 不能使用默认的 Always。

apiVersion: aggrega.ai/v1beta1
kind: Workload
form: task
containers:
worker:
image: "{{ .values.image }}"
command: ["{{ .values.entrypoint }}"]
args:
- "--config"
- "/etc/config/job.yaml"
variables:
JOB_ID: "{{ .context.instance_id }}-{{ .metadata.release_name }}"
volumeMounts:
- name: config
path: /etc/config
volumes:
config:
configmap:
source: "{{ .context.instance_id }}-config"

config 卷引用一个 ConfigMap,该 ConfigMap 预期由 Recipe 通过 artifacts: 与 Workload 一同输出(参见上文“辅助资源应置于 Workload 之外”)——Workload 本身只声明消费端。在按 identity 命名工作负载的 provider 上(如 compose),由 identity 为其命名;在按 release 名称命名工作负载资源的 helm 下,应改为基于 {{ .context.rendered_name }} 构建 ConfigMap 的名称——此处和 artifact 中都是如此——这样无论组件叫什么,该名称都能被集群接受。

模式 3——Sidecar 对

一个双容器 pod,其中主容器处理应用逻辑,sidecar 处理横切关注点(TLS 终止、日志传输、服务网格代理、AI 护栏)。containers: 中的编写顺序至关重要——helm provider 按声明顺序输出容器;第一个键(此处为 main)是 kubectl logs 及类似工具的默认容器目标。

apiVersion: aggrega.ai/v1beta1
kind: Workload
replicas: {{ optional .infra `replicas` 2 }}
containers:
main:
image: "{{ .values.app_image }}"
ports:
app: {{ optional .values `app_port` 8080 }}
variables:
UPSTREAM_URL: "http://localhost:{{ optional .values `app_port` 8080 }}"
sidecar:
image: "{{ .values.sidecar_image }}"
ports:
proxy: {{ optional .values `proxy_port` 9000 }}
variables:
PROXY_TARGET: "http://localhost:{{ optional .values `app_port` 8080 }}"
services:
external:
type: ClusterIP
ports:
proxy: {{ optional .values `proxy_port` 9000 }}

Service 暴露的是 sidecar 的端口(而非主容器的端口),将外部流量经由 sidecar 通过 localhost 路由到主容器。两个容器共享 pod 的网络命名空间,因此 localhost:<port> 可直接访问对端容器。对于需要注入凭据的 sidecar(典型的 AI 护栏模式),凭据通常位于 sidecar 的 attachments: 块中,而非主容器的块中——从而将凭据的作用范围限定在 sidecar 的进程边界内。

模式选择

这三种模式分别对应不同的交付形态关注点:

  • 暴露指标的服务器——由集群保持运行的长期服务;通过多个 Service 暴露实现流量分离。
  • 批处理作业——有限执行;不暴露 Service;依赖 Recipe 输出的 ConfigMap 或外部状态作为输入。
  • Sidecar 对——共享网络命名空间的多容器 pod;sidecar 的 Service 暴露横切关注点。

第四种模式——带持久卷的有状态服务器——设置 form: stateful,并通过 volumes.<name>.persistentTemplate 声明每个副本的存储;helm provider 会为 stateful 形态输出 StatefulSet(参见 providers/helm.md)。该模式在形态上与“暴露指标的服务器”相同,只是增加了 form: stateful、一个额外的 persistentTemplate 卷,以及恰好一个用于管理 StatefulSet 的 type: Headless service(缺少它构建会中止);需要该模式的作者可在模式 1 的基础上加入这三项声明。

交叉引用