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

Aggrega Workload schema

自动生成的参考文档。请勿手动编辑——请从发布的 JSON Schema 重新生成。

Schema id:https://aggrega.ai/schemas/workload-v1beta1.schema.json

由平台拥有的抽象 workload 规范。使用 synthesized 模式的 Recipe 通过 workload: 关键字声明恰好一个 Workload(内联块标量,或按照统一的文件导入词汇表写作 workload: { $import: })。目标 provider 将该 Workload 转换为 provider 原生的 manifest(对 helm 为 K8s Deployment/StatefulSet/Services/PVCs;对 compose 为 compose services + volumes + networks;等等)。Workload 自身不携带任何元数据——没有名称、没有标签、没有注解。标识和标签来自声明它的 component 实例:目标 provider 根据该实例派生每个渲染资源的名称,并为资源打上该节点的 aggrega.ai/* 溯源键。Workload 这一 kind 不是目录实体——此发布文件是规范的 Workload JSON Schema,编译器依据它校验 Workload。

有关编写 Workload 实体的文字说明,请参阅 Workload 编写参考;本页记录该参考所描述的结构化 schema。

顶层类型: object

属性

属性类型必需描述
apiVersionconst “aggrega.ai/v1beta1”是常量:"aggrega.ai/v1beta1"
kindconst “Workload”是常量:"Workload"
formstring(枚举)否工作负载的抽象控制器形态意图。它选择工作负载所具有的运行时生命周期类型,与任何目标平台无关: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"
endpointstring否form: reference 的外部端点——一个主机或 URL。编译器将其作为确定性的指针字符串原样传递;它在编译时(AOT)从不被解析。当 form 为 reference 时必填,且仅在此时有意义。helm 将其生成为 ExternalName Service 的 externalName(主机部分);compose 通过 recipe 的 provides 将其传递给消费方。
portinteger否reference 端点(form: reference)的可选端口。helm 将其生成为 ExternalName Service 上的一个端口。最小值:1。最大值:65535。
schedulestring否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 —from=cronjob/。suspend: false 的渲染结果与未写 suspend 时完全相同。仅在 form: scheduled 时有意义。helm 将其输出为 CronJob 的 spec.suspend。compose 没有调度形态,无论是否暂停,遇到 form: scheduled 的 workload 都会中止。默认值:false
replicasinteger否副本数量。默认为 1。在 compose 目标上,该值不会进入输出的任何部分,只要编写了该值就会报告警告——包括显式的 1。最小值:0。默认值:1
initContainerscontainer[]否在主容器启动之前运行至完成的有序容器列表。
containerscontainer 映射否容器名 → 容器规格的有序映射。至少需要一个条目。保留作者编写的顺序。至少 1 个条目。
volumesvolume 映射否卷名 → 卷规格的有序映射。每个卷规格恰好声明以下之一:ephemeral、configmap、secret、persistent、persistentTemplate。
servicesservice 映射否服务名 → 服务规格的有序映射。在 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 上,键在输出中不命名任何内容。
schedulingobject否K8s 原生的调度约束。对 helm 直接转换。在 compose 目标上,这些约束不会进入输出的任何部分,编写了该块时会报告警告。
podSecurityContextobject否
serviceAccountstring否该工作负载运行所用的 ServiceAccount 名称。实际的 RBAC(ServiceAccount/Role/RoleBinding 资源)应通过 Features 或 artifacts 生成,而不是通过该字段。
imagePullSecretsstring[]否用于从私有镜像仓库拉取镜像的 image-pull Secret 名称。helm 生成 pod.imagePullSecrets。compose 在文件内没有对应项——镜像仓库认证通过 docker login 在带外配置——因此忽略它。
priorityClassNamestring否决定该工作负载调度优先级的 PriorityClass 名称。helm 生成 pod.priorityClassName。compose 没有单主机调度优先级的对应项,因此忽略它。
runtimeClassNamestring否选择该工作负载运行所用容器运行时的 RuntimeClass 名称(例如支持 GPU 的运行时,如 ‘nvidia’)。编译器原样传递该名称;集群在调度时将其解析为已配置的 RuntimeClass。helm 生成 pod.runtimeClassName。compose 没有 runtime-class 对应项,因此忽略它。仅适用于计算型:不允许用于 reference 工作负载。
terminationGracePeriodSecondsinteger否关闭时 SIGTERM 与 SIGKILL 之间的秒数。helm 生成 pod.terminationGracePeriodSeconds;compose 生成 stop_grace_period。最小值:0。
dnsPolicystring(枚举)否Pod DNS 策略。helm 生成 pod.dnsPolicy。compose 没有 DNS 策略对应项,因此忽略它(compose 改为直接映射 dnsConfig 的 nameservers/searches)。允许的值:"Default"、"ClusterFirst"、"ClusterFirstWithHostNet"、"None"
dnsConfigobject否自定义 pod DNS 配置。helm 生成 pod.dnsConfig。compose 将 nameservers 映射为 dns,将 searches 映射为 dns_search;options 在 compose 中没有对应项,因此在那里被忽略。
hostAliasesobject[]否注入到 pod hosts 文件中的静态主机名到 IP 映射。helm 生成 pod.hostAliases;compose 生成 extra_hosts(每个主机名一个 hostname:ip 条目)。
hostNetwork布尔值否在主机节点自身的网络命名空间中运行工作负载,而不是在隔离的命名空间中。此时工作负载打开的端口可通过节点自身的地址访问,工作负载也能看到节点的网络接口。这只选择网络命名空间,别无其他:它不声明任何端口,工作负载打开的每个端口仍在 containers..ports 下声明。helm 生成 pod.hostNetwork。compose 在工作负载自身的服务上生成 network_mode: host;处于该模式的 compose 服务不连接到边界网络,因此其对等方通过节点的地址而非服务名访问它,而每个 init 容器的服务各自加入边界网络。仅适用于计算型:不允许用于 reference 工作负载。

不允许其他属性。

workload.scheduling

K8s 原生的调度约束。对 helm 直接转换。在 compose 目标上,这些约束不会进入输出的任何部分,编写了该块时会报告警告。

属性类型必需描述
nodeSelectormap of string否
affinityobject否
tolerationsobject[]否
topologySpreadConstraintsobject[]否

不允许其他属性。

workload.podSecurityContext

属性类型必需描述
runAsUserinteger否
runAsGroupinteger否
fsGroupinteger否
supplementalGroupsinteger[]否

不允许其他属性。

workload.dnsConfig

自定义 pod DNS 配置。helm 生成 pod.dnsConfig。compose 将 nameservers 映射为 dns,将 searches 映射为 dns_search;options 在 compose 中没有对应项,因此在那里被忽略。

属性类型必需描述
nameserversstring[]否
searchesstring[]否
optionsobject[]否

不允许其他属性。

workload.hostAliases[]

属性类型必需描述
ipstring是
hostnamesstring[]是

不允许其他属性。

定义

container

属性类型必需描述
namestring否可选的容器名称。对于按位置排列的 initContainers 条目,它设置输出的容器名称;省略时回退为生成的 init- 名称(即该条目在列表中的位置)。对于 containers 映射条目,映射键即容器名称,此字段被忽略。
imagestring是容器镜像引用(例如 ‘nginx:1.27-alpine’、‘ghcr.io/example/app:v1.2.3’)。
imagePullPolicystring(枚举)否镜像拉取策略。helm 将其输出为 container.imagePullPolicy。compose 将其映射为服务的 pull_policy(Always 对应 always,Never 对应 never,IfNotPresent 对应 if_not_present)。允许的值:"Always"、"Never"、"IfNotPresent"
commandstring[]否覆盖镜像的 entrypoint。K8s:.command。Compose:entrypoint。
argsstring[]否传递给 command 的参数(若无 command,则传递给镜像 entrypoint)。K8s:.args。Compose:command。
variablesmap of string否以字符串键值对表示的环境变量。K8s:spec.template.spec.containers[].env[]。Compose:services..environment。
attachmentscontainerAttachment 映射否环境变量名或文件名 → { from, as, key?, path?, connection? } 的有序映射。每个条目引用 Component 的 featuresSchema 中声明的槽位——或者,当条目指定了 connection 时,引用该连接的 socket 所声明的槽位——并交付填充该槽位的 attachment 所发布的内容。‘as’ 字段选择交付机制,该机制必须列在槽位的 inject: 数组允许列表中。黑盒槽位(inject: [])不得出现在此处。
envFromobject[]否从 ConfigMap 或 Secret 来源批量导入的环境变量。helm 输出 container.envFrom(configMapRef/secretRef)。compose 没有从对象导入环境变量的原语——来源引用不是主机文件,因此改用 env_file 解释会悄然改变含义;声明了 envFrom 的 workload 在 compose 目标上会明确报错并中止。
portsinteger 或 object 映射否命名的容器端口。端口可写为纯端口号(web: 8080),也可写为同时携带端口号及该端口所承载传输协议的对象(dns: { port: 53, protocol: UDP });未声明协议时,两种写法含义相同。允许的协议值为 TCP、UDP 和 SCTP,省略该键则沿用目标自身的默认值。端口名称被 services.*.ports 以及 http 探针的端口解析所引用,服务端口从其名称解析到的容器端口获取传输协议,因此传输协议只需声明一次。K8s:containerPort,仅在声明了协议时携带 protocol。Compose:容器端口仅在服务规范发布它时才进入输出;容器端口本身没有单独的 compose 字段,已发布端口会以发布条目上的 /protocol 后缀携带所声明的传输协议——compose 无法表示的传输协议会中止构建,而不是发布一个承载不同协议的端口。
resourcesobject否
healthobject否容器的健康探针——ready、live 和 startup——每个都声明为 http、tcp 或 exec。对于 helm,转换为 K8s 的 httpGet/tcpSocket/exec。对于 compose,一个服务只携带一个 healthcheck:http 和 tcp 转换为 CMD-SHELL 测试,exec 转换为 CMD 测试;声明了多个探针时只保留一个——警告会指出被转换的探针以及被丢弃的探针。
volumeMountsobject[]否
restartPolicystring(枚举)否允许的值:"Always"、"OnFailure"、"Never"
lifecycleobject否容器生命周期钩子。对于 helm,转换为 K8s 的 container.lifecycle(postStart/preStop)。compose 没有生命周期钩子原语;声明了 lifecycle 的 workload 在 compose 目标上会明确报错并中止,而不是悄然丢弃该钩子。
securityContextobject否

不允许其他属性。

container.envFrom[]

属性类型必需描述
configMapstring否由此 Recipe 的 artifacts 输入或某个已附加的 Feature 输出的 ConfigMap 来源的名称。
secretstring否featuresSchema 槽位的名称——Component 自身的槽位,或者在设置了 connection 时,该连接的 socket 所声明的槽位;导入的 Secret 名称从该槽位的 provides 解析得到。
connectionstring否该 component 所使用连接的别名——即它在 Aggregate 或 Release 上该 component 的 uses 块中所写的名称。设置后,secret 指定该连接所经由的 socket 声明的槽位,导入的 Secret 即该连接在该槽位中携带的 attachment 所发布的 Secret,因此连接多个目标的 component 会分别导入每个目标自己的 Secret。仅与 secret 同时使用时才有意义。若 component 并未使用该连接,或其 socket 未声明该槽位,则会被拒绝,并同时指出两者。
prefixstring否可选前缀,添加到每个导入的环境变量名称之前。

不允许其他属性。

container.resources

属性类型必需描述
requestsresourceList否
limitsresourceList否

不允许其他属性。

container.health

容器的健康探针——ready、live 和 startup——每个都声明为 http、tcp 或 exec。对于 helm,转换为 K8s 的 httpGet/tcpSocket/exec。对于 compose,一个服务只携带一个 healthcheck:http 和 tcp 转换为 CMD-SHELL 测试,exec 转换为 CMD 测试;声明了多个探针时只保留一个——警告会指出被转换的探针以及被丢弃的探针。

属性类型必需描述
readyprobe否
liveprobe否
startupprobe否

不允许其他属性。

container.volumeMounts[]

属性类型必需描述
namestring是必须与顶层 volumes: 映射中的某个键匹配。
pathstring是容器内的挂载点。
subPathstring否将卷中的单个文件或子目录挂载到 path,而不遮蔽目标目录中的其他文件。
readonly布尔值否默认值:false

不允许其他属性。

container.lifecycle

容器生命周期钩子。对于 helm,转换为 K8s 的 container.lifecycle(postStart/preStop)。compose 没有生命周期钩子原语;声明了 lifecycle 的 workload 在 compose 目标上会明确报错并中止,而不是悄然丢弃该钩子。

属性类型必需描述
postStartlifecycleHook否
preStoplifecycleHook否

不允许其他属性。

container.securityContext

属性类型必需描述
runAsUserinteger否
runAsGroupinteger否
runAsNonRoot布尔值否
readOnlyRootFilesystem布尔值否
allowPrivilegeEscalation布尔值否
capabilitiesobject否

不允许其他属性。

container.securityContext.capabilities
属性类型必需描述
addstring[]否
dropstring[]否

不允许其他属性。

containerAttachment

属性类型必需描述
fromstring是Component 的 featuresSchema 中声明的槽位名称——或者在设置了 connection 时,该连接所经由的 socket 声明的槽位名称。
connectionstring否该 component 所使用连接的别名——即它在 Aggregate 或 Release 上该 component 的 uses 块中所写的名称。设置后,from 指定该连接所经由的 socket 声明的槽位(usesSchema..featuresSchema),该条目交付该连接在该槽位中携带的 attachment 所发布的内容,因此连接多个目标的 component 会向每个目标出示各自的凭据。槽位的 inject: 允许列表约束 as,与 Component 所声明槽位的情况完全相同。若 component 并未使用该连接,或其 socket 未声明该槽位,则会被拒绝,并同时指出两者。
asstring(枚举)是交付机制。必须列在槽位的 inject: 数组允许列表中。允许的值:"env"、"file"
keystring否用于 as: env,指定此条目读取的所引用槽位 secret 中的具体数据键。当槽位的 secret 携带多个数据键时设置此项,以便此条目按名称选择其中之一;两个条目可以用不同的键引用同一槽位,从而从一个 secret 中读取多个键。省略时,条目读取该槽位唯一发布的键。对于 as: file 会被忽略,因为它挂载整个 secret。
pathstring否容器内的文件路径(as: file 时必填)。

不允许其他属性。

resourceList

属性类型必需描述
cpustring否CPU 数量(例如 ‘100m’、‘0.5’、‘2’)。helm 将其原样输出到 resources.{requests,limits}.cpu 下。compose 将其映射为 deploy.resources.{reservations,limits}.cpus,以小数核数表示——毫核数量会被转换(500m 变为 0.5);普通核数直接透传。compose 无法转换的数量会显式中止,而不是输出错误的值。
memorystring否内存数量(例如 ‘128Mi’、‘1Gi’)。helm 将其原样输出到 resources.{requests,limits}.memory 下。compose 将其映射为 deploy.resources.{reservations,limits}.memory,以精确字节数表示。结果为整数字节的数量会被精确转换(1.5Gi 变为 1610612736);结果不是整数字节或本身不是数量的值会显式中止,而不是取整。

其他键: 扩展(厂商/域限定)资源数量,以完全限定的 ’/’ 名称作为键(例如 ‘nvidia.com/gpu’: ‘1’、‘amd.com/gpu’: ‘2’)。域部分至少包含一个点,以此区分扩展键与裸 cpu/memory 数量。编译器将该数量原样透传;由集群的设备插件在调度时解析并分配。helm 将其输出到 resources.{requests,limits}. 下。compose 将 ‘nvidia.com/gpu’ 计数作为 NVIDIA 设备预留添加到容器的 service 上——写了 limit 时取 limit 的计数,否则取 request 的计数,计数为 0 时不做预留——并在计数不是整数个设备,或 request 与 limit 要求的计数不同时中止。对于其他任何扩展键,compose 没有对应项并会将其省略,每个不同的扩展键警告一次并指明该键,因此丢弃会被报告而不是静默发生。模式:^[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

属性类型必需描述
httpstring否HTTP GET 探针:路径针对名称按字母顺序排在最前的容器端口进行探测。
tcpinteger否针对给定容器端口号的 TCP 套接字探针。最小值:1。最大值:65535。
execstring[]否Exec 探针——在容器内运行的命令。至少 1 个条目。
timeoutSecondsinteger否最小值:1。
initialDelaySecondsinteger否最小值:0。
periodSecondsinteger否最小值:1。
failureThresholdinteger否最小值:1。
successThresholdinteger否最小值:1。

不允许其他属性。

lifecycleHook

属性类型必需描述
execstring[]否至少 1 个条目。
httpGetobject否K8s 原生的 httpGet 结构(path、port、scheme、host、httpHeaders)。透传给 helm。在 compose 目标上,声明了生命周期钩子的 workload 会中止,因为 compose 没有生命周期钩子原语——钩子绝不会被静默丢弃。

不允许其他属性。

volume

属性类型必需描述
ephemeralobject否
configmapobject否
secretobject否
persistentobject否
persistentTemplateobject否每副本声明模板。要求 form: stateful,因为只有 stateful 形态才能为每个副本提供每副本声明所需的稳定身份。在 Kubernetes 上它会变为 StatefulSet.volumeClaimTemplates。在 compose 目标上,它降级为由所有副本共享的单个命名卷,并会有一条警告报告该降级。

不允许其他属性。

volume.ephemeral

属性类型必需描述
sizeLimitstring否K8s 数量(例如 ‘1Gi’)。K8s:emptyDir.sizeLimit。Compose:该卷变为不带大小的 tmpfs 条目,因此该值不会进入输出的任何部分——编写了该值时会有一条警告报告。

不允许其他属性。

volume.configmap

属性类型必需描述
sourcestring是ConfigMap 的名称,由此 Recipe 通过 artifacts: 输出,或由附加的 Feature 输出;此处不引用其他 Recipe 输出的 ConfigMap。
itemsobject[]否可选的键到路径选择。

不允许其他属性。

volume.secret

属性类型必需描述
sourcestring是
itemsobject[]否

不允许其他属性。

volume.persistent

属性类型必需描述
sizestring是K8s 数量(例如 ‘10Gi’)。
classstring否StorageClassName。可选。
accessModesstring (enum)[]否PVC 访问模式。helm 输出 spec.accessModes,省略时默认为 [ReadWriteOnce]。compose 卷没有访问模式的概念,会将其省略。每个条目的允许值:"ReadWriteOnce", "ReadOnlyMany", "ReadWriteMany", "ReadWriteOncePod"。

不允许其他属性。

volume.persistentTemplate

每副本声明模板。要求 form: stateful,因为只有 stateful 形态才能为每个副本提供每副本声明所需的稳定身份。在 Kubernetes 上它会变为 StatefulSet.volumeClaimTemplates。在 compose 目标上,它降级为由所有副本共享的单个命名卷,并会有一条警告报告该降级。

属性类型必需描述
sizestring是
classstring否
accessModesstring (enum)[]否每副本声明模板的 PVC 访问模式。helm 输出 spec.accessModes,省略时默认为 [ReadWriteOnce]。compose 没有访问模式的概念,会将其省略。每个条目的允许值:"ReadWriteOnce", "ReadOnlyMany", "ReadWriteMany", "ReadWriteOncePod"。

不允许其他属性。

service

属性类型必需描述
typestring(枚举)是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"
portsinteger 映射是service 端口名 → 容器端口号的映射。端口名必须与 containers..ports 中的键匹配。service 端口本身不携带传输协议:它采用其名称所解析到的容器端口的传输协议,因此端口的传输协议只在容器端口上声明一次,service 暴露不会与容器所打开的端口不一致。

不允许其他属性。