Aggrega Workload schema
自动生成的参考文档。请勿手动编辑——请从发布的 JSON Schema 重新生成。
Schema id:https://aggrega.ai/schemas/workload-v1beta1.schema.json
由平台拥有的抽象 workload 规范。使用 synthesized 模式的 Recipe 通过 workload: 关键字声明恰好一个 Workload(内联块标量,或按照统一的文件导入词汇表写作 workload: { $import:
有关编写 Workload 实体的文字说明,请参阅 Workload 编写参考;本页记录该参考所描述的结构化 schema。
顶层类型: object
属性
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
apiVersion | const “aggrega.ai/v1beta1” | 是 | 常量:"aggrega.ai/v1beta1" |
kind | const “Workload” | 是 | 常量:"Workload" |
form | string(枚举) | 否 | 工作负载的抽象控制器形态意图。它选择工作负载所具有的运行时生命周期类型,与任何目标平台无关:stateless(可互换的长期运行副本)、stateful(具有稳定的逐副本身份和逐副本存储的副本)、daemon(每个符合条件的主机一个实例)、scheduled(周期性的、按时间触发的运行)、task(单次运行直至完成)、reference(没有计算资源的外部端点——没有控制器;helm 生成一个 ExternalName Service,compose 通过注入契约传递该端点)。为空时视为 stateless。每个目标 provider 将该形态映射为自身的原生形态;形态本身不携带任何平台原生的资源类型。persistentTemplate 卷是 stateful 的配套项,仅在 stateful 工作负载上有效。reference 工作负载声明 endpoint(以及可选的 port),不声明 containers,也不携带自身的凭据字段,因为环境变量名属于消费方而非端点。需要该端点凭据的消费方在其自身 Component 的 featuresSchema 上声明该槽位,并从其容器的 attachments 块中填充它,前提是该槽位的 inject 列表允许这种交付方式。允许的值:"stateless"、"stateful"、"daemon"、"scheduled"、"task"、"reference" 默认值:"stateless" |
endpoint | string | 否 | form: reference 的外部端点——一个主机或 URL。编译器将其作为确定性的指针字符串原样传递;它在编译时(AOT)从不被解析。当 form 为 reference 时必填,且仅在此时有意义。helm 将其生成为 ExternalName Service 的 externalName(主机部分);compose 通过 recipe 的 provides 将其传递给消费方。 |
port | integer | 否 | reference 端点(form: reference)的可选端口。helm 将其生成为 ExternalName Service 上的一个端口。最小值:1。最大值:65535。 |
schedule | string | 否 | form: scheduled 的 Cron 调度——标准的 5 字段 crontab 表达式(例如 ‘0 0 * * *’),或宏 @hourly、@daily、@weekly、@monthly、@yearly 之一。当 form 为 scheduled 时必填,且仅在此时有意义;目标 provider 将其原样传入调度资源的 schedule 字段。 |
suspend | 布尔值 | 否 | 暂停 form: scheduled workload 的周期性调度。为 true 时,调度资源在渲染时保留其调度,但在恢复之前不会按该调度启动任何运行;仍可从该资源手动创建一次运行——在 Kubernetes 上为 kubectl create job false |
replicas | integer | 否 | 副本数量。默认为 1。在 compose 目标上,该值不会进入输出的任何部分,只要编写了该值就会报告警告——包括显式的 1。最小值:0。默认值:1 |
initContainers | container[] | 否 | 在主容器启动之前运行至完成的有序容器列表。 |
containers | container 映射 | 否 | 容器名 → 容器规格的有序映射。至少需要一个条目。保留作者编写的顺序。至少 1 个条目。 |
volumes | volume 映射 | 否 | 卷名 → 卷规格的有序映射。每个卷规格恰好声明以下之一:ephemeral、configmap、secret、persistent、persistentTemplate。 |
services | service 映射 | 否 | 服务名 → 服务规格的有序映射。在 helm 上,每个条目成为一个单独的 K8s Service,type 为 Loopback 的条目会中止构建。在 compose 上没有单独的服务原语,因此条目并非一一映射:type 为 NodePort 或 LoadBalancer 的条目在该工作负载自身 compose 服务的每个主机接口上发布其端口,type 为 Loopback 的条目仅在主机的回环地址上发布其端口,type 为 ClusterIP 或 Headless 的条目不发布任何内容,并且每个发布的端口都汇集到该服务的端口列表中,主机端口与容器端口相同。在 helm 上,每个 Service 命名为 <name>-<key>:即该工作负载自身的 Deployment(或其他控制器)所带的名称,后跟一个连字符和条目的键,因此声明了 services.http 且其 Deployment 名为 api-server 的 Workload 会渲染出名为 api-server-http 的 Service。在 compose 上,键在输出中不命名任何内容。 |
scheduling | object | 否 | K8s 原生的调度约束。对 helm 直接转换。在 compose 目标上,这些约束不会进入输出的任何部分,编写了该块时会报告警告。 |
podSecurityContext | object | 否 | |
serviceAccount | string | 否 | 该工作负载运行所用的 ServiceAccount 名称。实际的 RBAC(ServiceAccount/Role/RoleBinding 资源)应通过 Features 或 artifacts 生成,而不是通过该字段。 |
imagePullSecrets | string[] | 否 | 用于从私有镜像仓库拉取镜像的 image-pull Secret 名称。helm 生成 pod.imagePullSecrets。compose 在文件内没有对应项——镜像仓库认证通过 docker login 在带外配置——因此忽略它。 |
priorityClassName | string | 否 | 决定该工作负载调度优先级的 PriorityClass 名称。helm 生成 pod.priorityClassName。compose 没有单主机调度优先级的对应项,因此忽略它。 |
runtimeClassName | string | 否 | 选择该工作负载运行所用容器运行时的 RuntimeClass 名称(例如支持 GPU 的运行时,如 ‘nvidia’)。编译器原样传递该名称;集群在调度时将其解析为已配置的 RuntimeClass。helm 生成 pod.runtimeClassName。compose 没有 runtime-class 对应项,因此忽略它。仅适用于计算型:不允许用于 reference 工作负载。 |
terminationGracePeriodSeconds | integer | 否 | 关闭时 SIGTERM 与 SIGKILL 之间的秒数。helm 生成 pod.terminationGracePeriodSeconds;compose 生成 stop_grace_period。最小值:0。 |
dnsPolicy | string(枚举) | 否 | Pod DNS 策略。helm 生成 pod.dnsPolicy。compose 没有 DNS 策略对应项,因此忽略它(compose 改为直接映射 dnsConfig 的 nameservers/searches)。允许的值:"Default"、"ClusterFirst"、"ClusterFirstWithHostNet"、"None" |
dnsConfig | object | 否 | 自定义 pod DNS 配置。helm 生成 pod.dnsConfig。compose 将 nameservers 映射为 dns,将 searches 映射为 dns_search;options 在 compose 中没有对应项,因此在那里被忽略。 |
hostAliases | object[] | 否 | 注入到 pod hosts 文件中的静态主机名到 IP 映射。helm 生成 pod.hostAliases;compose 生成 extra_hosts(每个主机名一个 hostname:ip 条目)。 |
hostNetwork | 布尔值 | 否 | 在主机节点自身的网络命名空间中运行工作负载,而不是在隔离的命名空间中。此时工作负载打开的端口可通过节点自身的地址访问,工作负载也能看到节点的网络接口。这只选择网络命名空间,别无其他:它不声明任何端口,工作负载打开的每个端口仍在 containers. |
不允许其他属性。
workload.scheduling
K8s 原生的调度约束。对 helm 直接转换。在 compose 目标上,这些约束不会进入输出的任何部分,编写了该块时会报告警告。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
nodeSelector | map of string | 否 | |
affinity | object | 否 | |
tolerations | object[] | 否 | |
topologySpreadConstraints | object[] | 否 |
不允许其他属性。
workload.podSecurityContext
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
runAsUser | integer | 否 | |
runAsGroup | integer | 否 | |
fsGroup | integer | 否 | |
supplementalGroups | integer[] | 否 |
不允许其他属性。
workload.dnsConfig
自定义 pod DNS 配置。helm 生成 pod.dnsConfig。compose 将 nameservers 映射为 dns,将 searches 映射为 dns_search;options 在 compose 中没有对应项,因此在那里被忽略。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
nameservers | string[] | 否 | |
searches | string[] | 否 | |
options | object[] | 否 |
不允许其他属性。
workload.hostAliases[]
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
ip | string | 是 | |
hostnames | string[] | 是 |
不允许其他属性。
定义
container
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
name | string | 否 | 可选的容器名称。对于按位置排列的 initContainers 条目,它设置输出的容器名称;省略时回退为生成的 init- |
image | string | 是 | 容器镜像引用(例如 ‘nginx:1.27-alpine’、‘ghcr.io/example/app:v1.2.3’)。 |
imagePullPolicy | string(枚举) | 否 | 镜像拉取策略。helm 将其输出为 container.imagePullPolicy。compose 将其映射为服务的 pull_policy(Always 对应 always,Never 对应 never,IfNotPresent 对应 if_not_present)。允许的值:"Always"、"Never"、"IfNotPresent" |
command | string[] | 否 | 覆盖镜像的 entrypoint。K8s:.command。Compose:entrypoint。 |
args | string[] | 否 | 传递给 command 的参数(若无 command,则传递给镜像 entrypoint)。K8s:.args。Compose:command。 |
variables | map of string | 否 | 以字符串键值对表示的环境变量。K8s:spec.template.spec.containers[].env[]。Compose:services. |
attachments | containerAttachment 映射 | 否 | 环境变量名或文件名 → { from, as, key?, path?, connection? } 的有序映射。每个条目引用 Component 的 featuresSchema 中声明的槽位——或者,当条目指定了 connection 时,引用该连接的 socket 所声明的槽位——并交付填充该槽位的 attachment 所发布的内容。‘as’ 字段选择交付机制,该机制必须列在槽位的 inject: 数组允许列表中。黑盒槽位(inject: [])不得出现在此处。 |
envFrom | object[] | 否 | 从 ConfigMap 或 Secret 来源批量导入的环境变量。helm 输出 container.envFrom(configMapRef/secretRef)。compose 没有从对象导入环境变量的原语——来源引用不是主机文件,因此改用 env_file 解释会悄然改变含义;声明了 envFrom 的 workload 在 compose 目标上会明确报错并中止。 |
ports | integer 或 object 映射 | 否 | 命名的容器端口。端口可写为纯端口号(web: 8080),也可写为同时携带端口号及该端口所承载传输协议的对象(dns: { port: 53, protocol: UDP });未声明协议时,两种写法含义相同。允许的协议值为 TCP、UDP 和 SCTP,省略该键则沿用目标自身的默认值。端口名称被 services.*.ports 以及 http 探针的端口解析所引用,服务端口从其名称解析到的容器端口获取传输协议,因此传输协议只需声明一次。K8s:containerPort,仅在声明了协议时携带 protocol。Compose:容器端口仅在服务规范发布它时才进入输出;容器端口本身没有单独的 compose 字段,已发布端口会以发布条目上的 /protocol 后缀携带所声明的传输协议——compose 无法表示的传输协议会中止构建,而不是发布一个承载不同协议的端口。 |
resources | object | 否 | |
health | object | 否 | 容器的健康探针——ready、live 和 startup——每个都声明为 http、tcp 或 exec。对于 helm,转换为 K8s 的 httpGet/tcpSocket/exec。对于 compose,一个服务只携带一个 healthcheck:http 和 tcp 转换为 CMD-SHELL 测试,exec 转换为 CMD 测试;声明了多个探针时只保留一个——警告会指出被转换的探针以及被丢弃的探针。 |
volumeMounts | object[] | 否 | |
restartPolicy | string(枚举) | 否 | 允许的值:"Always"、"OnFailure"、"Never" |
lifecycle | object | 否 | 容器生命周期钩子。对于 helm,转换为 K8s 的 container.lifecycle(postStart/preStop)。compose 没有生命周期钩子原语;声明了 lifecycle 的 workload 在 compose 目标上会明确报错并中止,而不是悄然丢弃该钩子。 |
securityContext | object | 否 |
不允许其他属性。
container.envFrom[]
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
configMap | string | 否 | 由此 Recipe 的 artifacts 输入或某个已附加的 Feature 输出的 ConfigMap 来源的名称。 |
secret | string | 否 | featuresSchema 槽位的名称——Component 自身的槽位,或者在设置了 connection 时,该连接的 socket 所声明的槽位;导入的 Secret 名称从该槽位的 provides 解析得到。 |
connection | string | 否 | 该 component 所使用连接的别名——即它在 Aggregate 或 Release 上该 component 的 uses 块中所写的名称。设置后,secret 指定该连接所经由的 socket 声明的槽位,导入的 Secret 即该连接在该槽位中携带的 attachment 所发布的 Secret,因此连接多个目标的 component 会分别导入每个目标自己的 Secret。仅与 secret 同时使用时才有意义。若 component 并未使用该连接,或其 socket 未声明该槽位,则会被拒绝,并同时指出两者。 |
prefix | string | 否 | 可选前缀,添加到每个导入的环境变量名称之前。 |
不允许其他属性。
container.resources
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
requests | resourceList | 否 | |
limits | resourceList | 否 |
不允许其他属性。
container.health
容器的健康探针——ready、live 和 startup——每个都声明为 http、tcp 或 exec。对于 helm,转换为 K8s 的 httpGet/tcpSocket/exec。对于 compose,一个服务只携带一个 healthcheck:http 和 tcp 转换为 CMD-SHELL 测试,exec 转换为 CMD 测试;声明了多个探针时只保留一个——警告会指出被转换的探针以及被丢弃的探针。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
ready | probe | 否 | |
live | probe | 否 | |
startup | probe | 否 |
不允许其他属性。
container.volumeMounts[]
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
name | string | 是 | 必须与顶层 volumes: 映射中的某个键匹配。 |
path | string | 是 | 容器内的挂载点。 |
subPath | string | 否 | 将卷中的单个文件或子目录挂载到 path,而不遮蔽目标目录中的其他文件。 |
readonly | 布尔值 | 否 | 默认值:false |
不允许其他属性。
container.lifecycle
容器生命周期钩子。对于 helm,转换为 K8s 的 container.lifecycle(postStart/preStop)。compose 没有生命周期钩子原语;声明了 lifecycle 的 workload 在 compose 目标上会明确报错并中止,而不是悄然丢弃该钩子。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
postStart | lifecycleHook | 否 | |
preStop | lifecycleHook | 否 |
不允许其他属性。
container.securityContext
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
runAsUser | integer | 否 | |
runAsGroup | integer | 否 | |
runAsNonRoot | 布尔值 | 否 | |
readOnlyRootFilesystem | 布尔值 | 否 | |
allowPrivilegeEscalation | 布尔值 | 否 | |
capabilities | object | 否 |
不允许其他属性。
container.securityContext.capabilities
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
add | string[] | 否 | |
drop | string[] | 否 |
不允许其他属性。
containerAttachment
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
from | string | 是 | Component 的 featuresSchema 中声明的槽位名称——或者在设置了 connection 时,该连接所经由的 socket 声明的槽位名称。 |
connection | string | 否 | 该 component 所使用连接的别名——即它在 Aggregate 或 Release 上该 component 的 uses 块中所写的名称。设置后,from 指定该连接所经由的 socket 声明的槽位(usesSchema. |
as | string(枚举) | 是 | 交付机制。必须列在槽位的 inject: 数组允许列表中。允许的值:"env"、"file" |
key | string | 否 | 用于 as: env,指定此条目读取的所引用槽位 secret 中的具体数据键。当槽位的 secret 携带多个数据键时设置此项,以便此条目按名称选择其中之一;两个条目可以用不同的键引用同一槽位,从而从一个 secret 中读取多个键。省略时,条目读取该槽位唯一发布的键。对于 as: file 会被忽略,因为它挂载整个 secret。 |
path | string | 否 | 容器内的文件路径(as: file 时必填)。 |
不允许其他属性。
resourceList
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
cpu | string | 否 | CPU 数量(例如 ‘100m’、‘0.5’、‘2’)。helm 将其原样输出到 resources.{requests,limits}.cpu 下。compose 将其映射为 deploy.resources.{reservations,limits}.cpus,以小数核数表示——毫核数量会被转换(500m 变为 0.5);普通核数直接透传。compose 无法转换的数量会显式中止,而不是输出错误的值。 |
memory | string | 否 | 内存数量(例如 ‘128Mi’、‘1Gi’)。helm 将其原样输出到 resources.{requests,limits}.memory 下。compose 将其映射为 deploy.resources.{reservations,limits}.memory,以精确字节数表示。结果为整数字节的数量会被精确转换(1.5Gi 变为 1610612736);结果不是整数字节或本身不是数量的值会显式中止,而不是取整。 |
其他键: 扩展(厂商/域限定)资源数量,以完全限定的 ’^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)+/[A-Za-z0-9]([-A-Za-z0-9_.]*[A-Za-z0-9])?$。
不允许任何其他属性。
probe
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
http | string | 否 | HTTP GET 探针:路径针对名称按字母顺序排在最前的容器端口进行探测。 |
tcp | integer | 否 | 针对给定容器端口号的 TCP 套接字探针。最小值:1。最大值:65535。 |
exec | string[] | 否 | Exec 探针——在容器内运行的命令。至少 1 个条目。 |
timeoutSeconds | integer | 否 | 最小值:1。 |
initialDelaySeconds | integer | 否 | 最小值:0。 |
periodSeconds | integer | 否 | 最小值:1。 |
failureThreshold | integer | 否 | 最小值:1。 |
successThreshold | integer | 否 | 最小值:1。 |
不允许其他属性。
lifecycleHook
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
exec | string[] | 否 | 至少 1 个条目。 |
httpGet | object | 否 | K8s 原生的 httpGet 结构(path、port、scheme、host、httpHeaders)。透传给 helm。在 compose 目标上,声明了生命周期钩子的 workload 会中止,因为 compose 没有生命周期钩子原语——钩子绝不会被静默丢弃。 |
不允许其他属性。
volume
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
ephemeral | object | 否 | |
configmap | object | 否 | |
secret | object | 否 | |
persistent | object | 否 | |
persistentTemplate | object | 否 | 每副本声明模板。要求 form: stateful,因为只有 stateful 形态才能为每个副本提供每副本声明所需的稳定身份。在 Kubernetes 上它会变为 StatefulSet.volumeClaimTemplates。在 compose 目标上,它降级为由所有副本共享的单个命名卷,并会有一条警告报告该降级。 |
不允许其他属性。
volume.ephemeral
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
sizeLimit | string | 否 | K8s 数量(例如 ‘1Gi’)。K8s:emptyDir.sizeLimit。Compose:该卷变为不带大小的 tmpfs 条目,因此该值不会进入输出的任何部分——编写了该值时会有一条警告报告。 |
不允许其他属性。
volume.configmap
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
source | string | 是 | ConfigMap 的名称,由此 Recipe 通过 artifacts: 输出,或由附加的 Feature 输出;此处不引用其他 Recipe 输出的 ConfigMap。 |
items | object[] | 否 | 可选的键到路径选择。 |
不允许其他属性。
volume.secret
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
source | string | 是 | |
items | object[] | 否 |
不允许其他属性。
volume.persistent
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
size | string | 是 | K8s 数量(例如 ‘10Gi’)。 |
class | string | 否 | StorageClassName。可选。 |
accessModes | string (enum)[] | 否 | PVC 访问模式。helm 输出 spec.accessModes,省略时默认为 [ReadWriteOnce]。compose 卷没有访问模式的概念,会将其省略。每个条目的允许值:"ReadWriteOnce", "ReadOnlyMany", "ReadWriteMany", "ReadWriteOncePod"。 |
不允许其他属性。
volume.persistentTemplate
每副本声明模板。要求 form: stateful,因为只有 stateful 形态才能为每个副本提供每副本声明所需的稳定身份。在 Kubernetes 上它会变为 StatefulSet.volumeClaimTemplates。在 compose 目标上,它降级为由所有副本共享的单个命名卷,并会有一条警告报告该降级。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
size | string | 是 | |
class | string | 否 | |
accessModes | string (enum)[] | 否 | 每副本声明模板的 PVC 访问模式。helm 输出 spec.accessModes,省略时默认为 [ReadWriteOnce]。compose 没有访问模式的概念,会将其省略。每个条目的允许值:"ReadWriteOnce", "ReadOnlyMany", "ReadWriteMany", "ReadWriteOncePod"。 |
不允许其他属性。
service
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
type | string(枚举) | 是 | Service 类型:该条目的端口可达的范围。ClusterIP 将端口保留在目标自身的网络上,可由 workload 的对等方访问;Headless 同样如此,并且在 helm 上渲染为带 clusterIP: None 的 K8s Service;NodePort 和 LoadBalancer 将端口发布到该网络之外;Loopback 仅将端口发布在主机自身的回环地址上,只能从 workload 所运行的机器访问,其他任何地方都无法访问。helm 将 ClusterIP、NodePort 和 LoadBalancer 渲染为同名的 K8s Service 类型,并按名称拒绝 Loopback 条目,因为 K8s Service 没有绑定到主机回环地址的类型。compose 对 ClusterIP 和 Headless 不发布任何端口,将 NodePort 和 LoadBalancer 端口以 host:container 形式发布在所有主机接口上,并将 Loopback 端口以 127.0.0.1:host:container 形式发布在 IPv4 回环地址上;同时也被 NodePort 或 LoadBalancer 条目发布的端口会发布在所有接口上。允许的值:"ClusterIP"、"NodePort"、"LoadBalancer"、"Headless"、"Loopback" |
ports | integer 映射 | 是 | service 端口名 → 容器端口号的映射。端口名必须与 containers. |
不允许其他属性。