Compose Provider
The compose provider renders Aggrega Recipes into a Docker Compose file. The provider assembles per-(path, provider): every boundary’s compose contributors are routed to the assembler keyed on the boundary’s evaluated directory: joined with the per-component subDirectory:, and that assembler emits one docker-compose.yaml containing every contributor at that path. Two sibling boundaries that evaluate to the same path collapse into a single merged compose file — the canonical example is a parent boundary plus two child boundaries with directory: "{{ .parent_boundary.directory }}" (the compose-bridge pattern).
Supported input kinds
The compose provider accepts all three Recipe input kinds:
- Sourced mode. A Recipe with
source:pointing at an existing compose file plusvaluesMapping:producing an overlay document. The base compose file is loaded, the overlay is evaluated, and the two are deep-merged per docker-compose’s native overlay semantics. - Workload mode. A Recipe with
workload:(inline or$import:-loaded) declares aWorkloaddocument. The provider synthesizes one or more compose services from the Workload spec. - Artifacts mode. A Recipe’s
artifacts:entries evaluate to compose fragments, which merge into the assembled file under the rules in Artifacts-emitted compose fragments. Artifacts may ride alongside a source or a Workload, and they may also be a Recipe’s whole output: a Recipe declaringartifacts:and neithersource:norworkload:renders here, contributing whatever its fragments declare. That is how a component that is only resources — a shared network and volume set, a seeded config — reaches a compose deployment without a placeholder Workload standing in for compute it does not have.
The three kinds compose by addition, and a Recipe declaring none of them is refused when it loads. A valuesMapping: with no source: beside it is refused when the Recipe loads too, whichever provider it names: there is nothing for the overlay to be applied to, and the diagnostic asks you to declare the source: pointer or drop the valuesMapping:.
Workload feature mapping
When a Recipe declares workload:, the provider translates the platform-owned Workload shape into compose primitives. The mapping is intentionally narrow — Compose’s surface is shape-poorer than Kubernetes, and several Workload features degrade to the closest compose equivalent with documented loss.
Container fields
| Workload field | Compose field |
|---|---|
image | image |
imagePullPolicy: Always / IfNotPresent / Never | pull_policy: always / if_not_present / never |
command | entrypoint (list form) — it overrides the image’s entry point, which is the compose key that does that |
args | command (list form) — it supplies the arguments the entry point receives, which is what compose’s command overrides |
variables | environment (map form) |
attachments[as: env] | environment entry with an empty value, and a warning naming the entry (see What the compose provider does not deliver) |
attachments[as: file] | volumes long-form bind-mount, read-only |
volumeMounts | the compose primitive the referenced Volume variant maps to — a volumes long-form entry, a service-level tmpfs: entry, or a service-level configs: reference (see Volumes) |
ports | implicit (compose containers expose ports the image listens on) |
restartPolicy: Always | restart: unless-stopped |
restartPolicy: OnFailure | restart: on-failure |
restartPolicy: Never | restart: "no" |
variables and attachments[as: env] land in the one environment map, the attachment entries first and the variables after them, each in the order it is authored — the order the helm provider writes, so one Workload renders one environment sequence on every target. Compose expands no $(NAME) reference between a service’s environment entries, so on compose that order carries no runtime meaning. Because the map holds each name once, a container that gives one name both as a variables entry and as an attachments entry delivered as: env halts the build rather than keeping one of the two values (see A container gives one environment variable two values).
Container resources
A container’s resources reach compose’s deploy.resources block, which docker compose honours in non-swarm mode. Kubernetes requests express a guaranteed minimum, so they become compose reservations; limits express a hard cap, so they stay limits.
| Workload field | Compose field | Translation |
|---|---|---|
resources.requests.cpu | deploy.resources.reservations.cpus | A decimal core count. A core count written as a bare number (2, 0.5) is emitted as written; any other form is converted from its value (500m → 0.5, 1500m → 1.5, 5n → 0.000000005, 1e1 → 10) |
resources.limits.cpu | deploy.resources.limits.cpus | Same conversion |
resources.requests.memory | deploy.resources.reservations.memory | An exact byte count, converted from the value in whichever form it is written — 8Gi becomes 8589934592, 1.5Gi becomes 1610612736, 1e3 becomes 1000 |
resources.limits.memory | deploy.resources.limits.memory | Same conversion |
nvidia.com/gpu, under resources.limits, resources.requests or both | deploy.resources.reservations.devices | One NVIDIA device entry on the container’s service — driver: nvidia, count: the GPU count, capabilities: [gpu]. The count is the limit’s where a limit is written — the count Kubernetes schedules for an extended resource — and the request’s otherwise. A count of 0 asks for no GPU and writes no entry |
any other extended resource key — amd.com/gpu and every other <domain>/<name> | — | No single-host compose analog. The key is dropped and the build raises an unsupported-field warning naming it, one per distinct key however many of requests and limits carried it. Its value is not emitted, so it is not checked |
Each cpu, memory and nvidia.com/gpu value is read as a quantity, in the form set out in Workload → Resource quantities, on the Workload as the Recipe’s templates evaluated it. Two things halt the build with a TRANSLATION_ERROR, and the error says which of the two it met, naming the container’s path, whether the value is a request or a limit, the resource and the value:
- a value that is not a quantity —
lots,1.5 cores, or theman empty template leaves in"{{ .infra.cpu }}m"; - a quantity compose cannot represent exactly — a negative amount; a memory amount that is not a whole number of bytes (
1500m,4u) or is larger than 9223372036854775807 bytes (8Ei); a cpu amount finer than nine decimal places of a core, the finest precision a Kubernetes quantity itself keeps, or larger than 9223372036.854775807 cores; a GPU count that is not a whole number of devices (0.5,500m).
A container whose nvidia.com/gpu request and limit ask for different counts halts the same way, naming both paths: compose reserves one count for a service, so the translation would otherwise have to choose one. Write the same count in both, or only the limit.
Nothing is rounded, and no value is emitted that means something else.
A GPU request reserves NVIDIA GPUs. A Workload container asking for nvidia.com/gpu: "1" renders a service carrying this reservation, beside any cpus and memory its requests reserve:
deploy: resources: reservations: devices: - driver: nvidia count: 1 capabilities: - gpuDocker Compose hands the reserved GPUs to the container when the Docker host has that many NVIDIA GPUs and is set up to give them to containers; the build cannot see the host, so a file reserving GPUs assembles the same way wherever it will run. The entry always states its count, because Compose reads a device entry with no count as every GPU on the host. Only the NVIDIA key is translated: amd.com/gpu and every other vendor’s key keep the dropped-key row’s warning. The runtimeClassName row in Pod-level fields is unchanged — compose has no runtime-class analog, so a Workload naming a GPU-enabled runtime is told the runtime was omitted, while its GPU count is reserved.
Probes
A Workload’s three probe slots (live, ready, startup) collapse to compose’s single healthcheck per service, with priority live > ready > startup (the most-canonical-liveness signal wins). Where that collapse discards a slot the author declared, the build raises an unsupported-field warning naming the slot that was translated and the slots that were dropped, so intent reaching no part of the output is reported rather than lost. A health block declaring one slot translates without loss and raises nothing, unless the slot sets successThreshold: a compose healthcheck has no field for it, so an authored value — 1 included — is omitted with an unsupported-field warning naming it (containers.<name>.health.<slot>.successThreshold), and the rest of the slot translates as the table below shows.
| Workload probe shape | 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, ...] |
The HTTP form requires the container to declare at least one named port; the synthesizer picks the alphabetically-first port name and uses its number to build the curl URL. Containers with no ports declared cannot use HTTP probes — the compiler halts with a TRANSLATION_ERROR naming the offending probe.
Probe timeout fields map to compose-style duration strings:
| Workload field | Compose healthcheck field |
|---|---|
periodSeconds | interval: <n>s |
timeoutSeconds | timeout: <n>s |
failureThreshold | retries: <n> |
initialDelaySeconds | start_period: <n>s |
Volumes
Compose has a config primitive of its own, which is what a configmap volume translates to. It has no Kubernetes-equivalent for Secret or per-replica volume templates, so those variants degrade to the closest compose primitive:
| Workload volume variant | Compose translation | Loss notes |
|---|---|---|
ephemeral | service-level tmpfs: list entry | sizeLimit is not preserved (compose tmpfs short-form lacks size). An authored sizeLimit raises an unsupported-field warning naming it at its authored coordinate (volumes.<name>.ephemeral.sizeLimit), whether or not a container mounts the volume; leaving the field out raises nothing |
configmap | service-level configs: reference naming the configmap, mounted at the volume mount’s path | 🔴 The mount path is the path of a single file, not of a directory. Compose writes the config’s content to exactly the target path, where a Kubernetes target mounting a ConfigMap at a path produces a directory holding one file per key. So the same authored path: denotes a file here and a directory there: point a configmap volume’s mount at the filename the container should read (/seed/config.json), not at the directory that would contain it, and a Recipe authored for both targets carries a different path per target. Nothing in the build can catch a path written for the other target’s shape — the path is an opaque string the compiler pipes through, and the emitted output is valid either way. The reference is by name, exactly as a Kubernetes target references a ConfigMap resource — nothing reads the config’s content. The matching top-level configs: entry comes from the Recipe’s artifacts: input, whose compose fragment declares it with inline content:; a reference with no such entry halts the build (see Artifacts-emitted compose fragments). A configs: reference carries the config name and the mount path and nothing else, so the mount’s readOnly has no separate expression |
secret | volumes long-form bind-mount, read-only | A secret volume deliberately does not follow the configmap translation: an inline configs: entry would write the secret’s value into the emitted compose file in plaintext, and the compiler never resolves a secret into plaintext — a secret stays a pointer through every stage of the build. The bind source is the secret’s source name, resolved as a path the operator makes reachable on the compose host independently of the build |
persistent | named volume + top-level volumes: { <volume-name>: {} } declaration, named per How a volume name is derived | Storage class, access modes and size are not preserved (compose has no equivalent shape). An authored class or accessModes raises an unsupported-field warning naming it at its authored coordinate (volumes.<name>.persistent.class, volumes.<name>.persistent.accessModes); leaving either out raises nothing. The required size raises no warning — see below |
persistentTemplate | named volume + top-level declaration, named the same way (same as persistent) | Companion of form: stateful; compose has no per-replica volume templating primitive, so the per-replica behaviour is lost, and an unsupported-field warning says the volume became one volume every replica shares. Storage class, access modes and size are not preserved, exactly as for persistent: an authored class or accessModes raises an unsupported-field warning at volumes.<name>.persistentTemplate.class or volumes.<name>.persistentTemplate.accessModes, and the required size raises none |
A mount’s subPath mounts part of a volume where compose has a form for it. A volumeMounts entry naming a persistent or persistentTemplate volume with subPath becomes a long-form volumes entry carrying volume.subpath, so the mount sees the named directory or file inside the volume rather than its root, and two mounts of one volume with two different subPath values see two different parts of it:
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: uploadsA mount written without subPath carries no volume: block. A subPath on a mount of an ephemeral, configmap or secret volume halts the build with a TRANSLATION_ERROR naming the component, the container, the mount’s authored path (containers.<name>.volumeMounts[<i>]), the volume and the subPath: those variants reach compose as a tmpfs entry, a configs: reference and a bind mount, none of which mounts part of what it delivers, so the mount would otherwise see the whole volume. Remove subPath from such a mount, or mount a persistent volume. Docker Compose reads volume.subpath from release 2.26.0, on Docker Engine 26.0 or later; the build cannot see the host that will run the file, so a file carrying one assembles the same way wherever it will run.
A volume says which variant it is and nothing more. A secret volume has exactly one translation — the read-only bind mount above — and a volume carries no as: field to select another. Delivering what a slot published as an environment variable is a container attachments entry (as: env) rather than a volume; what compose does with one is under What the compose provider does not deliver.
Three variants carry a storage size, and only one of them warns that the size was dropped. The difference is whether you had a choice. An ephemeral volume’s sizeLimit is optional, so writing it was a decision, and the warning tells you the value shapes nothing on this target and can be removed — it is advisory and out-of-band, the emitted file is byte-for-byte what it would be without it, and --no-unsupported-field-warnings silences it along with the rest of the class. A persistent or persistentTemplate volume’s size is required, so no version of the document leaves it out: a per-build warning there would fire on every stateful workload while naming nothing you could change, so the difference is taught here instead of reported on each build. Targeting compose, a persistent volume’s size, class, and accessModes shape nothing in the emitted file — what you get is a plain named volume, sized and backed by whatever the compose host’s volume driver does by default. class and accessModes are optional, so each one you write is reported the way an ephemeral sizeLimit is: one unsupported-field warning per field, advisory and out-of-band, silenced by the same flag. Size the underlying storage on the host, or on the Kubernetes target where the fields do reach the output.
A volume that no container mounts raises an unsupported-field warning naming it at its authored coordinate (volumes.<name>), because what reaches the emitted file then differs sharply by variant. persistent and persistentTemplate still produce their top-level declaration, so the volume is created and nothing uses it. ephemeral, configmap, and secret have no expression outside the mount itself — each translates to something written at the mount path, a tmpfs entry, a configs reference, or a bind-mount respectively — so with nothing mounting one, the volume you declared leaves no trace in the output at all. That second case is the reason the warning exists: without it, a configmap volume whose mount you forgot would simply be absent, with nothing in the emitted file to notice. Every container of the workload counts as a mounter, init containers included, so a volume mounted only by an init container is wired and raises nothing. The warning is advisory and out-of-band — the emitted file is byte-for-byte what it would be without it — and --no-unsupported-field-warnings silences the class.
How a volume name is derived
A persistent or persistentTemplate volume becomes a compose named volume: one top-level volumes: entry, referenced by every container that mounts it. A compose volume is shared storage, and the top-level volumes: block unions its entries by name — so two authored volumes arriving at one name become one volume both containers write into, with nothing in the emitted file to show that two were meant. The name is therefore built from the two identities that together say which volume it is: the <component> the volume belongs to, and the name the Workload gave the volume under volumes:.
A compose volume name accepts a narrower set of characters than either identity may carry: letters, digits, dots, underscores and hyphens. Rather than substitute for a character compose does not accept, the derivation writes it out, so two volumes that differ at all arrive at two names — and an assembled name can be read back into the two identities it was built from.
- A letter, a digit, a dot and an underscore are carried through exactly as authored.
- A hyphen is kept as authored wherever the character after it is carried through directly and is not a lowercase
z. A hyphen followed by a lowercasezopens an escape, so an authored one in that position is itself written out —api-zonebecomesapi-zhzone, which is what lets any name be read back without guessing. A hyphen with nothing after it is written out for the same reason, sodb-givesdb-zh. - Every other character is written as
-zfollowed by a letter naming it:sfor a path separator,hfor a hyphen the rule above does not keep. Anything else — a space and a non-ASCII letter included — is written asxand the character’s six-digit hexadecimal code point, and a byte that begins no character at all asband its own two-digit value, so a name that is not valid text is still written out distinctly rather than collapsed. - An empty value is written
-ze, which no non-empty value can produce. - The two identities are joined by
--. A single encoded identity never contains that pair, so the joined name says unambiguously where one identity ends and the other begins.
So the component store with a volume the Workload calls data gives the volume name store--data, and db-server with data gives db-server--data. Identical input always produces the identical name.
The doubled join is what makes the pair unambiguous, and a one-character join cannot be. Either identity may itself carry a hyphen, so a single-hyphen join leaves a name that divides in more than one place: db with a volume called data-cache and db-data with a volume called cache would both spell db-data-cache, and since the top-level block unions by name the two components would share one volume with nothing in the emitted file to show it. An encoded identity never contains a pair of hyphens, so the doubled join admits no second reading: the two reach db--data-cache and db-data--cache.
Changing either identity renames the compose volume, and compose does not rename a volume in place. The volume is created afresh under the new name while the old one stays behind with the data in it, so the container comes up against empty storage and the contents sit in a volume nothing mounts. Rename either identity only as a replacement to be planned — backed up, copied across, or scheduled — rather than as a change to roll out.
Controller form
The Workload’s form selects an abstract controller shape (see entities/workload.md). Compose renders stateless and stateful (and the empty default, treated as stateless) as long-running services; the stateful form adds the named volume for a persistentTemplate companion. The daemon, scheduled, and task forms have no clean single-host compose mapping, so a Workload declaring one of them targeting a compose boundary halts with a TRANSLATION_ERROR naming the form and the supported set — compose does not degrade an unsupported form into a plain service that misrepresents the intent. A reference Workload declares an external endpoint and no containers, so compose emits no service for it.
Because no service is emitted for a reference Workload, nothing reads the delivery pipe of the component it realizes: a credential attached to that component — delivered on its pipe by dotenv-secret, or by an attachment’s own inject: block — would reach no emitted file. Every standard-library Compose Recipe that realizes an external service this way, and whose Component declares a credential slot, therefore refuses a credential filling that slot: the build halts naming the slot and the component, rather than succeeding with the credential absent. On compose, a credential for an external service is attached to the component that calls it, under the environment variable that component reads. That refusal is each Recipe’s own assertion, and it runs before this provider renders anything. This provider also refuses at the node itself, whichever catalog the Recipe comes from: an attachment on a reference node whose material is declared sensitive — its Feature declares a field sensitive: true, or the slot it fills does — halts the build with TRANSLATION_ERROR (E0288), naming the node and every such attachment, whether or not any slot declares the name it is attached under. An attachment carrying nothing declared sensitive is not refused here. Those Components declare their credential slots optional, so on compose a slot left empty halts nothing. Where the Kubernetes realization needs the credential — the helm Recipes of twilio, vonage, telnyx, bland, letta, retell and vapi — that Recipe requires the slot instead, and halts the build naming it when it is empty.
Service exposure
A Workload services entry’s type field decides whether compose publishes ports, and on which host address:
| Workload service type | Compose behaviour |
|---|---|
ClusterIP | No ports: publishing — the service is reachable only on the compose network |
NodePort | ports: [<host>:<container>] publishing, on every host interface |
LoadBalancer | ports: [<host>:<container>] publishing, on every host interface (compose has no managed-loadbalancer equivalent; the host-port publish is the closest analogue) |
Loopback | ports: [127.0.0.1:<host>:<container>] publishing — reachable from the host itself and from nowhere else |
Headless | No ports: publishing |
Which number goes on which side. A service entry names a container port and gives it a number, the way a Kubernetes Service maps its port onto a targetPort. The entry’s number is the <host> side of the published pair, and the number of the container port the name resolves to is the <container> side. So a container declaring http: 8080 and a NodePort entry writing http: 8081 publish 8081:8080: the host’s port 8081 reaches the port the container serves on. An entry carrying the container port’s own number publishes that number on both sides, 8080:8080. A peer on the compose network reaches the service by its service name on the container’s port, never on the published one — the published port belongs to the host — so a Recipe publishing a port of its own choosing still hands its consumers the container’s port.
A Loopback entry binds the IPv4 loopback address only. The IPv6 loopback address ::1 is not bound: compose’s port syntax carries one host address per entry, and a host whose loopback interface carries no IPv6 address could not bind it, so the service would not start there. Clients on the host reach the port at 127.0.0.1.
When multiple services on a single Workload publish the same container port under the same number, it is published once, and the widest reach wins: any NodePort or LoadBalancer reference publishes it on every host interface, even where a Loopback entry names it too and whichever entry is declared first; a port that only Loopback entries name is published on 127.0.0.1. One container port published under two numbers is published twice, once under each. Published ports are listed in container-port order, and by published port within one container port.
Port transport. A published entry carries the transport declared on the container port it names, as compose’s /protocol suffix: 53:53/udp, or 127.0.0.1:53:53/udp for a Loopback entry. A port that declares no transport publishes as <host>:<container> with no suffix, leaving compose’s own default in force. Compose spells a published port’s transport as tcp or udp; a port declaring SCTP has no compose spelling, so it halts with a TRANSLATION_ERROR rather than publishing a port that would carry a different transport. A container port that no service publishes reaches no part of the compose file at all, so a transport declared on such a port has nothing to be spelled onto and does not halt.
Multi-container Workloads
A Workload with multiple containers becomes one main service plus one sidecar service per non-main container. The main container is the one named main (when present) or the first container in declaration order. Sidecars share the main service’s network namespace via network_mode: "service:<main>" — the closest compose primitive to a Kubernetes pod’s shared-network model.
How a sidecar or init service is named
The main service carries the <component> name as it is. Every other service the Workload produces — one per sidecar, and one per init container — is named from two identities together: the <component>, and the container’s name, which is its key under containers: for a sidecar and its name for an init container, or the positional init-<index> an unnamed init entry takes. The assembled services: block holds one service per name, so the name is built such that two containers differing in either identity always arrive at two names.
Each identity is written out exactly as the two parts of a volume name are — a letter, a digit, a dot and an underscore as authored, a hyphen kept where the rules there keep it, and every other character written out — and the two are joined by --, which no written-out identity contains. So the component api with a sidecar logger runs it as api--logger, the init container import-seed of platform runs as platform--import-seed, and an unnamed first init entry of api runs as api--init-0. A container name carrying a character a service name does not admit is written out rather than emitted as authored: an init container named warm cache/x of api runs as api--warm-zx000020cache-zsx.
The doubled join keeps two components’ containers apart. api with a container warm-cache and api-warm with a container cache run as api--warm-cache and api-warm--cache, two services, where a one-hyphen join would spell both api-warm-cache.
Sidecars and init containers share this one naming, so a containers entry and an initContainers entry carrying the same name reach the same service name, and the build halts on the pair rather than run one container in place of the other (see Init containers).
A component’s own service does not take one of these names. The main service is named after the component, and a doubled hyphen written in a component’s name is itself written out there — a component named api--prep runs as api-zh-prep — so it never carries the -- join. Where services of two different components still meet on a name in one compose file — through a service an artifact names for itself, say — the build halts naming both, as Per-(path, provider) output describes.
Changing the component’s name or the container’s name renames the service. Compose treats a service under a new name as a new service, so its container is created afresh under the new name.
Pod-level fields
Pod-level Workload fields apply to the main service only — sidecars share the main service’s network namespace — and an init service follows the same rule. The one exception is the pod’s user: a pod runs every one of its containers as podSecurityContext.runAsUser and runAsGroup, so they reach every service the Workload produces, sidecar and init services included.
Several map onto a compose service field:
| Workload field | Compose field |
|---|---|
podSecurityContext.runAsUser / runAsGroup | user ("1000", or 1000:3000 with a group) on every service of the Workload. A container that sets its own securityContext.runAsUser runs as that user on its own service instead, with its own runAsGroup where it sets one |
terminationGracePeriodSeconds | stop_grace_period: <n>s |
dnsConfig.nameservers / dnsConfig.searches | dns / dns_search |
hostAliases | one extra_hosts entry per hostname, in author order |
hostNetwork: true | network_mode: host |
Running on the node’s network. A workload declaring hostNetwork: true gets network_mode: host on its own service, and that service is then left off the boundary network rather than being attached to it: compose refuses a service that declares both networks: and network_mode:, so the two are alternatives rather than additions. The practical consequence is the one host networking always carries — peers no longer reach the service by its compose service name over that network, because it is no longer on it; they reach it on the host’s own addresses, which is what the declaration asked for. Every other service on the boundary is unaffected.
Two shapes compose with it. A sidecar keeps naming the main service (network_mode: "service:<main>"), so it follows the main service onto the host’s network without declaring anything itself — the same way a Kubernetes pod’s containers share one namespace. An init service does not: it joins the boundary network in its own right, because sharing the main service’s namespace would make the main service’s wait on it circular. So a workload with both hostNetwork and initContainers runs its own service on the host’s network while its init services stay on the boundary network, which is narrower than the pod shape it models; an unsupported-field warning names that difference rather than leaving it to be found at run time.
The rest have no single-host equivalent. None is dropped in silence: each authored one raises an unsupported-field warning naming the field, so an author learns which setting the target could not honour rather than discovering it from the running stack.
| Workload field | Why compose cannot honour it |
|---|---|
scheduling | Placement — nodeSelector, affinity, tolerations, topologySpreadConstraints — presumes a scheduler choosing among nodes. Compose runs on one host |
replicas | Compose’s own replica count lives under deploy: and is a swarm-mode feature |
runtimeClassName | Selecting an alternative container runtime — a GPU-enabled one, for example — has no compose expression |
priorityClassName | Preemption ordering presumes a scheduler |
serviceAccount | Workload identity is a cluster concept |
imagePullSecrets | Registry credentials on a compose host are the host’s own login state, not a field of the file |
dnsPolicy, dnsConfig.options | Compose exposes dns and dns_search and nothing finer |
podSecurityContext.fsGroup, podSecurityContext.supplementalGroups | user carries one user and one group; the group a pod’s volumes are owned by, and further groups for its processes, are not translated |
podSecurityContext.runAsGroup, where the pod sets no runAsUser, or where a container — main, sidecar or init — sets its own runAsUser and no runAsGroup | user names a group only beside a user, and a container’s own user takes the place of the pod’s, so the pod’s group reaches no service written that way |
Container-level securityContext translates partially: readOnlyRootFilesystem → read_only, capabilities.add / drop → cap_add / cap_drop, runAsUser / runAsGroup → user. runAsNonRoot and allowPrivilegeEscalation have no compose expression and raise the same unsupported-field warning, and so does a container runAsGroup written without a runAsUser beside it: the service then runs as the pod’s user where the pod sets one, without that group.
Every warning in this section is advisory and out-of-band: the build succeeds, and the emitted file is byte-for-byte what it would be without it. --no-unsupported-field-warnings silences the class.
Init containers
A Workload’s initContainers entries become services of their own, using compose’s run-to-completion idiom. Each entry adds one service, named from the <component> and the entry’s name by the same naming sidecars use — <component>--<container-name> for an ordinary name; an entry that omits name takes the positional init-<index> name the Workload reference documents, and is named from that.
The ordering the authoring contract promises — the init containers run to completion in the order they are written, and every other container starts only after all of them have finished — is expressed with depends_on’s long form:
- Each init service after the first waits on its predecessor with
condition: service_completed_successfully. - The main service, and every sidecar service, waits on the last init service with the same condition. Waiting on the last one is sufficient because the init services form a chain.
- Each init service carries
restart: "no". An init service runs once; a service that came back up would never reach the completed state its dependents are waiting on, so arestartPolicyauthored on an init container does not change this.
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"An init container is translated exactly as any other container: its image (including the registry rewrite an aggrega.ai/image-registry annotation applies), command, args, variables, attachments, volumeMounts, and securityContext all reach the init service. That is what makes the configuration an init container carries — most often a file it mounts and writes into a volume the main container also mounts — survive onto the compose target rather than being lost with the container. A shape compose cannot express fails the same way for an init container as for an ordinary one: a declared lifecycle or envFrom halts with a TRANSLATION_ERROR naming the init container it came from.
Two differences from the main service follow from an init service being a non-main service:
- Pod-level Workload fields are not applied, the same rule sidecars follow — the pod’s user excepted, which reaches every service as Pod-level fields describes.
- An init service joins its boundary’s network directly rather than sharing the main service’s network namespace the way a sidecar does. It has to: the main service waits on the init service, and sharing a namespace is itself a dependency on the main service, which would close the wait into a cycle compose refuses to start. An init container therefore reaches other services on the boundary network by service name, but it does not share the main service’s
localhost.
Init services and sidecar services share one name namespace, because one naming names both, so an initContainers entry and a containers entry may not carry the same name. When they do, the compiler halts with a TRANSLATION_ERROR naming the node, the container name, and the service name both wanted, rather than letting one service quietly replace the other.
Emitting the completion condition raises no minimum Compose version. condition and its values belong to the base Compose Specification — unlike the restart and required fields alongside them in the same long-form block, which the specification ties to particular Compose releases. Each minimum version the compose provider’s output asks for comes with the construct that needs it: ≥ 2.23.1 for inline configs.content, ≥ 2.26.0 for a mount’s subPath (see Volumes), and 2.38 for models. The first reaches any compose output carrying a config with inline content:, which is how the file behind a configmap volume and the config behind a bridged cross-network edge both arrive — not one authoring path.
Which network a service joins
Every service joins a Docker network; sidecars inherit it through their network_mode reference to the main service. Which network a node lands on is read from the aggrega.ai/namespace annotation on that node, falling back to the path of the compose file where the node carries no such annotation — the directory the file is written to under the build’s output directory, such as bridge/compose for a boundary whose directory: is bridge. So every node without the annotation in one compose file joins one network named for the file’s path, whichever boundary it sits in: unannotated boundaries that share a compose file share that network, and aggrega.ai/namespace is what separates them. Nodes carrying different annotations land on one network per distinct annotation. How a network name is derived is the name that identity produces.
How a network name is derived
A compose network is shared L3 connectivity, and the top-level networks: block unions its entries by name — so two identities arriving at one name become one network both sets of services sit on, reaching each other by service name, with nothing in the emitted file to show that two networks were meant. The name is therefore built from the identity that says which network it is: the node’s aggrega.ai/namespace annotation, or the path of the compose file where the node carries none.
A compose network name accepts a narrower set of characters than either identity may carry: letters, digits, dots, underscores and hyphens. Rather than substitute for a character compose does not accept, the derivation writes it out, so two identities that differ at all arrive at two networks — and a name can be read back into the identity it was built from.
- A letter, a digit, a dot and an underscore are carried through exactly as authored, in the case they were authored in. So
prodandProdare two networks, not one. - A hyphen is kept as authored wherever the character after it is carried through directly and is not a lowercase
z. A hyphen followed by a lowercasezopens an escape, so an authored one in that position is itself written out —api-zonebecomesapi-zhzone, which is what lets any name be read back without guessing. A hyphen with nothing after it is written out for the same reason, sodb-givesdb-zh. - Every other character is written as
-zfollowed by a letter naming it:sfor a path separator,hfor a hyphen the rule above does not keep. Anything else — a space and a non-ASCII letter included — is written asxand the character’s six-digit hexadecimal code point, and a byte that begins no character at all asband its own two-digit value, so an identity that is not valid text is still written out distinctly rather than collapsed. - An identity that is absent altogether — a node with no
aggrega.ai/namespaceannotation in a compose file with no path — is written-ze, which no identity an author wrote can produce. A network with no identity therefore never shares connectivity with one that has an identity spelled some particular way.
So a namespace of prod gives the network prod, core-net gives core-net, and a compose file at dist/app/compose gives dist-zsapp-zscompose. Identical input always produces the identical name.
A namespace and the path of a compose file are written into the same space. They are two ways of naming the same thing — which network a node is on — so a node whose namespace is app/compose and a node with no namespace in the compose file at app/compose deliberately land on one network, exactly as two boundaries carrying the same aggrega.ai/namespace annotation do. Where you want two nodes apart, give them identities that differ.
Changing a node’s identity renames the compose network, and compose does not rename a network in place. The network is created afresh under the new name and every service on it is recreated to attach to it, while the old network stays behind until something removes it. A network carries no data, so nothing is lost — but the containers on it do restart, and anything holding a connection across the change sees it drop. Change a namespace annotation, or the directory a compose file is written to, as a redeployment to be planned rather than as a value to adjust in place.
When two boundaries collapse into one assembly path (shared directory:), their nodes without an aggrega.ai/namespace annotation share the file’s one network; give each boundary its own aggrega.ai/namespace annotation and the merged docker-compose.yaml declares one top-level networks: entry per annotation. Services from different boundaries within the same compose file can communicate by their service names within compose’s default DNS resolution, subject to compose’s own cross-network reachability rules. Cross-network L4 routing within a single compose file is what the standard library’s compose-bridge Feature enables, as catalog content this provider holds no logic of: attached at the common-ancestor boundary, its FeatureRecipe derives a gateway from the boundary’s uses edges whose two ends are assembled into its own compose file and sit on different networks of it — an aggrega-gw service whose nginx stream config proxies each bridged edge (one server block per edge, on the target’s port with a portBase collision fallback) — and its own injectMapping rewrites each consumer’s host env var to aggrega-gw:<port>, or to aggrega-gw with the port variable rewritten to the listen port where the same connection delivers both. That rewrite replaces the value the consumer’s own connection delivered; if another Feature attached to the consumer delivered the same variable, the build halts naming both rather than replace it. The FeatureRecipe’s valuesMapping writes that config as a mounted compose config — a top-level configs: entry with inline content:, referenced from the gateway and mounted at /etc/nginx/nginx.conf; it is not an operator-mounted concern — and names every bridged endpoint under the gateway’s x-aggrega-networks-of, which this provider resolves into the networks those endpoints are placed on (below). An edge whose two ends are assembled into two compose files is not bridged and keeps the target’s own name; a boundary with nothing to bridge still carries the idle gateway, with no config and no network beyond its own; and a bridge attached at a boundary whose compose file holds no component halts the build rather than write the gateway nowhere. The stream config carries a resolver directive and proxies through a per-edge variable (set $uN <host>; proxy_pass $uN) so each upstream resolves at connection time rather than once at startup — a bare proxy_pass to a not-yet-running target would otherwise fail the gateway at boot. (The $ in those variables is escaped to $$ inside configs.content so Docker Compose’s own $-interpolation leaves a literal $ for nginx.) Inline configs.content requires Docker Compose ≥ 2.23.1. See the compose-bridge pattern.
Joining the networks of other components — x-aggrega-networks-of
A service a fragment writes — a sourced compose file once its overlay is merged in, or an artifacts: body — may join the networks of other components assembled into the same compose file by naming them under the extension key x-aggrega-networks-of: a list of component ids, the ids the Aggregate gives its components, which a boundary-scope FeatureRecipe reads as the keys of .boundary.components and as the source and target of its .boundary edge lists. The provider resolves each id to the network that component is placed on in this file, by the same placement every node receives, and adds those networks to the service, each once and in name order, ahead of the service’s own network, which it still joins. The key itself is left out of the assembled file. The provider reads the ids as references to resolve and nothing about what the service does, so any Recipe or FeatureRecipe may use the key; the compose bridge’s gateway joins the networks of the endpoints it relays between this way.
# 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-zscomposeThree things stop the build with TRANSLATION_ERROR when the file is assembled, each naming the service:
- An id that no component assembled into this file carries — one assembled into another compose file, say. A network belongs to one file, so the message names the id and the file the service is in. Name only components assembled into the same file, or remove the id.
- A value that is not a list of strings. The key takes a list of component ids, even for one id.
- The key on a service that writes
network_mode. Compose does not let a service with anetwork_modejoin networks; remove one of the two.
depends_on inference
The compose provider derives depends_on automatically from the IR’s uses edges. For each edge whose source and target both contribute services to the merged compose file, the provider adds depends_on: [<target>] to the source service.
The dependency lands on the source component’s own service, and on no other service that component contributes. A component that also declares init containers contributes one run-to-completion service per entry, and none of those receives the edge-derived dependency — an edge names the component, and an init service carries a name of its own. So an init container that has to reach the edge’s target, such as a schema migration against a database the component uses, carries no ordering against that target and may run before it is reachable, while the component’s own service waits both for the init chain to complete and for the target to have started.
Edge-derived entries are emitted ungated: they have service_started semantics regardless of whether the target declares a healthcheck. Gating them on the target’s health — which would let the compose runtime block startup until the target’s healthcheck reports healthy — is expressible, and a uses edge does not ask for it. A wave naming the same pair is the one thing that changes the condition on an edge-derived entry, and it does so because the wave asks for it rather than because the edge does.
Edge-derived entries are emitted in alphabetical target order for output stability. Edges whose source or target are served by a different provider (helm or helm-chart) are skipped — depends_on only applies within the compose-served subset of the Release.
A service’s depends_on emits in one of compose’s two forms, never a mix, because compose requires a condition on every entry of the long form:
- Short-form list (
depends_on: [<service-name>]) when no entry on that service carries a condition. That is every service whose only dependencies come fromusesedges. - Long-form mapping when any entry carries one — which happens when the service also waits on an init container, or when a deployment wave orders it. There, the edge-derived entries emit the explicit
condition: service_started, which the Compose Specification defines as the short form’s equivalent, so their meaning is unchanged.
Within a service the sources keep their own order and do not interleave: the init-chain wait, whose order is the order the author wrote the list in, is emitted first, then the alphabetically-ordered edge-derived entries, then the alphabetically-ordered wave-derived ones.
Deployment wave ordering
A Release boundary’s syncWave: value orders the services of the compose file that boundary renders into. Every component in the boundary inherits the boundary’s wave, and where several boundaries share one directory: — so their contributions collapse into a single docker-compose.yaml — the merged file holds more than one wave and the provider expresses the ordering between them as depends_on.
Each service waits on every service of the immediately-preceding wave that has any services, and on no earlier wave than that. Compose resolves the rest transitively: a service in wave 2 waits on wave 1, which waits on wave 0, so the whole sequence is ordered while each service’s own list stays the size of one wave rather than of the whole file. Waves need not be contiguous, and negative values are ordinary — -1 is a common choice for a migration that runs before everything else.
The condition depends on what the target can satisfy. A wave means the earlier group is up before the later one starts, which is readiness rather than process launch, so:
- where the target service declares a
healthcheck, the wait iscondition: service_healthy; - where it does not, the wait is
condition: service_started, because a service with no healthcheck can never report healthy and a health-gated wait on it would never be satisfied — the file would never come up.
The weaker condition is visible in the emitted file beside the stronger one, and the build additionally names each such service in a warning, so an author who expected readiness ordering learns which part of the wave they declared arrives as start ordering only. The warning is advisory: the build succeeds and the rendered bytes are exactly what they would be without it. Adding a health: block to that container is what upgrades the wait. --no-unsupported-field-warnings silences the class.
The wave is still recorded as a label. Ordering is added beside the aggrega.ai/sync-wave label, not in place of it: the label is where a reader inspecting the emitted file sees which wave a service came from, which the depends_on entries do not state.
Where a wave and a uses edge name the same pair, one entry carries both. Compose accepts one entry per dependency, so a service that both uses a target and sits a wave after it emits a single entry gated on the wave’s condition — the wave’s requirement is the stronger of the two and it is the one expressed.
A boundary whose components all sit in one wave emits nothing from this. So does a Release that declares no syncWave at all: every contributor carries the field’s default of 0, the merged file holds a single wave, and the output is exactly what it would be if the provider expressed no wave ordering.
Ordering across two compose files is not expressible, and it is not approximated. depends_on names a service inside the same file, and boundaries that evaluate to distinct assembly paths produce distinct docker-compose.yaml files that the compose runtime treats as independent projects. So a wave orders every service in the file it renders into and nothing outside it. Sequencing two compose projects is the operator’s concern, the same way cross-file routing is; declaring a shared directory: is what brings two boundaries into one file, and it is an output-shape decision to take for its own reasons rather than to obtain ordering.
A uses edge pointing at a later wave is emitted as written, and reported. The emitted depends_on reflects what was declared — both the uses edges and the waves. An edge whose consumer sits in an earlier wave than the target it uses states the opposite of what the waves state: the edge makes the consumer wait for the target, while the waves make the target wait, through every wave between them, for the consumer. The merged file expresses both, which is a circular dependency set Docker Compose refuses to start. The build names each such edge in a warning stating both services and both waves, so the cycle surfaces when you build rather than at docker compose up. The warning is advisory — the build succeeds and the rendered bytes are exactly what they would be without it — and --no-unsupported-field-warnings does not silence it, because nothing was dropped: the two declarations are each expressed, and together they cannot start. It covers the direct pair only: it names the two services one edge connects rather than tracing the whole cycle. Any cycle built from uses edges and waves together passes through at least one such edge, so it is always reported; a cycle formed by uses edges alone, with no wave involved, and one closed by a depends_on entry written in a compose file the Recipe supplies, are emitted as written and not reported. Keep the edge direction and the wave order consistent: place the consumer in the target’s wave or a later one, or the target in the consumer’s wave or an earlier one.
# 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 does not name migrator: the ordering reaches the immediately-preceding wave and compose chains the rest through store.
Sourced mode
The compose provider’s source: names a docker-compose YAML file that the provider can read and parse, and it accepts both of the shapes the source: field takes: a bare filesystem path string, and a structured object whose url: carries the location. Wherever that location is a filesystem path, it is anchored to the directory holding the recipe.yaml that declares it, not to the directory the build is invoked from, and it must stay inside that directory: one that climbs out of it, or an absolute one, is refused, because every file a publication of the Recipe carries is taken from its directory — see entities/recipe.md “Content paths stay inside the Recipe’s own directory”. The file named this way is published with the Recipe, while a file beside the Recipe that nothing it declares names is not.
spec: capability: compose source: ./docker-compose.base.yaml # filesystem path to the base compose file valuesMapping: | services: api: image: "{{ .values.image }}"In the structured shape, what url: carries decides whether anything is fetched. A fragment published over https:// is fetched and pinned with kind: compose-https-fragment; aggrega pull acquires it and the build reads it from the cache. A url: naming a filesystem path is not fetched — it is read from disk, anchored exactly as the bare-string form above, and aggrega pin records the digest of the file it names in the entity.lock beside the Recipe, which a build then compares before the fragment is read. Vendoring a remote fragment locally and pointing source: at the vendored copy is supported as an alternative to fetching, and is not required. The schema accepts an open structured object.
A Recipe with source: <path-to-compose-file> and valuesMapping: runs the following pipeline:
- The base compose file at
<path>is read and parsed as YAML. - The
valuesMappingtemplate evaluates against the Recipe’s template context. Its output is treated as a compose overlay document — a partial compose file that augments or overrides fields in the base. - Base and overlay are deep-merged using docker-compose’s native overlay semantics.
The deep-merge rules:
- Scalars: overlay wins. When both base and overlay set the same scalar field, the overlay’s value replaces the base’s value.
- Maps: merge recursively. When both base and overlay set the same map field, the merge recurses into the map. Keys present in both follow the same rules; keys present in only one are preserved as-is.
- Lists: replace. When both base and overlay set the same list field, the overlay’s list replaces the base’s list entirely (no element-wise merging or appending). This matches
docker compose -f base.yaml -f overlay.yaml configbehaviour. null: replaces, and stays. A key the overlay sets tonullon a service — one of the service’s own keys, such asuser,commandorhealthcheck, anenvironmententry, a label, or a key directly underhealthcheckordeploy— replaces the base’s value like any scalar and is written into the compose file askey: null; it does not remove the key. Where the provider writes a value of its own into that key, the file carries the provider’s value instead:labels: nullleaves the provenance labels the provider stamps, andnetworks: nullthe network it attaches. Anullwritten anywhere else in the overlay is outside this rule. What anullthen means is Compose’s reading of that attribute — anenvironmententry with no value, for one, takes its value from the environmentdocker composeruns in.
Every label a service’s author wrote stays. A service’s labels: in the base file or the overlay may be written as a map or as Compose’s list of key=value entries, and each label reaches the compose file beside the provenance labels the provider stamps. A list entry is read as Compose reads it: the text before its first = names the label and the text after it is the value, and an entry with no = is a label with an empty value. A number or a true/false value is written as its text, so replicas-hint: 2 reaches the file as replicas-hint: "2", and a label written as null stays null. Where an authored label and a provenance label share a key, the file carries the provenance value. A labels: value that is neither a map nor a list, and a list entry that is not text, stop the build, naming the source file and the service. An artifacts: body’s service labels take the map form: a list there stops the build, naming the artifact and the service.
The merged document then flows into the Release-level merge alongside any synthesized-mode contributions, with the same per-boundary networking and depends_on inference.
Leaving services, volumes and configs out. The overlay cannot remove anything from the base file — an overlay value replaces, it never deletes — so a fetched file that bundles a service the Release must not run is what the omits: entries of a Recipe or a FeatureRecipe are for. This provider honours them in this mode and in no other: a synthesized Workload and an artifacts: body render without them. An entry names one top-level unit of the file by its kind — service, volume or config — and its name, the unit’s key under services:, volumes: or configs:, compared exactly. A compose file has no namespaces, so an entry carrying a namespace, like one naming any other kind, stops the build when the component renders, naming the entry and the kinds this provider accepts; every entry is checked before anything is left out. The entries are matched against the file once the overlay above is merged into it, so a unit the overlay added is left out exactly as one the base declared, and before the provider adds anything of its own, so an entry never names that. A unit an entry names is removed, and a section every unit of which is left out is removed with them; every other unit is written exactly as it would be without the entries. The entries reach the file of the Recipe or FeatureRecipe declaring them and nothing else: what another component or an attached Feature contributes to the same docker-compose.yaml is untouched, a unit with the same key included. The provider reports how many units each entry left out, and an entry that left none out stops the build; see An omits entry left out nothing the source rendered.
A unit left out must not stay named by what remains, because compose refuses a file that names a service, a volume or a config it does not declare. Once the units are removed, every reference the file still makes to one of them stops the build, and the message names each referring service or job, the unit it names and the field the reference is in. A reference is what the Compose Specification defines as one entry of a file naming another:
- a service, named by
depends_onin either form, bylinks(SERVICEorSERVICE:ALIAS), byvolumes_from(SERVICEorSERVICE:MODE), bynetwork_mode,ipc,pidorutsset toservice:<name>, byextendsnaming a service of the same file, or by abuild.additional_contextsvalueservice:<name>; - a volume, named as the source of a
volumes:entry — the short formSOURCE:TARGETwhere the source is a name rather than a path, and the long form oftype: volume; - a config, named by a
configs:entry, in either form.
A service’s pre_start hooks and each top-level jobs: entry are read too, for the references the specification lets each of them carry. Some values only look like references and are not read as one: a volumes_from or network_mode entry opening with container: names a container, external_links names a container this file does not declare, an extends with a file: names a service of another file, and a credential_spec.config may name a config the platform holds rather than the file. Every value is compared as written, so a reference spelled through a ${VARIABLE} is not one this check sees, and a reference to a unit the file never declared is left as it is.
The check reads the declaring Recipe’s or FeatureRecipe’s own file alone, so a reference to a left-out service stops the build even where another contributor at the same assembly path declares a service of that name. To keep the reference, keep the unit. To drop it, change the referring entry through valuesMapping: — a list there replaces the base file’s list, so depends_on: [] clears one — or leave the referring service out as well.
Per-(path, provider) output
Each compose assembly path produces one docker-compose.yaml. Boundaries that evaluate to distinct paths produce distinct compose files; boundaries that share an evaluated path produce one merged compose file containing every contributor at that path. The path is the boundary’s directory: joined with the per-component subDirectory: (which defaults to {{ .capability }} so compose contributors land under a compose/ subfolder by default).
Service-name collisions within a single assembly path halt the build. When two different nodes contribute services with the same instance ID at the same (path, provider) tuple, the compiler halts and the diagnostic names every contributing (boundary, node) tuple in alphabetical order. The author resolves the collision by renaming one of the contributors (typically by adjusting the node’s identifier so the synthesizer produces a different service name), or by routing the contributors to distinct paths via different directory: declarations.
Top-level volumes union within an assembly path, and two contributors may declare one name provided they agree about it. A contributor is a fragment, so two fragments of one component — its own compose file and an artifacts: entry, or two artifacts: entries — are two contributors exactly as two components are. A named volume is one physical volume, so two identical declarations both describe exactly the entry the assembled file ends up with, and it keeps a single entry under that name. A volume the provider derived carries no body, so two of those agree trivially, and they cannot meet in any case (see How a volume name is derived).
An authored volumes: entry is the one to watch, because it may carry a body of its own — a driver, driver_opts, or labels. Where two contributors declare one name with different bodies, the build halts under TRANSLATION_ERROR, naming the volume and every contributing (boundary, node, fragment) tuple. Two authors disagreeing about a single volume have no answer the assembler can choose between: keeping either body discards what the other author wrote, from a build that would otherwise succeed. Resolve it by making the two declarations identical, where both authors meant the same volume, or by renaming one of them, where they meant two. Top-level networks are one per distinct aggrega.ai/namespace annotation, plus one named for the compose file’s path for the nodes carrying none, named per How a network name is derived; two contributing boundaries with the same aggrega.ai/namespace annotation merge to a single network shared by both, as do two unannotated boundaries sharing the file.
Every key a fragment writes is carried or refused
A fragment — a sourced compose file once its overlay is merged in, or an artifacts: body that evaluates to compose YAML — reaches the assembled docker-compose.yaml only through the keys the provider carries, and that set is fixed. Each key a fragment writes is either carried into the assembled file as written or refused by name; none is left out without a word. A fragment is one compose file, so it is one YAML document.
- Carried. At the top level:
services,volumes,configsandmodels. On a service: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_hostsandprofiles. Inside the blocks the provider describes:deploy.resourceswith itslimits(cpus,memory) andreservations(cpus,memory,devices, each device entry’sdriver,count,device_ids,capabilitiesandoptions); ahealthcheck’stest,interval,timeout,retriesandstart_period; a long-formvolumes:entry’stype,source,target,read_onlyandvolume.subpath; a long-formconfigs:entry’ssourceandtarget; a long-formdepends_on:entry’scondition; a top-level volume’sdriver,driver_optsandlabels; a top-level config’scontent. A model’s body and a service’s long-formmodels:entry carry every member, as Models describes. An extension member — a key beginningx-— is carried at the top level and on a service, as Extension members describes. - Refused. Any other key —
stdin_openon a service, a top-levelsecrets:orname:,deploy.replicas, arestart:orrequired:inside a long-formdepends_on:entry, anx-key inside a top-level volume’s body or ahealthcheck— stops the build withTRANSLATION_ERROR, naming every such key, its path in the fragment (services.migrate.stdin_open), the fragment and the component, and it names the two places such a key comes from. One is the fragment itself, and the fix is to remove the key from it. The other is a sourced Recipe that declares novaluesMapping:: the node’s values are then laid over the compose file as they are, so each value key arrives as a top-level key of the fragment, and the fix is to declare avaluesMapping:that places each value under a key the provider carries. A key a YAML merge key (<<: *anchor) brings into a block is judged where it lands, as if written there. A source-rendered fragment is named<component>.compose-fragment.yaml; anartifacts:fragment by the name its Recipe gives it. - Refused as a whole: a network of the fragment’s own. An entry under a fragment’s top-level
networks:stops the build withTRANSLATION_ERRORwhatever its body holds — an empty entry, adriver, anything else — naming the entry (networks.back), the fragment and the component, because the assembled file holds only the networks the provider derives (see Which network a service joins). Remove the entry: a service joins its own component’s network with nothing declared, theaggrega.ai/namespaceannotation chooses which network a component joins, a service names the components whose networks it also joins underx-aggrega-networks-of, and thecompose-bridgeFeature routes between services on different networks. An emptynetworks: {}declares nothing and is not refused, and a service’s ownnetworks:list is carried as above. - Refused as a whole: a fragment of more than one document. An
artifacts:body holding two or more YAML documents separated by---stops the build withTRANSLATION_ERROR, naming the fragment, the component and how many documents it holds, because the merge reads a fragment as one compose file and every document after the first would otherwise be missing from the assembled file. Write the fragment as one document, or give each document anartifacts:entry of its own. A document holding nothing — the empty one a trailing---opens — is not counted. A sourced compose file of several documents never becomes such a fragment: it is refused when the file is read.
The provider reads no key’s meaning: a key is carried because it is in the set above and refused because it is not.
Extension members are carried as written
The Compose Specification reserves keys beginning x- for extensions: data a tool reading the file may use and Compose itself ignores. A fragment’s extension members at the top level and on a service reach the assembled file as written, after every key the provider models at that level, in the order the fragment holds them; the provider reads nothing inside them, except a service’s x-aggrega-networks-of, which it resolves into networks the service joins and leaves out of the assembled file (see Joining the networks of other components). An artifacts: body holds them in the order it writes them. A sourced compose file’s keys reach its fragment in name order once its overlay is merged in, so its extension members are written in name order.
# an artifacts: bodyx-owner: team-bservices: migrate: image: example/migrate:1 x-schedule: manualA member reached through a YAML alias is written out in full, and no anchor is carried, so the assembled file never holds an alias whose anchor it lacks; this is what lets a top-level member hold an anchor a service’s merge key (<<: *base) brings in. A service’s members travel with its service. Top-level members union within an assembly path under the rule volumes follow: two fragments writing one member with the same content leave a single entry, whether they write it in block or flow style, and two writing it with different content stop the build under TRANSLATION_ERROR, naming the member and every contributing (boundary, node, fragment) tuple — two fragments of one component included. Make the two declarations identical, or give one of them a different name.
profiles gates a service behind a Compose profile. A service listing profiles: is one docker compose up leaves alone unless one of its profiles is enabled, and one docker compose run --rm <service> starts on request — the compose shape of a task run on demand. The list is carried as the fragment writes it, in its order:
# a sourced compose fileservices: migrate: image: example/migrate:1 profiles: [manual]Models
A compose file’s top-level models: section declares the AI models the file’s services use, and a service is granted a model through its own models: entry. The provider carries both from a fragment into the assembled docker-compose.yaml, in Compose’s own spelling, whether the fragment is a sourced compose file or an artifacts: body that evaluates to compose YAML. A Workload declares no model, so a Workload-mode Recipe contributes none.
- A model’s body is written as the fragment wrote it.
model— the OCI artifact identifier for the model —context_sizeandruntime_flagskeep their names, and every other member, anx-extension among them, is carried beside them. Within a model the three named members come first and the rest follow in key order, and the models are written in name order, so identical input produces a byte-identical file. The provider reads nothing in the body: it does not check the identifier, and it knows nothing of what will serve the model. - A service’s reference keeps its form. The short form lists model names (
models: [llm]); the long form maps each model toendpoint_varandmodel_var, the names of the variables that receive the model runner’s address and the model’s identifier. Either is written in the form and the order the fragment used, and travels with its service. Where the long form leaves a variable unnamed, Compose names it when it runs the file. - Models union within an assembly path, under the rule volumes follow. Two contributors declaring one model name with bodies that emit identically leave a single entry under it; two declaring it with different bodies halt the build under
TRANSLATION_ERROR, naming the model and every contributing(boundary, node, fragment)tuple. Two fragments of one component are two contributors here too. Make the declarations identical where both contributors mean one model, or give one of them a different name. - Every reference names a declared model. Once the assembly path’s fragments are unioned, a service granted a model that no contributor at that path declares halts the build with
TRANSLATION_ERROR, naming the service and the model. The check runs over the completed union, so one component may grant its service a model another component at the same assembly path declares. - An
omits:entry cannot leave a model out.service,volumeandconfigare the kinds this provider accepts, and an entry naming a model stops the build like one naming any other kind.
The models are served when the file runs, not when it is built. Docker Compose 2.38 or later, on a platform that supports Compose models such as Docker Model Runner, pulls and runs each model a service is granted, leaving out any other unless started with --all-resources, and sets, in each service granted it, the variables its reference names to the model runner’s address and the model’s identifier. The build cannot see the host that will run the file, so it checks neither the Compose version nor the platform: a file carrying models assembles the same way whatever runs it.
A Feature attached to a component contributes to the same file
A Feature attached to a component contributes its services to the docker-compose.yaml its host component assembles into, on the same terms as the host’s own Recipe. There is no second file beside it: one assembly path produces one document, so an attached Feature’s services are either in that document or they are not deployed at all. Detaching the Feature removes exactly those services and leaves the host component’s own untouched.
They are contributors at that assembly path like any other, so everything above applies to them unchanged — the service-name rule, and the requirement that two contributors declaring one top-level volume or config name agree about what it is. They also join the same network as the rest of the boundary, so a component and a Feature attached to it reach each other by service name with nothing further to declare.
Each service a Feature contributes carries the identity composed for that attachment rather than the host component’s, so the two stay distinguishable inside a document both contributed to. Labels and annotations covers how that identity is built.
This is a different mechanism from a Workload’s container-level attachments: block, and the two are easy to read as one because they share a word. Attaching a Feature to a component adds services to the assembled document; a container’s attachments: entry reads a credential a slot published into that one container, and is covered under Container fields.
Artifacts-emitted compose fragments
When a Recipe’s artifacts: block evaluates to compose YAML — a fragment carrying its own services:, volumes:, configs:, models:, or networks: blocks (each entry inline or per-entry $import:-loaded) — the merge into the per-(path, provider) assembly follows shape-specific rules:
services:from artifacts merge into the assembled compose file alongside per-component services. A service name contributed by two different components at the same assembly path halts, and the diagnostic names every contributor. A collision within a single component — between that component’s own artifact fragment and the services synthesized for it — is not detected, and the later contribution replaces the earlier one, so keep an artifact-authored service name distinct from the<component>and<component>--<container-name>names the synthesizer produces (see How a sidecar or init service is named).volumes:from artifacts merge into the top-levelvolumes:block. Two entries reaching one name leave a single entry under it where they declare it identically, matching the same rule as per-component volumes; two that declare it differently halt the build, whether they come from two components or from two fragments of one — two of itsartifacts:entries, or one of them and the component’s own compose file. Because an artifact fragment writes its own bodies, this is the path on which two contributors are most likely to disagree. Keep an artifact-authored volume name distinct from the others at its assembly path, including from the<component>--<volume-name>shape the derivation produces — unless two contributors are meant to describe one shared volume, in which case their declarations must match.configs:from artifacts merge into the top-levelconfigs:block. This is how the file behind aconfigmapvolume reaches the assembly: the volume becomes a service-levelconfigs:reference naming the configmap, and the artifact fragment declares an entry of that name with inlinecontent:. Once the assembly path’s fragments are unioned, every service-level reference must resolve to a declared entry, or the build halts withTRANSLATION_ERRORnaming each unresolved reference — the service, the config name, and the mount path. The check runs over the completed union rather than per component, so one component may reference a config another component at the same assembly path declares. The union reconciles by name where the contributors agree: two declaring one config name with identicalcontent:leave the single entry both of them described. Two declaring one name with differentcontent:halt the build underTRANSLATION_ERROR, naming the config and every contributing(boundary, node, fragment)tuple, two fragments of one component included — a config entry always carries content, so keeping either declaration would discard a file an author wrote. Keep a config name distinct across every contributor at its assembly path, or make the declarations identical where two contributors are meant to deliver one shared file.models:from artifacts merge into the top-levelmodels:block, and a service’smodels:reference travels with its service, under the rules in Models: two contributors declaring one model name must declare it identically, and every reference must name a model some contributor at the assembly path declares.networks:from artifacts are refused. The compose provider derives networks from boundary annotations (one network per distinctaggrega.ai/namespaceannotation, plus one named for the compose file’s path that every node without one joins, each named per How a network name is derived), so an artifact-supplied network declaration has no place in the assembled file: any entry stops the build, naming the entry and the fragment, under the rules in Every key a fragment writes is carried or refused. Remove the entry and shape networks through theaggrega.ai/namespaceannotation, or have a service join the networks of named components throughx-aggrega-networks-of; authors who need cross-network routing within a single compose file use thecompose-bridgeFeature.- Extension members from artifacts are carried. A top-level
x-key is written after the assembled file’s other sections, in the order written, under the rules in Extension members are carried as written. - Any other top-level key from artifacts stops the build.
services:,volumes:,configs:,models:and the extension members are the whole of what the assembler carries from a fragment. Asecrets:block and a top-levelname:each halt the build naming the key and the fragment, under the rules in Every key a fragment writes is carried or refused. - An
artifacts:body is one document. A body holding several YAML documents stops the build naming the fragment and how many it holds; give each document anartifacts:entry of its own.
The asymmetry between the first four and networks: is structural: services:, volumes:, configs: and models: carry per-Recipe content the assembler accumulates into the assembled file; networks: is per-boundary infrastructure the assembler derives from boundary state. Artifacts can extend the former; only boundary annotations can shape the latter, which is why an artifact’s own network entry is refused. Extension members are data the Compose Specification defines for other tools, so they are carried as written. Everything else is a shape the assembled document has no place for, which is why it is refused rather than merged.
What the compose provider does not deliver
- Cross-network L4 routing within one compose file. The provider places each node on its network and joins a service to the networks
x-aggrega-networks-ofnames, and routes nothing between networks itself. A service in network A reaching a service in network B by anything other than docker-compose’s default DNS requires thecompose-bridgeFeature, whose FeatureRecipe writes the gateway and the rewrite. - Cross-compose-file routing. Boundaries that evaluate to distinct assembly paths produce distinct
docker-compose.yamlfiles; the compose runtime treats them as independent projects, and thecompose-bridgeFeature leaves a connection between two files as written. Cross-file communication is the operator’s concern (publishing host ports, sharing external networks, or coalescing the boundaries onto one path via a shareddirectory:). - Sourcing an environment variable from an attachment. Compose has no primitive for it, so a Workload
attachmentsentry withas: envemits the variable name with an empty value rather than a runtime-resolved reference. The placeholder is deliberate — a variable that is present but empty is visible to whoever debugs the container, where an absent one leaves nothing to look at — and the build says so rather than leaving it to be discovered: each such entry raises anunsupported-fieldwarning naming the entry at its authored coordinate (containers.<name>.attachments.<KEY>, orinitContainers[<i>].attachments.<KEY>), so the author knows which variable arrives empty and which container it belongs to. The warning is advisory: the build succeeds, and the rendered file is byte-for-byte what it would be without it.--no-unsupported-field-warningssilences the class. Anattachmentsentry withas: fileis unaffected — compose bind-mounts it, and no warning is raised. - Swarm-mode
deploy:content. Replicas, placement constraints, and update strategy underdeploy:are swarm-mode features, and the compose provider targets single-host compose only, so it emits none of them. It does emitdeploy.resources— the reservations and limits a container’sresourcesmap to, which docker compose honours in non-swarm mode (see Container resources). - Health-condition-gated
depends_onfrom ausesedge. A dependency derived from ausesedge is emitted ungated, withservice_startedsemantics; it is not gated on the target’s healthcheck reporting healthy. This is about what ausesedge means, not about a shape the provider cannot produce: the long form is emitted for an init container wait, and a deployment wave does gate on the target’s health where the target declares a healthcheck.
Authoring example
A two-service compose deployment with a depends_on edge derived from uses:
# 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.0The compose provider produces one docker-compose.yaml at the boundary’s evaluated path (default dist/boundaries/production/compose/docker-compose.yaml, because a boundary’s directory: defaults to dist/boundaries/<name> and subDirectory: to {{ .capability }}) containing:
services.api(the main api service, networkprod, ports8080:8080, healthcheck viacurl,depends_on: [db])services.db(the main db service, networkprod)networks.prod(the boundary’s docker network)
Related references
- Workload entity — the platform-owned Workload kind that the compose provider translates.
- Provider architecture — how providers fit into the compilation pipeline.
- Well-known annotations — the
aggrega.ai/*annotations the compose provider consumes. - Provider reference index — what each standard-library provider produces, and which page answers which question.
- Recipe input composition — the canonical Provider Capability Matrix.