Compose Provider
compose provider 将 Aggrega Recipes 渲染为 Docker Compose 文件。该 provider 按 (path, provider) 进行组装:每个边界的 compose 贡献者都会被路由到一个组装器,该组装器以边界求值后的 directory: 与每个组件的 subDirectory: 拼接所得的路径为键,并输出一个 docker-compose.yaml,其中包含该路径下的所有贡献者。两个求值为同一路径的同级边界会合并为一个 compose 文件——典型示例是一个父边界加上两个声明了 directory: "{{ .parent_boundary.directory }}" 的子边界(即 compose-bridge 模式)。
支持的输入类型
compose provider 接受全部三种 Recipe 输入类型:
- Sourced 模式。 一个 Recipe 通过
source:指向现有的 compose 文件,并通过valuesMapping:生成一个覆盖文档。加载基础 compose 文件,求值覆盖文档,然后按照 docker-compose 原生的覆盖语义对两者进行深度合并。 - Workload 模式。 带有
workload:(内联或通过$import:加载)的 Recipe 声明一个Workload文档。provider 根据 Workload 规范合成一个或多个 compose 服务。 - Artifacts 模式。 Recipe 的
artifacts:条目求值为 compose 片段,这些片段按照由 Artifacts 生成的 compose 片段中的规则合并到组装后的文件中。Artifacts 可以与 source 或 Workload 并存,也可以构成 Recipe 的全部输出:声明了artifacts:而既没有source:也没有workload:的 Recipe 也会在此渲染,贡献其片段所声明的任何内容。这样,仅由资源构成的组件(一组共享的网络和卷、一份预置的配置)便能进入 compose 部署,而无需用一个占位 Workload 来代替它并不具备的计算。
这三种类型以叠加方式组合,未声明其中任何一种的 Recipe 在加载时会被拒绝。旁边没有 source: 的 valuesMapping: 同样会在 Recipe 加载时被拒绝,无论它指定哪个 provider:覆盖文档没有可应用的对象,诊断信息会要求你声明 source: 指针或删除 valuesMapping:。
Workload 特性映射
当 Recipe 声明 workload: 时,provider 会将平台所拥有的 Workload 结构翻译为 compose 原语。该映射有意保持狭窄——Compose 的表达面在结构上比 Kubernetes 更贫乏,若干 Workload 特性会退化为最接近的 compose 等价物,并有文档记录其损失。
容器字段
| Workload 字段 | Compose 字段 |
|---|---|
image | image |
imagePullPolicy: Always / IfNotPresent / Never | pull_policy: always / if_not_present / never |
command | entrypoint(列表形式)——它覆盖镜像的入口点,而 compose 中执行此操作的键正是它 |
args | command(列表形式)——它提供入口点接收的参数,这正是 compose 的 command 所覆盖的内容 |
variables | environment(映射形式) |
attachments[as: env] | 值为空的 environment 条目,并发出一条指明该条目的警告(参见 compose provider 不提供的内容) |
attachments[as: file] | volumes 长格式绑定挂载,只读 |
volumeMounts | 所引用的 Volume 变体映射到的 compose 原语——一个 volumes 长格式条目、一个服务级 tmpfs: 条目,或一个服务级 configs: 引用(参见 卷) |
ports | 隐式(compose 容器会暴露镜像所监听的端口) |
restartPolicy: Always | restart: unless-stopped |
restartPolicy: OnFailure | restart: on-failure |
restartPolicy: Never | restart: "no" |
variables 和 attachments[as: env] 都落入同一个 environment 映射中,attachment 条目在前,variables 在后,各自按编写顺序排列——与 helm provider 写入的顺序相同,因此同一个 Workload 在每个目标上都渲染出同一个环境变量序列。Compose 不会在服务的环境变量条目之间展开任何 $(NAME) 引用,因此在 compose 上该顺序没有运行时意义。由于该映射中每个名称只出现一次,如果一个容器将同一个名称既作为 variables 条目、又作为以 as: env 交付的 attachments 条目给出,构建会中止,而不是保留两个值之一(参见 A container gives one environment variable two values(一个容器为同一个环境变量给出了两个值))。
容器资源
容器的 resources 会进入 compose 的 deploy.resources 块,docker compose 在非 swarm 模式下会遵循该块。Kubernetes 的 requests 表示保证的最小值,因此它们成为 compose 的 reservations;limits 表示硬性上限,因此保持为 limits。
| Workload 字段 | Compose 字段 | 转换 |
|---|---|---|
resources.requests.cpu | deploy.resources.reservations.cpus | 十进制核数。以纯数字形式书写的核数(2、0.5)按原样输出;其他任何形式都按其值转换(500m → 0.5、1500m → 1.5、5n → 0.000000005、1e1 → 10) |
resources.limits.cpu | deploy.resources.limits.cpus | 相同的转换 |
resources.requests.memory | deploy.resources.reservations.memory | 精确的字节数,无论值以何种形式书写都按其值转换——8Gi 变为 8589934592,1.5Gi 变为 1610612736,1e3 变为 1000 |
resources.limits.memory | deploy.resources.limits.memory | 相同的转换 |
nvidia.com/gpu,位于 resources.limits、resources.requests 或两者之下 | deploy.resources.reservations.devices | 在该容器的服务上生成一个 NVIDIA 设备条目——driver: nvidia、count: 为 GPU 数量、capabilities: [gpu]。若写了 limit,数量取 limit 的值——即 Kubernetes 为扩展资源调度的数量——否则取 request 的值。数量为 0 表示不请求 GPU,不写入任何条目 |
其他任何扩展资源键——amd.com/gpu 以及其他所有 <domain>/<name> | — | 没有单主机 compose 对应物。该键会被丢弃,构建发出一条指明该键的 unsupported-field 警告,每个不同的键一条,无论 requests 和 limits 中有多少处携带了它。其值不会输出,因此不会被检查 |
每个 cpu、memory 和 nvidia.com/gpu 值都按 Workload → 资源数量 中规定的形式作为数量读取,读取对象是经 Recipe 模板求值后的 Workload。以下两种情况会以 TRANSLATION_ERROR 中止构建,错误会说明遇到的是哪一种,并指明容器的路径、该值是 request 还是 limit、资源以及值:
- 不是数量的值——
lots、1.5 cores,或空模板在"{{ .infra.cpu }}m"中留下的m; - compose 无法精确表示的数量——负数;不是整数字节(
1500m、4u)或大于 9223372036854775807 字节(8Ei)的内存量;精度细于核的九位小数(即 Kubernetes 数量本身保留的最细精度)或大于 9223372036.854775807 核的 cpu 量;不是整数个设备(0.5、500m)的 GPU 数量。
如果一个容器的 nvidia.com/gpu request 与 limit 请求的数量不同,构建同样会中止,并指明两者的路径:compose 为一个服务只预留一个数量,否则转换就不得不从中选择一个。请在两处写相同的数量,或只写 limit。
不会进行任何舍入,也不会输出任何含义不同的值。
GPU request 会预留 NVIDIA GPU。 一个请求 nvidia.com/gpu: "1" 的 Workload 容器会渲染出携带如下预留的服务,与其 requests 所预留的 cpus 和 memory 并列:
deploy: resources: reservations: devices: - driver: nvidia count: 1 capabilities: - gpu当 Docker 主机拥有相应数量的 NVIDIA GPU 并已配置为将其提供给容器时,Docker Compose 会将预留的 GPU 交给容器;构建无法看到主机,因此预留 GPU 的文件无论将在何处运行,组装方式都相同。该条目总是写明数量,因为 Compose 会将没有数量的设备条目理解为主机上的所有 GPU。只有 NVIDIA 键会被转换:amd.com/gpu 和其他所有厂商的键仍然产生被丢弃键那一行所述的警告。Pod 级字段 中的 runtimeClassName 行保持不变——compose 没有运行时类的对应物,因此指定启用 GPU 的运行时的 Workload 会被告知该运行时已被省略,而其 GPU 数量仍会被预留。
探针
Workload 的三个探针槽位(live、ready、startup)会合并为 compose 每个服务唯一的 healthcheck,优先级为 live > ready > startup(最典型的存活信号胜出)。当这种合并丢弃了作者声明的槽位时,构建会发出一条 unsupported-field 警告,指明被转换的槽位和被丢弃的槽位,从而使未进入输出任何部分的意图得到报告而不是悄然丢失。只声明一个槽位的 health 块可无损转换,不会发出任何警告,除非该槽位设置了 successThreshold:compose 的 healthcheck 没有对应字段,因此显式编写的值(包括 1)会被省略,并发出一条指明它的 unsupported-field 警告(containers.<name>.health.<slot>.successThreshold),该槽位的其余部分按下表所示转换。
| Workload 探针结构 | Compose healthcheck.test |
|---|---|
http: /path | ["CMD-SHELL", "curl -f http://localhost:<port>/path || exit 1"] |
tcp: <port> | ["CMD-SHELL", "nc -z localhost <port>"] |
exec: [cmd, ...] | ["CMD", cmd, ...] |
HTTP 形式要求容器至少声明一个具名端口;合成器选取按字母顺序排在最前的端口名,并用其端口号构建 curl URL。未声明端口的容器无法使用 HTTP 探针——编译器会以 TRANSLATION_ERROR 中止,并指明出错的探针。
探针超时字段映射为 compose 风格的时长字符串:
| Workload 字段 | Compose healthcheck 字段 |
|---|---|
periodSeconds | interval: <n>s |
timeoutSeconds | timeout: <n>s |
failureThreshold | retries: <n> |
initialDelaySeconds | start_period: <n>s |
卷
Compose 有自己的 config 原语,configmap 卷即转换为该原语。Compose 没有与 Kubernetes 的 Secret 或按副本卷模板对应的机制,因此这些变体会降级为最接近的 compose 原语:
| Workload 卷变体 | Compose 转换 | 损失说明 |
|---|---|---|
ephemeral | 服务级 tmpfs: 列表条目 | sizeLimit 不会保留(compose tmpfs 短格式不支持大小)。编写的 sizeLimit 会触发一条 unsupported-field 警告,在其编写位置(volumes.<name>.ephemeral.sizeLimit)指明该字段,无论是否有容器挂载该卷;省略该字段则不会触发任何警告 |
configmap | 服务级 configs: 引用,指明该 configmap,挂载在卷挂载的路径上 | 🔴 挂载路径是单个文件的路径,而不是目录的路径。 Compose 将 config 的内容恰好写入目标路径,而 Kubernetes 目标在某个路径挂载 ConfigMap 时,会生成一个目录,每个键对应其中一个文件。因此,同样编写的 path: 在这里表示文件,在那里表示目录:应将 configmap 卷的挂载指向容器要读取的文件名(/seed/config.json),而不是包含该文件的目录;为两种目标编写的 Recipe 需要为每个目标使用不同的路径。构建过程无法发现为另一种目标形态编写的路径——该路径是编译器原样传递的不透明字符串,而且无论哪种情况,生成的输出都是有效的。引用按名称进行,与 Kubernetes 目标引用 ConfigMap 资源的方式完全一致——不会读取 config 的内容。对应的顶层 configs: 条目来自 Recipe 的 artifacts: 输入,其 compose 片段使用内联 content: 声明该条目;没有此类条目的引用会使构建中止(参见 Artifacts 生成的 compose 片段)。configs: 引用只携带 config 名称和挂载路径,因此挂载的 readOnly 没有单独的表达方式 |
secret | volumes 长格式绑定挂载,只读 | secret 卷有意不沿用 configmap 的转换方式:内联 configs: 条目会将 secret 的值以明文写入生成的 compose 文件,而编译器从不将 secret 解析为明文——secret 在构建的每个阶段都保持为指针。绑定源是 secret 的 source 名称,解析为一个路径,由运维人员在构建之外确保该路径在 compose 主机上可访问 |
persistent | 命名卷 + 顶层 volumes: { <volume-name>: {} } 声明,按卷名称的推导方式命名 | 存储类、访问模式和大小不会保留(compose 没有等效的结构)。编写的 class 或 accessModes 会引发一条 unsupported-field 警告,在其编写坐标(volumes.<name>.persistent.class、volumes.<name>.persistent.accessModes)处指出该字段;二者都省略则不会引发任何警告。必填的 size 不会引发警告——见下文 |
persistentTemplate | 命名卷 + 顶层声明,命名方式相同(与 persistent 相同) | form: stateful 的配套项;compose 没有按副本的卷模板原语,因此按副本的行为会丢失,并会有一条 unsupported-field 警告说明该卷已变为所有副本共享的一个卷。存储类、访问模式和大小不会保留,与 persistent 完全相同:编写的 class 或 accessModes 会在 volumes.<name>.persistentTemplate.class 或 volumes.<name>.persistentTemplate.accessModes 处引发一条 unsupported-field 警告,而必填的 size 不会引发任何警告 |
挂载的 subPath 会在 compose 有对应形式时挂载卷的一部分。 一个指向 persistent 或 persistentTemplate 卷并带有 subPath 的 volumeMounts 条目,会变成携带 volume.subpath 的长格式 volumes 条目,因此该挂载看到的是卷内指定的目录或文件,而不是卷的根目录;对同一个卷的两次挂载若使用两个不同的 subPath 值,则会看到卷的两个不同部分:
volumes: - type: volume source: store--data target: /var/lib/app/db volume: subpath: db - type: volume source: store--data target: /var/lib/app/uploads volume: subpath: uploads未带 subPath 编写的挂载不携带 volume: 块。在 ephemeral、configmap 或 secret 卷的挂载上使用 subPath 会以 TRANSLATION_ERROR 停止构建,并指出组件、容器、该挂载的编写路径(containers.<name>.volumeMounts[<i>])、卷以及 subPath:这些变体在 compose 中分别成为 tmpfs 条目、configs: 引用和绑定挂载,它们都不会只挂载所交付内容的一部分,否则该挂载会看到整个卷。请从此类挂载中移除 subPath,或改为挂载 persistent 卷。Docker Compose 从 2.26.0 版本起读取 volume.subpath,要求 Docker Engine 26.0 或更高版本;构建无法看到将运行该文件的主机,因此携带它的文件无论在哪里运行,组装方式都相同。
卷只声明它是哪种变体,仅此而已。 secret 卷只有一种转换——即上面的只读绑定挂载——且卷没有用于选择其他方式的 as: 字段。将某个槽位发布的内容作为环境变量交付,是通过容器的 attachments 条目(as: env)而非卷来实现的;compose 如何处理此类条目,参见 compose provider 不提供的功能。
有三种变体携带存储大小,但其中只有一种会警告大小被丢弃。 区别在于你是否有选择。ephemeral 卷的 sizeLimit 是可选的,因此写上它是一个决定,警告会告诉你该值在此目标上不影响任何内容,可以删除——警告仅供参考,且在输出之外,生成的文件与没有该警告时逐字节相同,--no-unsupported-field-warnings 会连同该类别的其他警告一并屏蔽它。persistent 或 persistentTemplate 卷的 size 是必填的,因此任何版本的文档都不会省略它:在此处每次构建都发出警告,会在每个有状态 workload 上触发,却指出不了任何你能修改的内容,因此这一区别在此说明,而不是在每次构建时报告。以 compose 为目标时,持久卷的 size、class 和 accessModes 不影响生成文件中的任何内容——你得到的是一个普通的命名卷,其大小和后端由 compose 主机卷驱动的默认行为决定。class 和 accessModes 是可选的,因此你写入的每一个都会像 ephemeral 的 sizeLimit 那样被报告:每个字段一条 unsupported-field 警告,仅供参考且在输出之外,由同一个标志屏蔽。请在主机上设置底层存储的大小,或在这些字段确实会进入输出的 Kubernetes 目标上设置。
没有任何容器挂载的卷会触发一条 unsupported-field 警告,在其编写位置(volumes.<name>)指明该卷,因为此时进入生成文件的内容因变体不同而差异很大。persistent 和 persistentTemplate 仍会生成其顶层声明,因此卷会被创建,但没有任何东西使用它。ephemeral、configmap 和 secret 在挂载本身之外没有任何表达——它们分别转换为写在挂载路径上的 tmpfs 条目、configs 引用或绑定挂载——因此没有任何挂载时,你声明的卷在输出中完全不留痕迹。第二种情况正是该警告存在的原因:没有它,一个忘记挂载的 configmap 卷会直接消失,生成的文件中没有任何可察觉的线索。workload 的每个容器都算作挂载者,包括初始化容器,因此仅由初始化容器挂载的卷已正确连接,不会触发警告。该警告仅供参考,且在输出之外——生成的文件与没有该警告时逐字节相同——--no-unsupported-field-warnings 会屏蔽该类别。
卷名如何派生
persistent 或 persistentTemplate 卷会成为一个 compose 命名卷:一个顶层 volumes: 条目,由挂载它的每个容器引用。compose 卷是共享存储,顶层 volumes: 块按名称合并其条目——因此两个编写的卷若得到同一个名称,就会成为两个容器共同写入的一个卷,而输出文件中没有任何迹象表明原本应是两个卷。因此,名称由共同说明它是哪个卷的两个标识构成:该卷所属的 <component>,以及 Workload 在 volumes: 下为该卷指定的名称。
compose 卷名接受的字符集比这两个标识可能包含的字符都要窄:字母、数字、点、下划线和连字符。派生过程不会替换 compose 不接受的字符,而是将其转写出来,因此只要两个卷有任何不同,就会得到两个名称——并且组装后的名称可以反向解析回构成它的两个标识。
- 字母、数字、点和下划线按编写原样保留。
- 只要连字符后面的字符被直接保留且不是小写
z,该连字符就按编写原样保留。连字符后跟小写z表示开始一个转义,因此在该位置编写的连字符本身会被转写——api-zone变为api-zhzone,正是这一点使任何名称都能无需猜测地反向解析。后面没有任何字符的连字符出于同样的原因也会被转写,因此db-得到db-zh。 - 其他每个字符都写作
-z后跟一个表示该字符的字母:s表示路径分隔符,h表示上述规则未保留的连字符。其余任何字符——包括空格和非 ASCII 字母——写作x加该字符的六位十六进制码点;不构成任何字符开头的字节写作b加其自身的两位值,因此不是有效文本的名称仍会被区分地转写,而不会被合并。 - 空值写作
-ze,任何非空值都不会产生它。 - 两个标识由
--连接。单个编码后的标识绝不包含这对字符,因此连接后的名称可以明确地表明一个标识在何处结束、另一个在何处开始。
因此,component store 加上 Workload 称为 data 的卷,得到卷名 store--data;db-server 加 data 得到 db-server--data。相同的输入总是产生相同的名称。
双连字符连接使这对标识无歧义,而单字符连接做不到。 任一标识本身都可能包含连字符,因此单连字符连接会使名称可以在多个位置拆分:db 加名为 data-cache 的卷,与 db-data 加名为 cache 的卷,都会拼成 db-data-cache;而由于顶层块按名称合并,这两个 component 将共享一个卷,输出文件中却没有任何迹象。编码后的标识绝不包含一对连字符,因此双连字符连接不允许第二种解读:二者分别得到 db--data-cache 和 db-data--cache。
更改任一标识都会重命名 compose 卷,而 compose 不会原地重命名卷。 新名称下会重新创建卷,旧卷连同其中的数据保留下来,因此容器启动时面对的是空存储,而内容留在一个没有任何东西挂载的卷中。只有将重命名任一标识作为需要规划的替换——先备份、复制数据或安排时间——才可进行,而不应作为一项直接发布的变更。
控制器形式
Workload 的 form 选择一种抽象的控制器形态(参见 entities/workload.md)。compose 将 stateless 和 stateful(以及视为 stateless 的空默认值)渲染为长期运行的服务;stateful 形式会为 persistentTemplate 配套卷添加命名卷。daemon、scheduled 和 task 形式没有清晰的单主机 compose 映射,因此声明其中之一且面向 compose 边界的 Workload 会以 TRANSLATION_ERROR 停止,并指明该形式和受支持的集合——compose 不会把不受支持的形式降级为一个歪曲原意的普通服务。reference 形式的 Workload 声明的是一个外部端点,没有容器,因此 compose 不会为它生成服务。
由于不会为 reference Workload 生成任何服务,因此没有任何东西读取它所实现的组件的交付管道:附加到该组件的凭据——由 dotenv-secret 或附件自身的 inject: 块在其管道上交付——不会到达任何生成的文件。因此,每个以这种方式实现外部服务、且其 Component 声明了凭据槽的标准库 Compose Recipe,都会拒绝填充该槽的凭据:构建会停止并指出该槽和该组件,而不是在缺少凭据的情况下成功。在 compose 上,外部服务的凭据应附加到调用它的组件上,并使用该组件读取的环境变量。该拒绝是每个 Recipe 自身的断言,在本 provider 渲染任何内容之前运行。本 provider 也会在节点本身处拒绝,无论 Recipe 来自哪个目录:reference 节点上材料被声明为敏感的附件——其 Feature 将某个字段声明为 sensitive: true,或其填充的槽如此声明——会以 TRANSLATION_ERROR(E0288)停止构建,并指出该节点和每个此类附件,无论是否有任何槽声明了它附加时所用的名称。不携带任何声明为敏感内容的附件不会在此处被拒绝。这些 Components 将其凭据槽声明为可选,因此在 compose 上,留空的槽不会导致任何停止。在 Kubernetes 实现需要凭据的情况下——twilio、vonage、telnyx、bland、letta、retell 和 vapi 的 helm Recipes——该 Recipe 则要求填写该槽,并在其为空时停止构建并指出该槽。
服务暴露
Workload services 条目的 type 字段决定 compose 是否发布端口,以及在哪个主机地址上发布:
| Workload 服务类型 | Compose 行为 |
|---|---|
ClusterIP | 不发布 ports:——服务只能在 compose 网络内访问 |
NodePort | 发布 ports: [<host>:<container>],在所有主机接口上 |
LoadBalancer | 发布 ports: [<host>:<container>],在所有主机接口上(compose 没有托管负载均衡器的等价物;主机端口发布是最接近的对应方式) |
Loopback | 发布 ports: [127.0.0.1:<host>:<container>]——只能从主机自身访问,其他任何地方都无法访问 |
Headless | 不发布 ports: |
哪个数字放在哪一侧。 服务条目指明一个容器端口并为其指定一个编号,就像 Kubernetes Service 将其 port 映射到 targetPort 一样。条目的编号是所发布端口对的 <host> 一侧,而该名称解析到的容器端口的编号是 <container> 一侧。因此,声明 http: 8080 的容器与写有 http: 8081 的 NodePort 条目会发布 8081:8080:主机的 8081 端口通向容器提供服务的端口。携带容器端口自身编号的条目会在两侧发布该编号,即 8080:8080。compose 网络上的对等方通过服务名称在容器的端口上访问该服务,而不是在已发布的端口上——已发布的端口属于主机——因此,发布自选端口的 Recipe 交给其使用方的仍是容器的端口。
Loopback 条目只绑定 IPv4 回环地址,不绑定 IPv6 回环地址 ::1:compose 的端口语法每个条目只承载一个主机地址,而回环接口没有 IPv6 地址的主机无法绑定它,服务在那里将无法启动。主机上的客户端通过 127.0.0.1 访问该端口。
当单个 Workload 上的多个服务以相同的编号发布同一个容器端口时,该端口只发布一次,且可达范围最广的胜出:任何 NodePort 或 LoadBalancer 引用都会在所有主机接口上发布该端口,即使某个 Loopback 条目也指明了它,也无论哪个条目先声明;只有 Loopback 条目指明的端口在 127.0.0.1 上发布。以两个编号发布的同一个容器端口会发布两次,每个编号各一次。已发布的端口按容器端口顺序列出,同一容器端口内则按发布端口排序。
端口传输协议。 发布的条目会携带其所指容器端口上声明的传输协议,以 compose 的 /protocol 后缀表示:53:53/udp,对于 Loopback 条目则为 127.0.0.1:53:53/udp。未声明传输协议的端口发布为不带后缀的 <host>:<container>,沿用 compose 自身的默认值。compose 将已发布端口的传输协议写作 tcp 或 udp;声明 SCTP 的端口没有 compose 写法,因此会以 TRANSLATION_ERROR 停止,而不是发布一个会使用不同传输协议的端口。没有任何服务发布的容器端口完全不会出现在 compose 文件中,因此在这类端口上声明的传输协议无处可写,也不会导致停止。
多容器 Workloads
具有多个容器的 Workload 会成为一个主服务,外加每个非主容器各一个 sidecar 服务。主容器是名为 main 的容器(若存在),否则为声明顺序中的第一个容器。sidecar 通过 network_mode: "service:<main>" 共享主服务的网络命名空间——这是 compose 中最接近 Kubernetes pod 共享网络模型的原语。
边车服务或 Init 服务如何命名
主服务按原样使用 <component> 名称。Workload 生成的其他每个服务 — 每个边车一个,每个 Init 容器 一个 — 都由两个标识共同命名:<component> 和容器的名称;对于边车,容器名称是它在 containers: 下的键,对于 Init 容器,则是它的 name,或未命名的 init 条目所取的按位置命名的 init-<index>。组装后的 services: 块每个名称只容纳一个服务,因此名称的构造方式确保:在任一标识上不同的两个容器总会得到两个名称。
每个标识的写出方式与 卷名称 的两个部分完全相同 — 字母、数字、点和下划线按原样保留,连字符在那里的规则保留它的位置保留,其他每个字符都会被转写 — 两者以 -- 连接,任何转写后的标识都不包含它。因此,带有边车 logger 的组件 api 将其作为 api--logger 运行,platform 的 Init 容器 import-seed 作为 platform--import-seed 运行,api 未命名的第一个 init 条目作为 api--init-0 运行。容器名称若带有服务名称不接受的字符,会被转写,而不是按原样输出:api 中名为 warm cache/x 的 Init 容器作为 api--warm-zx000020cache-zsx 运行。
双连字符连接使两个组件的容器保持区分。 带有容器 warm-cache 的 api 和带有容器 cache 的 api-warm 分别作为 api--warm-cache 和 api-warm--cache 两个服务运行,而单连字符连接会把两者都拼成 api-warm-cache。
边车和 Init 容器共用这一套命名,因此带有相同名称的 containers 条目和 initContainers 条目会得到相同的服务名称,构建会因这一对条目而停止,而不是用一个容器替代另一个运行(参见 Init 容器)。
组件自身的服务不会使用这些名称。 主服务以组件命名,而组件名称中写有的双连字符在那里本身也会被转写 — 名为 api--prep 的组件作为 api-zh-prep 运行 — 因此它从不包含 -- 连接。如果两个不同组件的服务仍在同一个 compose 文件中撞上同一个名称 — 例如通过某个工件为自己命名的服务 — 构建会停止并指出两者,如 按 (path, provider) 输出 所述。
更改组件名称或容器名称会重命名该服务。 Compose 将新名称下的服务视为一个新服务,因此会以新名称重新创建其容器。
Pod 级字段
Pod 级 Workload 字段只应用于主服务——sidecar 共享主服务的网络命名空间——init 服务也遵循同样的规则。唯一的例外是 pod 的用户:pod 以 podSecurityContext.runAsUser 和 runAsGroup 运行其所有容器,因此它们会作用于该 Workload 生成的每个服务,包括 sidecar 和 init 服务。
其中若干字段映射到 compose 服务字段:
| Workload 字段 | Compose 字段 |
|---|---|
podSecurityContext.runAsUser / runAsGroup | Workload 的每个服务上的 user("1000",或带组时为 1000:3000)。设置了自己的 securityContext.runAsUser 的容器则改为在其自身服务上以该用户运行,若它还设置了自己的 runAsGroup,则同时使用该组 |
terminationGracePeriodSeconds | stop_grace_period: <n>s |
dnsConfig.nameservers / dnsConfig.searches | dns / dns_search |
hostAliases | 每个主机名一个 extra_hosts 条目,按编写顺序 |
hostNetwork: true | network_mode: host |
在节点网络上运行。 声明 hostNetwork: true 的 workload 会在其自身服务上获得 network_mode: host,该服务随后不再挂接到边界网络:compose 拒绝同时声明 networks: 和 network_mode: 的服务,因此二者是互斥选项而非叠加。其实际后果正是主机网络始终带来的后果——对等方不再能通过该网络以 compose 服务名访问该服务,因为它已不在该网络上;它们通过主机自身的地址访问它,这正是该声明所要求的。边界上的其他所有服务不受影响。
有两种形态与之组合。sidecar 仍指向主服务(network_mode: "service:<main>"),因此它无需自行声明任何内容就会随主服务进入主机网络——与 Kubernetes pod 中各容器共享一个命名空间的方式相同。init 服务则不然:它以自身身份加入边界网络,因为共享主服务的命名空间会使主服务对它的等待形成循环。因此,同时具有 hostNetwork 和 initContainers 的 workload 会在主机网络上运行其自身服务,而其 init 服务仍留在边界网络上,这比它所模拟的 pod 形态更窄;一条 unsupported-field 警告会指明这一差异,而不是留到运行时才被发现。
其余字段没有单主机的等价物。**没有任何字段会被静默丢弃:**每个编写的此类字段都会引发一条指明该字段的 unsupported-field 警告,使编写者得知目标无法遵循哪项设置,而不是从运行中的栈里才发现。
| Workload 字段 | compose 无法遵循的原因 |
|---|---|
scheduling | 调度放置——nodeSelector、affinity、tolerations、topologySpreadConstraints——以存在一个在节点间进行选择的调度器为前提。compose 运行在单个主机上 |
replicas | compose 自身的副本数位于 deploy: 下,是 swarm 模式的功能 |
runtimeClassName | 选择替代的容器运行时(例如启用 GPU 的运行时)在 compose 中没有对应表达 |
priorityClassName | 抢占顺序以存在调度器为前提 |
serviceAccount | Workload 身份是集群概念 |
imagePullSecrets | compose 主机上的镜像仓库凭据是主机自身的登录状态,而不是文件中的字段 |
dnsPolicy, dnsConfig.options | compose 只提供 dns 和 dns_search,没有更细粒度的设置 |
podSecurityContext.fsGroup, podSecurityContext.supplementalGroups | user 只承载一个用户和一个组;pod 的卷所属的组,以及其进程的其他组,都不会被转换 |
podSecurityContext.runAsGroup,当 pod 未设置 runAsUser 时,或当某个容器(主容器、sidecar 或 init)设置了自己的 runAsUser 但未设置 runAsGroup 时 | user 只能在用户旁边指定组,而容器自己的用户会取代 pod 的用户,因此 pod 的组不会到达以这种方式编写的任何服务 |
容器级 securityContext 部分转换:readOnlyRootFilesystem → read_only,capabilities.add / drop → cap_add / cap_drop,runAsUser / runAsGroup → user。runAsNonRoot 和 allowPrivilegeEscalation 在 compose 中没有对应表达,会引发同样的 unsupported-field 警告;旁边没有 runAsUser 的容器 runAsGroup 也是如此:此时若 pod 设置了用户,该服务就以 pod 的用户运行,但不带该组。
本节中的每条警告都是建议性的,且在带外报告:构建成功,输出文件与没有该警告时逐字节相同。--no-unsupported-field-warnings 可屏蔽此类警告。
Init 容器
Workload 的 initContainers 条目会各自成为独立的服务,采用 compose 的“运行至完成”惯用方式。每个条目添加一个服务,按照与 sidecar 相同的命名方式由 <component> 和该条目的 name 命名——普通名称为 <component>--<container-name>;省略 name 的条目采用 Workload 参考中记载的按位置命名的 init-<index> 名称,并据此命名。
编写契约所承诺的顺序——init 容器按编写顺序依次运行至完成,且其他所有容器只在它们全部完成后才启动——通过 depends_on 的长格式表达:
- 第一个之后的每个 init 服务都以
condition: service_completed_successfully等待其前一个服务。 - 主服务以及每个 sidecar 服务都以相同条件等待最后一个 init 服务。由于 init 服务构成一条链,等待最后一个即已足够。
- 每个 init 服务都带有
restart: "no"。init 服务只运行一次;重新启动的服务永远不会达到其依赖方所等待的完成状态,因此在 init 容器上编写的restartPolicy不会改变这一点。
services: platform: image: platform:1.0 depends_on: platform--verify-seed: condition: service_completed_successfully platform--import-seed: image: platform:1.0 restart: "no" platform--verify-seed: image: platform:1.0 depends_on: platform--import-seed: condition: service_completed_successfully restart: "no"init 容器的转换方式与其他任何容器完全相同:其 image(包括 aggrega.ai/image-registry 注解所施加的镜像仓库重写)、command、args、variables、attachments、volumeMounts 和 securityContext 都会传递到 init 服务。正因如此,init 容器所携带的配置——最常见的是它挂载并写入主容器同样挂载的卷中的文件——能够保留到 compose 目标上,而不会随容器一起丢失。compose 无法表达的形式对 init 容器和普通容器的失败方式相同:声明了 lifecycle 或 envFrom 时,会以 TRANSLATION_ERROR 中止,并指明其来源的 init 容器。
由于 init 服务属于非主服务,它与主服务有两点不同:
- 不应用 Pod 级 Workload 字段,与 sidecar 遵循的规则相同——pod 的用户除外,它会按照 Pod 级字段所述作用于每个服务。
- init 服务直接加入其边界的网络,而不是像 sidecar 那样共享主服务的网络命名空间。这是必须的:主服务等待 init 服务,而共享命名空间本身就是对主服务的依赖,这会使等待形成一个 compose 拒绝启动的循环。因此,init 容器可以通过服务名访问边界网络上的其他服务,但不共享主服务的
localhost。
init 服务和 sidecar 服务共享同一个名称空间,因为两者由同一种命名方式命名,因此 initContainers 条目与 containers 条目不能使用相同的名称。若出现这种情况,编译器会以 TRANSLATION_ERROR 中止,并指明节点、容器名称以及两者都想要的服务名称,而不会让一个服务悄无声息地替换另一个。
生成完成条件不会提高最低 Compose 版本要求。condition 及其取值属于基础 Compose Specification——不同于同一长格式块中与之并列的 restart 和 required 字段,规范将后两者与特定的 Compose 版本绑定。compose provider 的输出所要求的每个最低版本都与需要它的构造一同出现:内联 configs.content 需要 ≥ 2.23.1,挂载的 subPath 需要 ≥ 2.26.0(参见卷),模型需要 2.38。其中第一个适用于任何携带内联 content: 配置的 compose 输出,configmap 卷背后的文件和桥接跨网络边背后的配置都是以这种方式到达的——而不只是某一条编写路径。
服务加入哪个网络
每个服务都会加入一个 Docker 网络;sidecar 通过其指向主服务的 network_mode 引用继承该网络。节点落在哪个网络上,取决于该节点上的 aggrega.ai/namespace 注解;节点没有该注解时,则回退为 compose 文件的路径——即该文件在构建输出目录下写入的目录,例如对 directory: 为 bridge 的边界而言是 bridge/compose。因此,同一个 compose 文件中所有没有该注解的节点,无论位于哪个边界,都会加入以该文件路径命名的同一个网络:共享一个 compose 文件的未注解边界共享该网络,而 aggrega.ai/namespace 正是将它们分开的手段。带有不同注解的节点则按每个不同的注解各落在一个网络上。网络名称如何派生说明了这一标识所生成的名称。
网络名称如何派生
compose 网络是共享的 L3 连通性,顶层 networks: 块按名称合并其条目——因此,两个标识若得到同一个名称,就会变成同一个网络,两组服务都位于其上,可以通过服务名相互访问,而生成的文件中没有任何迹象表明原本打算使用两个网络。因此,名称由表明它是哪个网络的标识构建:节点的 aggrega.ai/namespace 注解,或节点没有该注解时 compose 文件的路径。
compose 网络名称接受的字符集比这两种标识可能包含的字符都要窄:字母、数字、点、下划线和连字符。对于 compose 不接受的字符,派生过程不做替换,而是将其转写出来,因此只要两个标识有任何不同,就会得到两个网络——并且名称可以反向解析回构建它的标识。
- 字母、数字、点和下划线按编写原样保留,大小写也与编写时一致。因此
prod和Prod是两个网络,而不是一个。 - 只要连字符后面的字符被直接保留且不是小写
z,该连字符就按编写原样保留。连字符后跟小写z表示开始一个转义,因此在该位置编写的连字符本身会被转写——api-zone变为api-zhzone,正是这一点使任何名称都能无需猜测地反向解析。后面没有任何字符的连字符出于同样的原因也会被转写,因此db-得到db-zh。 - 其他每个字符都写作
-z后跟一个表示该字符的字母:s表示路径分隔符,h表示上述规则不保留的连字符。其余任何字符——包括空格和非 ASCII 字母——都写作x加上该字符的六位十六进制码位;不构成任何字符开头的字节则写作b加上其自身的两位数值,因此即使标识不是有效文本,也仍会被区分地转写出来,而不会被合并。 - 完全不存在的标识——即位于没有路径的 compose 文件中、没有
aggrega.ai/namespace注解的节点——写作-ze,作者编写的任何标识都无法生成该名称。因此,没有标识的网络永远不会与某个以特定方式拼写的有标识网络共享连通性。
因此,命名空间 prod 得到网络 prod,core-net 得到 core-net,位于 dist/app/compose 的 compose 文件得到 dist-zsapp-zscompose。相同的输入总是生成相同的名称。
**命名空间和 compose 文件的路径写入同一个空间。**它们是命名同一事物(节点位于哪个网络)的两种方式,因此命名空间为 app/compose 的节点,与位于 app/compose 处的 compose 文件中、没有命名空间的节点,会有意落在同一个网络上,这与两个带有相同 aggrega.ai/namespace 注解的边界完全一样。如果你希望两个节点分开,请为它们指定不同的标识。
**更改节点的标识会重命名 compose 网络,而 compose 不会原地重命名网络。**网络会以新名称重新创建,其上的每个服务都会重新创建以连接到它,而旧网络会一直保留,直到被移除。网络不承载数据,因此不会丢失任何内容——但其上的容器确实会重启,任何跨越此次变更保持的连接都会断开。应将更改命名空间注解或 compose 文件写入的目录视为一次需要规划的重新部署,而不是一个可以原地调整的值。
当两个边界合并到同一个装配路径(共享 directory:)时,它们中没有 aggrega.ai/namespace 注解的节点共享该文件唯一的网络;为每个边界指定各自的 aggrega.ai/namespace 注解,合并后的 docker-compose.yaml 就会为每个注解声明一个顶层 networks: 条目。同一 compose 文件中来自不同边界的服务可以在 compose 默认的 DNS 解析范围内通过服务名通信,但受 compose 自身跨网络可达性规则的约束。单个 compose 文件内的跨网络 L4 路由由标准库的 compose-bridge Feature 实现,它是目录内容,此 provider 不包含它的任何逻辑:附加在共同祖先边界上时,它的 FeatureRecipe 会根据该边界的 uses 边派生一个网关,这些边的两端都装配到该边界自己的 compose 文件中,并位于该文件的不同网络上——即一个 aggrega-gw 服务,其 nginx stream 配置代理每条桥接的边(每条边一个 server 块,使用目标的端口,冲突时回退到 portBase)——而它自己的 injectMapping 会将每个消费者的主机环境变量重写为 aggrega-gw:<port>;当同一连接同时提供主机和端口时,则重写为 aggrega-gw,并将端口变量重写为监听端口。该重写会替换消费者自身连接所提供的值;如果附加到该消费者的另一个 Feature 提供了同一个变量,构建会停止并指出两者,而不会替换它。该 FeatureRecipe 的 valuesMapping 将该配置写为挂载的 compose config——一个带有内联 content: 的顶层 configs: 条目,由网关引用并挂载到 /etc/nginx/nginx.conf;这不需要运维人员自行挂载——并在网关的 x-aggrega-networks-of 下列出每个桥接的端点,此 provider 会将其解析为这些端点所在的网络(见下文)。两端装配到两个 compose 文件中的边不会被桥接,并保留目标自身的名称;没有可桥接内容的边界仍带有空闲的网关,它没有配置,也没有自身网络之外的网络;而附加在其 compose 文件不含任何组件的边界上的桥接会使构建停止,而不是把网关写到无处。stream 配置带有 resolver 指令,并通过每条边一个变量进行代理(set $uN <host>; proxy_pass $uN),使每个上游在连接时解析,而不是在启动时只解析一次——否则直接用 proxy_pass 指向尚未运行的目标,会导致网关在启动时失败。(这些变量中的 $ 在 configs.content 中被转义为 $$,使 Docker Compose 自身的 $ 插值为 nginx 留下字面量 $。)内联 configs.content 需要 Docker Compose ≥ 2.23.1。参见 compose-bridge 模式。
加入其他组件的网络——x-aggrega-networks-of
片段所写的服务——合并覆盖文档后的源 compose 文件,或 artifacts: 正文——可以在扩展键 x-aggrega-networks-of 下列出装配到同一 compose 文件中的其他组件,从而加入它们的网络:该键是一个组件 id 列表,即 Aggregate 为其组件指定的 id,边界作用域的 FeatureRecipe 会将其读作 .boundary.components 的键,以及其 .boundary 边列表中的 source 和 target。provider 将每个 id 解析为该组件在此文件中所在的网络,所用的放置方式与每个节点所采用的相同,并将这些网络添加到该服务,每个只添加一次并按名称排序,排在该服务自身网络之前,服务仍会加入自身网络。该键本身不会出现在组装后的文件中。provider 只将这些 id 读作待解析的引用,不涉及该服务的任何用途,因此任何 Recipe 或 FeatureRecipe 都可以使用该键;compose bridge 的网关正是以这种方式加入它所中继的各端点的网络。
# written by a FeatureRecipe attached at the boundary `bridge`, whose file holds adminer (namespace frontend) and db (namespace backend)services: probe-svc: image: busybox x-aggrega-networks-of: ["adminer", "db"]# dist/bridge/compose/docker-compose.yaml (abridged)services: probe-svc: image: busybox networks: - backend - frontend - bridge-zscompose组装文件时,以下三种情况会以 TRANSLATION_ERROR 停止构建,每种都会指出该服务:
- 没有任何装配到此文件中的组件带有的 id——例如装配到另一个 compose 文件中的组件的 id。网络属于一个文件,因此消息会指出该 id 以及该服务所在的文件。只列出装配到同一文件中的组件,或移除该 id。
- **不是字符串列表的值。**该键接受组件 id 列表,即使只有一个 id 也是如此。
- **写有
network_mode的服务上的该键。**Compose 不允许带有network_mode的服务加入网络;请移除二者之一。
depends_on 推断
compose provider 根据 IR 的 uses 边自动推导 depends_on。对于源和目标都向合并后的 compose 文件贡献服务的每条边,provider 会向源服务添加 depends_on: [<target>]。
**依赖落在源 component 自身的服务上,而不落在该 component 贡献的任何其他服务上。**同时声明了init 容器的 component 会为每个条目贡献一个运行至完成的服务,这些服务都不会收到由边推导的依赖——边指名的是 component,而 init 服务有自己的名称。因此,需要访问边的目标的 init 容器(例如针对 component uses 的数据库执行的 schema 迁移)相对于该目标没有任何顺序约束,可能在目标可访问之前就运行;而 component 自身的服务既要等待 init 链完成,也要等待目标已启动。
由边推导的条目以无门控方式生成:无论目标是否声明了 healthcheck,它们都具有 service_started 语义。以目标的健康状态为门控(这会让 compose 运行时阻止启动,直到目标的 healthcheck 报告健康)是可以表达的,而 uses 边并不要求这样做。指名同一对服务的波次是唯一会改变由边推导条目的条件的因素,而这样做是因为波次提出了要求,而不是因为边提出了要求。
为保证输出稳定,由边推导的条目按目标的字母顺序生成。源或目标由其他 provider(helm 或 helm-chart)提供服务的边会被跳过——depends_on 仅适用于 Release 中由 compose 提供服务的子集。
服务的 depends_on 以 compose 的两种形式之一生成,绝不混用,因为 compose 要求长形式的每个条目都带有条件:
- 短形式列表(
depends_on: [<service-name>]):当该服务上没有任何条目带有条件时使用。所有依赖仅来自uses边的服务都属于这种情况。 - 长形式映射:当任一条目带有条件时使用——即该服务还需等待某个init 容器,或者某个部署波次为其排序时。此时,由边推导的条目会生成显式的
condition: service_started,Compose Specification 将其定义为与短形式等价,因此其含义不变。
在一个服务内,各来源保持各自的顺序,互不交错:首先生成 init 链的等待(其顺序即作者编写列表的顺序),然后是按字母顺序排列的由边推导的条目,最后是按字母顺序排列的由波次推导的条目。
部署波次排序
Release 边界的 syncWave: 值决定该边界渲染到的 compose 文件中各服务的顺序。边界中的每个组件都继承边界的波次;当多个边界共享同一个 directory:,从而它们的贡献合并到单个 docker-compose.yaml 中时,合并后的文件包含多个波次,provider 会将它们之间的顺序表达为 depends_on。
**每个服务等待紧邻的前一个含有服务的 wave 中的每个服务,而不等待比它更早的 wave。**其余部分由 Compose 传递解析:wave 2 中的服务等待 wave 1,后者又等待 wave 0,因此整个序列都是有序的,而每个服务自身的列表只保持一个 wave 的规模,而不是整个文件的规模。wave 不必连续,负值也很常见:-1 常用于在其他一切之前运行的迁移。
条件取决于目标能够满足什么。 波次意味着较早的一组在较晚的一组启动之前已就绪,这是就绪状态而非进程启动,因此:
- 如果目标服务声明了
healthcheck,等待条件为condition: service_healthy; - 如果没有声明,等待条件为
condition: service_started,因为没有 healthcheck 的服务永远无法报告健康,对它进行基于健康状态的等待永远不会被满足,文件将永远无法启动。
较弱的条件在输出文件中与较强的条件并列可见,此外构建还会在警告中列出每个这样的服务,使期望就绪排序的作者得知所声明的波次中哪一部分仅以启动排序生效。该警告仅供参考:构建会成功,渲染出的字节与没有警告时完全相同。为该容器添加 health: 块即可升级等待条件。--no-unsupported-field-warnings 可屏蔽此类警告。
波次仍会记录为标签。 排序是在 aggrega.ai/sync-wave 标签之外额外添加的,而不是取代它:查看输出文件的读者通过该标签了解服务来自哪个波次,而 depends_on 条目并不说明这一点。
当波次和 uses 边指向同一对服务时,由一个条目同时承载两者。 Compose 对每个依赖只接受一个条目,因此一个既 uses 某个目标、又位于其后一个波次的服务只输出一个条目,并以波次的条件为准:波次的要求是两者中较强的,因此表达的是它。
所有组件都位于同一波次的边界不会因此输出任何内容。 完全未声明 syncWave 的 Release 也是如此:每个贡献者都采用该字段的默认值 0,合并后的文件只有一个波次,输出与 provider 不表达任何波次排序时完全相同。
跨两个 compose 文件的排序无法表达,也不会被近似处理。 depends_on 指向同一文件内的服务,而求值为不同装配路径的边界会生成不同的 docker-compose.yaml 文件,compose 运行时将它们视为相互独立的项目。因此,波次只对其渲染到的文件中的所有服务排序,不涉及文件之外的内容。对两个 compose 项目进行排序是运维人员的事,跨文件路由也是如此;声明共享的 directory: 才能让两个边界进入同一个文件,这是一项输出形态上的决定,应出于其自身的理由做出,而不是为了获得排序。
指向更晚波次的 uses 边会按编写的原样输出,并被报告。 输出的 depends_on 反映所声明的内容——包括 uses 边和波次。如果某条边的消费方所在的波次早于它所使用的目标,那么这条边所表达的就与波次所表达的相反:边让消费方等待目标,而波次则让目标经由二者之间的每个波次等待消费方。合并后的文件同时表达了这两者,构成一组 Docker Compose 拒绝启动的循环依赖。构建会在一条警告中指出每条这样的边,说明两个服务和两个波次,使循环在你构建时就暴露出来,而不是等到 docker compose up 时。该警告仅供参考——构建成功,渲染出的字节与没有该警告时完全相同——且 --no-unsupported-field-warnings 不会屏蔽它,因为没有任何内容被丢弃:两项声明各自都得到了表达,只是合在一起无法启动。它只覆盖直接的一对:它指出一条边所连接的两个服务,而不追踪整个循环。任何由 uses 边和波次共同构成的循环都至少经过一条这样的边,因此总会被报告;而仅由 uses 边构成、不涉及波次的循环,以及由 Recipe 提供的 compose 文件中写入的 depends_on 条目闭合的循环,都会按编写的原样输出且不被报告。请保持边的方向与波次顺序一致:把消费方放在目标所在的波次或更晚的波次中,或者把目标放在消费方所在的波次或更早的波次中。
# release.yaml fragment — three boundaries collapsing onto one compose fileboundaries: data: directory: ./dist/cluster syncWave: -1 components: migrator: {} # no health: block core: directory: ./dist/cluster syncWave: 0 components: store: {} # declares health: edge: directory: ./dist/cluster syncWave: 1 components: frontend: {} # uses: store# dist/cluster/compose/docker-compose.yaml (abridged)services: frontend: labels: aggrega.ai/sync-wave: "1" depends_on: store: condition: service_healthy # store declares a healthcheck migrator: labels: aggrega.ai/sync-wave: "-1" # lowest wave: waits on nothing store: depends_on: migrator: condition: service_started # migrator declares no healthcheck healthcheck: test: [CMD-SHELL, "nc -z localhost 5432"]frontend 没有指向 migrator:排序只到达紧邻的前一个波次,其余部分由 compose 通过 store 串联。
源模式
compose provider 的 source: 指定一个 provider 能够读取和解析的 docker-compose YAML 文件,并接受 source: 字段的两种形式:纯文件系统路径字符串,以及由 url: 携带位置的结构化对象。只要该位置是文件系统路径,它就以声明它的 recipe.yaml 所在目录为基准,而不是以调用构建的目录为基准,并且必须留在该目录内:跳出该目录的路径或绝对路径都会被拒绝,因为 Recipe 的一次发布所携带的每个文件都取自其目录——参见 entities/recipe.md “Content paths stay inside the Recipe’s own directory”。以这种方式指定的文件会随 Recipe 一起发布,而 Recipe 旁边未被其任何声明指定的文件则不会。
spec: capability: compose source: ./docker-compose.base.yaml # filesystem path to the base compose file valuesMapping: | services: api: image: "{{ .values.image }}"在结构化形式中,url: 的内容决定是否进行获取。通过 https:// 发布的片段会被获取,并以 kind: compose-https-fragment 固定;aggrega pull 获取它,构建从缓存中读取它。指向文件系统路径的 url: 不会被获取——它从磁盘读取,基准与上述纯字符串形式完全相同,aggrega pin 会将其所指文件的摘要记录在 Recipe 旁边的 entity.lock 中,构建随后在读取片段前进行比对。作为获取的替代方案,支持将远程片段 vendor 到本地并让 source: 指向该副本,但这不是必需的。schema 接受开放的结构化对象。
带有 source: <path-to-compose-file> 和 valuesMapping: 的 Recipe 会运行以下流水线:
- 读取
<path>处的基础 compose 文件并将其解析为 YAML。 valuesMapping模板基于 Recipe 的模板上下文求值。其输出被视为 compose 覆盖文档——一个补充或覆盖基础文件中字段的部分 compose 文件。- 基础文件和覆盖文档按照 docker-compose 原生的覆盖语义进行深度合并。
深度合并规则:
- 标量:覆盖优先。 当基础文件和覆盖文档设置了同一个标量字段时,覆盖文档的值替换基础文件的值。
- 映射:递归合并。 当基础文件和覆盖文档设置了同一个映射字段时,合并会递归进入该映射。两者都有的键遵循相同规则;只在一方存在的键原样保留。
- 列表:替换。 当基础文件和覆盖文档设置了同一个列表字段时,覆盖文档的列表完全替换基础文件的列表(不做逐元素合并或追加)。这与
docker compose -f base.yaml -f overlay.yaml config的行为一致。 null:替换并保留。 覆盖文档在服务上设为null的键——服务自身的键之一,如user、command或healthcheck,一个environment条目,一个标签,或直接位于healthcheck或deploy下的键——会像任何标量一样替换基础文件的值,并以key: null写入 compose 文件;它不会删除该键。当 provider 向该键写入自己的值时,文件中保留的是 provider 的值:labels: null会保留 provider 打上的来源标签,networks: null会保留它所附加的网络。写在覆盖文档其他任何位置的null不在此规则范围内。null随后的含义取决于 Compose 对该属性的解读——例如,没有值的environment条目会从docker compose运行所在的环境中取值。
服务作者编写的每个标签都会保留。 基础文件或覆盖层中服务的 labels: 可以写成映射,也可以写成 Compose 的 key=value 条目列表,每个标签都会与 provider 标记的来源标签一起进入 compose 文件。列表条目按 Compose 的方式读取:第一个 = 之前的文本是标签名,之后的文本是值,不含 = 的条目是值为空的标签。数字或 true/false 值按其文本写入,因此 replicas-hint: 2 在文件中写为 replicas-hint: "2",而写为 null 的标签保持为 null。若编写的标签与来源标签使用同一个键,文件中采用来源标签的值。既不是映射也不是列表的 labels: 值,以及不是文本的列表条目,都会停止构建,并指出源文件和服务。artifacts: 主体中的服务标签采用映射形式:在那里使用列表会停止构建,并指出该制品和服务。
合并后的文档随后与所有合成模式的贡献一起进入 Release 级合并,并采用相同的按边界网络划分和 depends_on 推断。
排除服务、卷和配置。 覆盖文档无法从基础文件中移除任何内容——覆盖值只会替换,从不删除——因此,如果获取的文件捆绑了 Release 不得运行的服务,就应使用 Recipe 或 FeatureRecipe 的 omits: 条目。此 provider 仅在此模式下遵循这些条目:合成的 Workload 和 artifacts: 正文在渲染时不使用它们。每个条目通过其 kind(service、volume 或 config)和 name(该单元在 services:、volumes: 或 configs: 下的键,精确比较)指定文件中的一个顶层单元。compose 文件没有命名空间,因此带有 namespace 的条目与指定其他任何 kind 的条目一样,会在该 component 渲染时终止构建,并指出该条目以及此 provider 接受的 kind;在排除任何内容之前会检查每个条目。条目在上述覆盖文档合并进文件之后进行匹配,因此覆盖文档添加的单元与基础文件声明的单元一样会被排除;匹配发生在 provider 添加其自身内容之前,因此条目永远不会指向这些内容。条目指定的单元会被移除,所有单元均被排除的部分也随之移除;其他每个单元的写入结果与没有这些条目时完全相同。条目仅作用于声明它们的 Recipe 或 FeatureRecipe 的文件:其他 component 或附加的 Feature 向同一个 docker-compose.yaml 贡献的内容不受影响,包括具有相同键的单元。provider 会报告每个条目排除了多少个单元,未排除任何单元的条目会终止构建;参见 An omits entry left out nothing the source rendered(omits 条目未排除源渲染的任何内容)。
被排除的单元不得仍被剩余内容引用,因为 compose 会拒绝引用了未声明的服务、卷或配置的文件。单元移除后,文件中仍对其中任何一个的引用都会终止构建,消息会指出每个引用它的服务或作业、所引用的单元以及引用所在的字段。引用即 Compose Specification 所定义的、文件中一个条目指向另一个条目的情形:
- 服务:由任一形式的
depends_on、links(SERVICE或SERVICE:ALIAS)、volumes_from(SERVICE或SERVICE:MODE)、设为service:<name>的network_mode、ipc、pid或uts、指向同一文件中服务的extends,或值为service:<name>的build.additional_contexts指定; - 卷:作为
volumes:条目的源被指定——即源为名称而非路径的短形式SOURCE:TARGET,以及type: volume的长形式; - 配置:由任一形式的
configs:条目指定。
服务的 pre_start 钩子和每个顶层 jobs: 条目也会被读取,以检查规范允许它们各自携带的引用。有些值只是看起来像引用,并不会被当作引用读取:以 container: 开头的 volumes_from 或 network_mode 条目指向容器,external_links 指向本文件未声明的容器,带有 file: 的 extends 指向另一个文件的服务,而 credential_spec.config 可能指向平台持有而非文件中的配置。每个值都按书写原样比较,因此通过 ${VARIABLE} 拼写的引用不在此检查范围内,而对文件从未声明的单元的引用则保持原样。
该检查只读取声明它的 Recipe 或 FeatureRecipe 自身的文件,因此即使同一装配路径上的另一个贡献者声明了同名服务,对被排除服务的引用仍会终止构建。要保留引用,就保留该单元。要去掉引用,可通过 valuesMapping: 修改引用条目——那里的列表会替换基础文件的列表,因此 depends_on: [] 可将其清空——或者同时排除引用它的服务。
按 (path, provider) 输出
每个 compose 组装路径生成一个 docker-compose.yaml。求值为不同路径的边界生成不同的 compose 文件;共享同一求值路径的边界生成一个合并后的 compose 文件,其中包含该路径上的所有贡献者。该路径由边界的 directory: 与每个组件的 subDirectory: 拼接而成(后者默认为 {{ .capability }},因此 compose 贡献者默认落在 compose/ 子文件夹下)。
同一组装路径内的服务名冲突会中止构建。当两个不同节点在同一 (path, provider) 元组上贡献了实例 ID 相同的服务时,编译器会中止,诊断信息按字母顺序列出每个参与贡献的 (boundary, node) 元组。作者可以通过重命名其中一个贡献者来解决冲突(通常是调整节点的标识符,使合成器生成不同的服务名),或通过不同的 directory: 声明将贡献者路由到不同路径。
顶层卷在组装路径内取并集,两个贡献者可以声明同一个名称,前提是它们对其描述一致。贡献者就是一个片段,因此一个组件的两个片段——其自身的 compose 文件和一个 artifacts: 条目,或两个 artifacts: 条目——与两个组件一样,是两个贡献者。一个命名卷就是一个物理卷,因此两个相同的声明描述的正是组装后文件最终包含的那个条目,该名称下只保留一个条目。由 provider 派生的卷不带主体,因此两个派生卷天然一致,而且它们无论如何都不会相遇(参见卷名如何派生)。
需要留意的是手写的 volumes: 条目,因为它可能带有自己的主体:driver、driver_opts 或 labels。当两个贡献者以不同的主体声明同一名称时,构建会以 TRANSLATION_ERROR 中止,并列出该卷及每个参与贡献的 (boundary, node, fragment) 元组。两位作者对同一个卷意见不一,组装器无从选择:保留任一主体都会丢弃另一位作者所写的内容,而构建本来可以成功。如果两位作者指的是同一个卷,就让两个声明保持一致;如果指的是两个卷,就重命名其中一个。顶层网络为每个不同的 aggrega.ai/namespace 注解各一个,另有一个以 compose 文件路径命名、供不带注解的节点使用的网络,命名方式见网络名如何派生;带有相同 aggrega.ai/namespace 注解的两个参与贡献的边界会合并为一个由二者共享的网络,共享该文件的两个未注解边界也是如此。
片段写入的每个键要么被保留,要么被拒绝
片段——合并覆盖文档后的源 compose 文件,或求值为 compose YAML 的 artifacts: 正文——只能通过 provider 所保留的键到达组装后的 docker-compose.yaml,而这组键是固定的。片段写入的每个键要么按原样保留到组装后的文件中,要么被指名拒绝;没有任何键会被无声地丢弃。一个片段就是一个 compose 文件,因此它是一个 YAML 文档。
- 保留。 顶层:
services、volumes、configs和models。服务上:image、pull_policy、command、entrypoint、environment、env_file、ports、labels、volumes、tmpfs、networks、network_mode、depends_on、healthcheck、restart、user、working_dir、privileged、read_only、cap_add、cap_drop、configs、models、deploy、stop_grace_period、dns、dns_search、extra_hosts和profiles。在 provider 描述的块内:deploy.resources及其limits(cpus、memory)和reservations(cpus、memory、devices,以及每个设备条目的driver、count、device_ids、capabilities和options);healthcheck的test、interval、timeout、retries和start_period;长格式volumes:条目的type、source、target、read_only和volume.subpath;长格式configs:条目的source和target;长格式depends_on:条目的condition;顶层卷的driver、driver_opts和labels;顶层 config 的content。模型的主体以及服务的长格式models:条目会保留每个成员,如模型所述。扩展成员——以x-开头的键——在顶层和服务上都会保留,如扩展成员所述。 - **拒绝。**任何其他键——服务上的
stdin_open、顶层的secrets:或name:、deploy.replicas、长格式depends_on:条目中的restart:或required:、顶层卷主体或healthcheck中的x-键——都会以TRANSLATION_ERROR停止构建,指出每个这样的键、它在片段中的路径(services.migrate.stdin_open)、该片段和该组件,并指出此类键的两个来源。一个是片段本身,修复方法是从中移除该键。另一个是未声明valuesMapping:的源 Recipe:此时节点的值会按原样叠加到 compose 文件上,因此每个值键都会作为片段的顶层键出现,修复方法是声明一个valuesMapping:,将每个值放在 provider 保留的键之下。YAML 合并键(<<: *anchor)引入块中的键,按其落地的位置判定,如同直接写在那里。由源渲染的片段命名为<component>.compose-fragment.yaml;artifacts:片段则以其 Recipe 为其指定的名称命名。 - 整体拒绝:片段自己的网络。 片段顶层
networks:下的条目无论其主体内容如何——空条目、driver或其他任何内容——都会以TRANSLATION_ERROR停止构建,并指出该条目(networks.back)、该片段和该组件,因为组装后的文件只包含 provider 派生的网络(参见服务加入哪个网络)。请移除该条目:服务无需任何声明即可加入其所属组件的网络,aggrega.ai/namespace注解决定组件加入哪个网络,服务在x-aggrega-networks-of下列出它还要加入其网络的组件,而compose-bridgeFeature 负责在不同网络上的服务之间路由。空的networks: {}什么也不声明,不会被拒绝,而服务自身的networks:列表按上文所述保留。 - **整体拒绝:包含多个文档的片段。**包含两个或更多以
---分隔的 YAML 文档的artifacts:正文会以TRANSLATION_ERROR停止构建,并指出该片段、该组件以及它包含的文档数量,因为合并会将片段读作一个 compose 文件,否则第一个之后的每个文档都会从组装后的文件中缺失。请将片段写成一个文档,或为每个文档提供各自的artifacts:条目。不包含任何内容的文档——即末尾的---开启的空文档——不计入。包含多个文档的源 compose 文件永远不会成为这样的片段:它在读取文件时就会被拒绝。
provider 不读取任何键的含义:一个键被保留是因为它在上述集合中,被拒绝是因为它不在其中。
扩展成员按原样携带
Compose Specification 将以 x- 开头的键保留给扩展:读取该文件的工具可以使用、而 Compose 本身会忽略的数据。片段在顶层和服务上的扩展成员会按原样进入组装后的文件,位于 provider 在该层级建模的所有键之后,并保持片段中的顺序;provider 不读取其中的任何内容,唯一的例外是服务的 x-aggrega-networks-of,provider 会将其解析为该服务加入的网络,并且不把它写入组装后的文件(参见加入其他组件的网络)。artifacts: 主体按其编写顺序保存这些成员。sourced compose 文件在合并其覆盖层之后,其键按名称顺序进入其片段,因此其扩展成员按名称顺序写出。
# an artifacts: bodyx-owner: team-bservices: migrate: image: example/migrate:1 x-schedule: manual通过 YAML 别名到达的成员会被完整写出,且不携带任何锚点,因此组装后的文件中绝不会出现缺少对应锚点的别名;正因如此,顶层成员可以持有服务的合并键(<<: *base)所引入的锚点。服务的成员随其服务一起携带。顶层成员在组装路径内按卷所遵循的规则取并集:两个片段以相同内容写出同一成员时只保留一个条目,无论它们以块样式还是流样式写出;两个片段以不同内容写出时,构建会以 TRANSLATION_ERROR 停止,并列出该成员以及每个参与贡献的 (boundary, node, fragment) 元组——同一组件的两个片段也包括在内。请让两个声明完全相同,或为其中一个换用其他名称。
profiles 将服务置于 Compose profile 之后。 列出 profiles: 的服务,除非其某个 profile 被启用,否则 docker compose up 不会启动它,而 docker compose run --rm <service> 会按需启动它——这是按需运行的任务在 compose 中的形态。该列表按片段的写法及其顺序携带:
# a sourced compose fileservices: migrate: image: example/migrate:1 profiles: [manual]模型
compose 文件的顶层 models: 部分声明该文件中的服务所使用的 AI 模型,服务通过自身的 models: 条目获得某个模型。无论片段是来源模式的 compose 文件,还是求值为 compose YAML 的 artifacts: 主体,provider 都会将这两者从片段带入组装后的 docker-compose.yaml,并沿用 Compose 自身的写法。Workload 不声明模型,因此 Workload 模式的 Recipe 不贡献任何模型。
- 模型主体按片段原样写出。
model(模型的 OCI 制品标识符)、context_size和runtime_flags保留其名称,其他所有成员(包括x-扩展)一并带上。在一个模型内,这三个具名成员排在前面,其余按键顺序排列,各模型按名称顺序写出,因此相同的输入会生成字节完全相同的文件。provider 不读取主体中的任何内容:它不检查标识符,也不了解将由什么来提供该模型。 - 服务的引用保持原有形式。 短形式列出模型名称(
models: [llm]);长形式将每个模型映射到endpoint_var和model_var,即接收模型运行器地址和模型标识符的变量名。两种形式都按片段使用的形式和顺序写出,并随其服务一起携带。长形式未指定变量名时,由 Compose 在运行文件时为其命名。 - 模型在组装路径内取并集,遵循与卷相同的规则。 两个贡献者以输出相同的主体声明同一模型名时,该名称下只保留一个条目;以不同主体声明时,构建会以
TRANSLATION_ERROR中止,并列出该模型及每个参与贡献的(boundary, node, fragment)元组。同一组件的两个片段在这里同样是两个贡献者。如果两个贡献者指的是同一个模型,就让声明保持一致;否则为其中一个换用其他名称。 - 每个引用都必须指向已声明的模型。 组装路径上的片段取并集后,如果某服务获得的模型在该路径上没有任何贡献者声明,构建会以
TRANSLATION_ERROR中止,并列出该服务和模型。该检查针对完整的并集进行,因此一个组件可以为其服务授予由同一组装路径上另一个组件声明的模型。 omits:条目不能排除模型。 此 provider 接受的类型是service、volume和config,指向模型的条目会像指向其他任何类型的条目一样中止构建。
模型在文件运行时提供,而非在构建时提供。Docker Compose 2.38 或更高版本在支持 Compose 模型的平台(如 Docker Model Runner)上,会拉取并运行服务所获得的每个模型,除非以 --all-resources 启动,否则会略过其他模型;并在每个获得该模型的服务中,将其引用所指定的变量设置为模型运行器的地址和模型的标识符。构建无法看到将运行该文件的主机,因此既不检查 Compose 版本,也不检查平台:带有模型的文件无论由什么运行,组装方式都相同。
附加到组件的 Feature 向同一文件贡献内容
附加到组件的 Feature 会将其服务贡献到宿主组件所组装进的 docker-compose.yaml 中,条件与宿主自身的 Recipe 相同。旁边不会有第二个文件:一个组装路径只生成一个文档,因此附加的 Feature 的服务要么在该文档中,要么根本不会部署。解除该 Feature 的附加只会移除这些服务,宿主组件自身的服务不受影响。
它们与其他贡献者一样,是该组装路径上的贡献者,因此上述所有内容都原样适用于它们:服务名规则,以及声明同一顶层卷名或 config 名的两个贡献者必须对其描述一致的要求。它们还会加入与该边界其余部分相同的网络,因此组件与附加到它的 Feature 无需额外声明即可通过服务名互相访问。
Feature 贡献的每个服务都带有为该附加关系组合出的标识,而非宿主组件的标识,因此在二者共同贡献的文档中仍可区分。标签和注解介绍了该标识的构建方式。
这与 Workload 容器级的 attachments: 块是不同的机制,二者因共用一个词而容易被混为一谈。将 Feature 附加到组件会向组装后的文档添加服务;而容器的 attachments: 条目读取的是某个槽位发布到该容器中的凭据,详见容器字段。
由 artifacts 输出的 compose 片段
当一个 Recipe 的 artifacts: 块求值为 compose YAML——即一个带有自身 services:、volumes:、configs:、models: 或 networks: 块的片段(每个条目内联编写,或按条目通过 $import: 加载)——时,合并到按 (path, provider) 组装的结果中遵循按结构区分的规则:
- 来自 artifacts 的
services:与按组件生成的服务一起合并到组装后的 compose 文件中。 同一组装路径上由两个不同组件贡献的同名服务会使构建中止,诊断信息会列出每个贡献者。单个组件内部的冲突——即该组件自身的 artifact 片段与为其合成的服务之间的冲突——不会被检测到,后来的贡献会替换先前的贡献,因此请让 artifact 中编写的服务名与合成器生成的<component>和<component>--<container-name>名称保持不同(参见sidecar 或 init 服务如何命名)。 - **来自 artifacts 的
volumes:合并到顶层volumes:块中。**两个条目指向同一名称时,若声明完全相同,则该名称下只保留一个条目,这与按组件生成的卷遵循同一规则;若声明不同,则构建中止,无论它们来自两个组件,还是来自同一组件的两个片段——该组件的两个artifacts:条目,或其中一个条目与该组件自身的 compose 文件。由于 artifact 片段自行编写其主体,这是两个贡献者最可能产生分歧的路径。请让 artifact 中编写的卷名与其组装路径上的其他卷名保持不同,包括与推导生成的<component>--<volume-name>形式保持不同——除非两个贡献者本意是描述同一个共享卷,此时它们的声明必须一致。 - 来自 artifacts 的
configs:合并到顶层configs:块中。configmap卷背后的文件正是由此进入组装结果:该卷变为一个指向该 configmap 的服务级configs:引用,而 artifact 片段声明一个同名条目,并带有内联的content:。组装路径上的片段合并完成后,每个服务级引用都必须解析到一个已声明的条目,否则构建会以TRANSLATION_ERROR中止,并列出每个未解析的引用——服务、config 名称和挂载路径。该检查针对合并完成后的结果进行,而非按组件进行,因此一个组件可以引用同一组装路径上另一个组件声明的 config。在贡献者一致时,合并按名称进行协调:两个贡献者以相同的content:声明同一 config 名称,会保留双方所描述的那一个条目。两个贡献者以不同的content:声明同一名称,会使构建以TRANSLATION_ERROR中止,并列出该 config 以及每个参与贡献的(boundary, node, fragment)元组(同一组件的两个片段也包括在内)——config 条目总是带有内容,因此保留任一声明都会丢弃某位作者编写的文件。请让 config 名称在其组装路径上的所有贡献者之间保持不同;若两个贡献者本意是提供同一个共享文件,则让它们的声明完全相同。 - 来自 artifacts 的
models:合并到顶层models:块中,服务的models:引用随其服务一起传递,遵循 Models 中的规则:两个贡献者声明同一模型名称时必须声明完全相同,且每个引用都必须指向该组装路径上某个贡献者声明的模型。 - 来自 artifacts 的
networks:会被拒绝。 compose provider 根据边界注解推导网络(每个不同的aggrega.ai/namespace注解对应一个网络,另外还有一个以 compose 文件路径命名、供所有未带该注解的节点加入的网络,每个网络都按网络名称如何推导命名),因此由 artifact 提供的网络声明在组装后的文件中没有位置:任何条目都会停止构建,并按片段写入的每个键要么被携带,要么被拒绝中的规则指出该条目和片段。请删除该条目,并通过aggrega.ai/namespace注解塑造网络,或者让服务通过x-aggrega-networks-of加入指定组件的网络;需要在单个 compose 文件内进行跨网络路由的作者使用compose-bridgeFeature。 - 来自 artifacts 的扩展成员会被携带。 顶层
x-键按编写顺序写在组装后文件的其他部分之后,遵循扩展成员按原样携带中的规则。 - 来自 artifacts 的其他任何顶层键都会停止构建。
services:、volumes:、configs:、models:以及扩展成员是组装器从片段中携带的全部内容。secrets:块和顶层name:都会使构建中止,并按片段写入的每个键要么被携带,要么被拒绝中的规则指出该键和片段。 artifacts:主体是一个文档。 包含多个 YAML 文档的主体会停止构建,并指出该片段及其包含的文档数量;请为每个文档提供单独的artifacts:条目。
前四者与 networks: 之间的不对称是结构性的:services:、volumes:、configs: 和 models: 携带按 Recipe 提供的内容,由组装器累积到组装后的文件中;networks: 是按边界划分的基础设施,由组装器根据边界状态推导。artifacts 可以扩展前者;只有边界注解能够塑造后者,这就是 artifact 自己的网络条目会被拒绝的原因。扩展成员是 Compose Specification 为其他工具定义的数据,因此按原样携带。其他一切都是组装后的文档中没有位置容纳的结构,这就是它被拒绝而不是被合并的原因。
compose provider 不提供的功能
- 单个 compose 文件内的跨网络 L4 路由。 provider 将每个节点放在其网络上,并让服务加入
x-aggrega-networks-of所指定的网络,但它自身不在网络之间进行任何路由。网络 A 中的服务若要通过 docker-compose 默认 DNS 以外的任何方式访问网络 B 中的服务,需要使用compose-bridgeFeature,其 FeatureRecipe 会写出网关和重写规则。 - 跨 compose 文件的路由。 求值为不同组装路径的边界会生成不同的
docker-compose.yaml文件;compose 运行时将它们视为相互独立的项目,compose-bridgeFeature 也会让两个文件之间的连接保持原样。跨文件通信由运维人员负责(发布主机端口、共享外部网络,或通过共享的directory:将这些边界合并到同一路径上)。 - 从 attachment 获取环境变量的值。 Compose 没有对应的原语,因此带有
as: env的 Workloadattachments条目会输出值为空的变量名,而不是运行时解析的引用。这个占位是有意为之:一个存在但为空的变量对调试容器的人是可见的,而缺失的变量则什么也看不到。构建会明确指出这一点,而不是留待别人发现:每个这样的条目都会引发一条unsupported-field警告,以条目编写时的坐标(containers.<name>.attachments.<KEY>或initContainers[<i>].attachments.<KEY>)指明该条目,让作者知道哪个变量为空、属于哪个容器。该警告仅供参考:构建会成功,渲染出的文件与没有该警告时逐字节相同。--no-unsupported-field-warnings可关闭这类警告。带有as: file的attachments条目不受影响:compose 会以 bind mount 方式挂载它,且不会引发警告。 - Swarm 模式的
deploy:内容。deploy:下的副本数、放置约束和更新策略属于 swarm 模式的功能,而 compose provider 只面向单主机 compose,因此不会输出其中任何一项。它会输出deploy.resources,即容器的resources所映射到的预留和限制,docker compose 在非 swarm 模式下也会遵循它们(参见容器资源)。 - 由
uses边生成的、以健康状态为条件的depends_on。 由uses边推导出的依赖以无条件形式输出,采用service_started语义;它不以目标的 healthcheck 报告健康为条件。这取决于uses边的含义,而不是因为 provider 无法生成这种形式:等待 init 容器时会输出长格式,而在目标声明了 healthcheck 时,部署波次确实会以目标的健康状态为条件。
编写示例
一个包含两个服务的 compose 部署,其中有一条由 uses 推导出的 depends_on 边:
# release.yaml fragmentspec: boundaries: production: annotations: aggrega.ai/namespace: prod components: api: {} db: {}# api RecipeapiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: api version: 1.0.0spec: capability: compose implements: example/compute/api:1.0.0 workload: | apiVersion: aggrega.ai/v1beta1 kind: Workload containers: main: image: api:1.0 ports: http: 8080 health: live: http: /healthz services: public: type: NodePort ports: http: 8080# Aggregate fragment — api uses db, on a socket api's Component declaresapiVersion: aggrega.ai/v1beta1kind: Aggregatespec: components: api: type: example/compute/api:1.0.0 uses: backend: db: target: db db: type: example/datastore/db:1.0.0compose provider 在边界的求值路径上生成一个 docker-compose.yaml(默认为 dist/boundaries/production/compose/docker-compose.yaml,因为边界的 directory: 默认为 dist/boundaries/<name>,subDirectory: 默认为 {{ .capability }}),其中包含:
services.api(主 api 服务,网络prod,端口8080:8080,通过curl进行健康检查,depends_on: [db])services.db(主 db 服务,网络prod)networks.prod(该边界的 docker 网络)
相关参考
- Workload 实体 — 由平台拥有、由 compose provider 转换的 Workload 类型。
- Provider 架构 — provider 如何融入编译流水线。
- 知名注解 — compose provider 使用的
aggrega.ai/*注解。 - Provider 参考索引 — 每个标准库 provider 生成什么,以及哪个页面回答哪个问题。
- Recipe 输入组合 — 权威的 Provider 能力矩阵。