Provider Compose
Le fournisseur compose rend les Recipes d’Aggrega en un fichier Docker Compose. Le fournisseur assemble par (path, provider) : les contributeurs compose de chaque frontière sont acheminés vers l’assembleur indexé sur le directory: évalué de la frontière joint au subDirectory: de chaque composant, et cet assembleur émet un seul docker-compose.yaml contenant chaque contributeur à ce chemin. Deux frontières sœurs qui s’évaluent au même chemin se fondent en un seul fichier compose fusionné — l’exemple canonique est une frontière parente plus deux frontières enfants avec directory: "{{ .parent_boundary.directory }}" (le modèle compose-bridge).
Types d’entrée pris en charge
Le fournisseur compose accepte les trois types d’entrée de Recipe :
- Mode issu d’une source. Une Recipe avec
source:pointant vers un fichier compose existant, plusvaluesMapping:produisant un document de surcouche. Le fichier compose de base est chargé, la surcouche est évaluée, et les deux sont fusionnés en profondeur selon la sémantique de surcouche native de docker-compose. - Mode Workload. Une Recipe avec
workload:(inline ou chargé via$import:) déclare un documentWorkload. Le fournisseur synthétise un ou plusieurs services compose à partir de la spécification du Workload. - Mode artefacts. Les entrées
artifacts:d’une Recipe s’évaluent en fragments compose, qui fusionnent dans le fichier assemblé selon les règles de Fragments compose émis comme artefacts. Les artefacts peuvent accompagner une source ou un Workload, et ils peuvent aussi constituer toute la sortie d’une Recipe : une Recipe qui déclareartifacts:et nisource:niworkload:est rendue ici, et apporte tout ce que ses fragments déclarent. C’est ainsi qu’un composant fait uniquement de ressources — un ensemble partagé de réseau et de volumes, une configuration préremplie — atteint un déploiement compose sans qu’un Workload de remplacement tienne lieu d’une capacité de calcul qu’il n’a pas.
Les trois types se composent par addition, et une Recipe qui n’en déclare aucun est refusée à son chargement. Un valuesMapping: sans source: à côté est lui aussi refusé au chargement de la Recipe, quel que soit le fournisseur qu’elle nomme : il n’y a rien sur quoi appliquer la surcouche, et le diagnostic vous demande de déclarer le pointeur source: ou de retirer le valuesMapping:.
Correspondance des fonctionnalités du Workload
Lorsqu’une Recipe déclare workload:, le fournisseur traduit la forme Workload détenue par la plateforme en primitives compose. La correspondance est volontairement étroite — la surface de Compose est plus pauvre en formes que celle de Kubernetes, et plusieurs fonctionnalités du Workload se dégradent vers l’équivalent compose le plus proche, avec une perte documentée.
Champs du conteneur
| Champ du Workload | Champ Compose |
|---|---|
image | image |
imagePullPolicy: Always / IfNotPresent / Never | pull_policy: always / if_not_present / never |
command | entrypoint (forme liste) — il remplace le point d’entrée de l’image, ce que fait précisément cette clé compose |
args | command (forme liste) — il fournit les arguments que reçoit le point d’entrée, ce que remplace le command de compose |
variables | environment (forme table) |
attachments[as: env] | entrée environment avec une valeur vide, et un avertissement nommant l’entrée (voir Ce que le fournisseur compose ne fournit pas) |
attachments[as: file] | bind-mount volumes en forme longue, en lecture seule |
volumeMounts | la primitive compose à laquelle correspond la variante de volume référencée — une entrée volumes en forme longue, une entrée tmpfs: au niveau du service, ou une référence configs: au niveau du service (voir Volumes) |
ports | implicite (les conteneurs compose exposent les ports sur lesquels l’image écoute) |
restartPolicy: Always | restart: unless-stopped |
restartPolicy: OnFailure | restart: on-failure |
restartPolicy: Never | restart: "no" |
variables et attachments[as: env] aboutissent dans l’unique table environment, les entrées des rattachements d’abord et les variables ensuite, chacune dans l’ordre où elle est rédigée — l’ordre qu’écrit le fournisseur helm, de sorte qu’un Workload rend une seule séquence d’environnement sur chaque cible. Compose ne développe aucune référence $(NAME) entre les entrées d’environnement d’un service, donc sur compose cet ordre n’a aucune signification à l’exécution. Comme la table contient chaque nom une seule fois, un conteneur qui donne un même nom à la fois comme entrée de variables et comme entrée d’attachments livrée as: env arrête le build au lieu de conserver l’une des deux valeurs (voir A container gives one environment variable two values (Un conteneur donne deux valeurs à une même variable d’environnement)).
Ressources des conteneurs
Les resources d’un conteneur atteignent le bloc deploy.resources de compose, que docker compose respecte en mode non swarm. Les requests de Kubernetes expriment un minimum garanti, elles deviennent donc des reservations compose ; les limits expriment un plafond strict, elles restent donc des limits.
| Champ du Workload | Champ Compose | Traduction |
|---|---|---|
resources.requests.cpu | deploy.resources.reservations.cpus | Un nombre décimal de cœurs. Un nombre de cœurs écrit comme nombre nu (2, 0.5) est émis tel qu’il est écrit ; toute autre forme est convertie à partir de sa valeur (500m → 0.5, 1500m → 1.5, 5n → 0.000000005, 1e1 → 10) |
resources.limits.cpu | deploy.resources.limits.cpus | Même conversion |
resources.requests.memory | deploy.resources.reservations.memory | Un nombre exact d’octets, converti à partir de la valeur quelle que soit la forme sous laquelle elle est écrite — 8Gi devient 8589934592, 1.5Gi devient 1610612736, 1e3 devient 1000 |
resources.limits.memory | deploy.resources.limits.memory | Même conversion |
nvidia.com/gpu, sous resources.limits, resources.requests ou les deux | deploy.resources.reservations.devices | Une entrée de périphérique NVIDIA sur le service du conteneur — driver: nvidia, count: le nombre de GPU, capabilities: [gpu]. Le nombre est celui de la limite là où une limite est écrite — le nombre que Kubernetes planifie pour une ressource étendue — et celui de la demande sinon. Un nombre de 0 ne demande aucun GPU et n’écrit aucune entrée |
toute autre clé de ressource étendue — amd.com/gpu et tout autre <domain>/<name> | — | Aucun équivalent compose sur un seul hôte. La clé est abandonnée et le build émet un avertissement unsupported-field qui la nomme, un par clé distincte, quel que soit le nombre de requests et de limits qui la portaient. Sa valeur n’est pas émise, elle n’est donc pas vérifiée |
Chaque valeur cpu, memory et nvidia.com/gpu est lue comme une quantité, sous la forme exposée dans Workload → Quantités de ressources, sur le Workload tel que les templates de la Recipe l’ont évalué. Deux choses arrêtent le build avec une TRANSLATION_ERROR, et l’erreur indique laquelle des deux elle a rencontrée, en nommant le chemin du conteneur, si la valeur est une demande ou une limite, la ressource et la valeur :
- une valeur qui n’est pas une quantité —
lots,1.5 cores, ou lemqu’un template vide laisse dans"{{ .infra.cpu }}m"; - une quantité que compose ne peut pas représenter exactement — un montant négatif ; un montant de mémoire qui n’est pas un nombre entier d’octets (
1500m,4u) ou qui dépasse 9223372036854775807 octets (8Ei) ; un montant de cpu plus fin que neuf décimales d’un cœur, la précision la plus fine qu’une quantité Kubernetes conserve elle-même, ou supérieur à 9223372036.854775807 cœurs ; un nombre de GPU qui n’est pas un nombre entier de périphériques (0.5,500m).
Un conteneur dont la demande et la limite nvidia.com/gpu demandent des nombres différents arrête le build de la même manière, en nommant les deux chemins : compose réserve un seul nombre pour un service, la traduction devrait donc sinon en choisir un. Écrivez le même nombre dans les deux, ou seulement la limite.
Rien n’est arrondi, et aucune valeur signifiant autre chose n’est émise.
Une demande de GPU réserve des GPU NVIDIA. Un conteneur de Workload qui demande nvidia.com/gpu: "1" est rendu en un service portant cette réservation, à côté des cpus et memory que réservent ses demandes :
deploy: resources: reservations: devices: - driver: nvidia count: 1 capabilities: - gpuDocker Compose remet les GPU réservés au conteneur lorsque l’hôte Docker dispose d’autant de GPU NVIDIA et est configuré pour les donner aux conteneurs ; le build ne peut pas voir l’hôte, donc un fichier qui réserve des GPU s’assemble de la même manière partout où il sera exécuté. L’entrée indique toujours son nombre, car Compose lit une entrée de périphérique sans nombre comme tous les GPU de l’hôte. Seule la clé NVIDIA est traduite : amd.com/gpu et la clé de tout autre fabricant conservent l’avertissement de la ligne des clés abandonnées. La ligne runtimeClassName dans Champs au niveau du pod est inchangée — compose n’a pas d’équivalent de la classe de runtime, donc un Workload qui nomme un runtime compatible GPU est informé que le runtime a été omis, tandis que son nombre de GPU est réservé.
Sondes
Les trois slots de sonde d’un Workload (live, ready, startup) se réduisent à l’unique healthcheck par service de compose, avec la priorité live > ready > startup (le signal de liveness le plus canonique l’emporte). Là où cette réduction écarte un slot que l’auteur a déclaré, le build émet un avertissement unsupported-field nommant le slot traduit et les slots écartés, de sorte qu’une intention qui n’atteint aucune partie de la sortie est signalée plutôt que perdue. Un bloc health déclarant un seul slot se traduit sans perte et n’émet rien, sauf si le slot définit successThreshold : un healthcheck compose n’a pas de champ pour cela, donc une valeur rédigée — 1 compris — est omise avec un avertissement unsupported-field qui la nomme (containers.<name>.health.<slot>.successThreshold), et le reste du slot se traduit comme le montre le tableau ci-dessous.
| Forme de sonde du Workload | healthcheck.test de Compose |
|---|---|
http: /path | ["CMD-SHELL", "curl -f http://localhost:<port>/path || exit 1"] |
tcp: <port> | ["CMD-SHELL", "nc -z localhost <port>"] |
exec: [cmd, ...] | ["CMD", cmd, ...] |
La forme HTTP exige que le conteneur déclare au moins un port nommé ; le synthétiseur choisit le premier nom de port dans l’ordre alphabétique et utilise son numéro pour construire l’URL curl. Les conteneurs sans port déclaré ne peuvent pas utiliser de sondes HTTP — le compilateur s’arrête avec une TRANSLATION_ERROR nommant la sonde en cause.
Les champs de délai des sondes correspondent à des chaînes de durée de style compose :
| Champ du Workload | Champ healthcheck de Compose |
|---|---|
periodSeconds | interval: <n>s |
timeoutSeconds | timeout: <n>s |
failureThreshold | retries: <n> |
initialDelaySeconds | start_period: <n>s |
Volumes
Compose dispose d’une primitive de config qui lui est propre, et c’est en elle qu’un volume configmap est traduit. Il n’a pas d’équivalent Kubernetes pour les Secret ni pour les templates de volume par réplica, de sorte que ces variantes se dégradent vers la primitive compose la plus proche :
| Variante de volume du Workload | Traduction Compose | Notes sur les pertes |
|---|---|---|
ephemeral | entrée de liste tmpfs: au niveau du service | sizeLimit n’est pas conservé (la forme courte du tmpfs de compose n’a pas de taille). Un sizeLimit écrit par l’auteur déclenche un avertissement unsupported-field qui le nomme à sa coordonnée de rédaction (volumes.<name>.ephemeral.sizeLimit), qu’un conteneur monte ou non le volume ; omettre le champ ne déclenche rien |
configmap | référence configs: au niveau du service nommant la configmap, montée au chemin du montage de volume | 🔴 Le chemin de montage est le chemin d’un seul fichier, pas d’un répertoire. Compose écrit le contenu de la config exactement au chemin cible, là où une cible Kubernetes montant une ConfigMap à un chemin produit un répertoire contenant un fichier par clé. Le même path: écrit désigne donc ici un fichier et là-bas un répertoire : pointez le montage d’un volume configmap vers le nom du fichier que le conteneur doit lire (/seed/config.json), et non vers le répertoire qui le contiendrait, et une Recipe écrite pour les deux cibles porte un chemin différent pour chaque cible. Rien dans le build ne peut détecter un chemin écrit pour la forme de l’autre cible — le chemin est une chaîne opaque que le compilateur transmet sans l’interpréter, et la sortie émise est valide dans les deux cas. La référence se fait par nom, exactement comme une cible Kubernetes fait référence à une ressource ConfigMap — rien ne lit le contenu de la config. L’entrée configs: de premier niveau correspondante provient de l’entrée artifacts: de la Recipe, dont le fragment compose la déclare avec un content: inline ; une référence sans une telle entrée arrête le build (voir Fragments compose émis comme artefacts). Une référence configs: porte le nom de la config et le chemin de montage, et rien d’autre, de sorte que le readOnly du montage n’a pas d’expression distincte |
secret | bind-mount volumes en forme longue, en lecture seule | Un volume secret ne suit délibérément pas la traduction configmap : une entrée configs: inline écrirait la valeur du secret en clair dans le fichier compose émis, et le compilateur ne résout jamais un secret en clair — un secret reste un pointeur à chaque étape du build. La source du bind est le nom source du secret, résolu comme un chemin que l’opérateur rend accessible sur l’hôte compose indépendamment du build |
persistent | volume nommé + déclaration volumes: { <volume-name>: {} } de premier niveau, nommé selon Comment un nom de volume est dérivé | La classe de stockage, les modes d’accès et la taille ne sont pas conservés (compose n’a pas de forme équivalente). Un class ou un accessModes écrit par l’auteur déclenche un avertissement unsupported-field qui le nomme à sa coordonnée de rédaction (volumes.<name>.persistent.class, volumes.<name>.persistent.accessModes) ; omettre l’un ou l’autre ne déclenche rien. Le size obligatoire ne déclenche aucun avertissement — voir ci-dessous |
persistentTemplate | volume nommé + déclaration de premier niveau, nommé de la même façon (comme pour persistent) | Compagnon de form: stateful ; compose n’a pas de primitive de templating de volume par réplica, de sorte que le comportement par réplica est perdu, et un avertissement unsupported-field indique que le volume est devenu un seul volume que tous les réplicas partagent. La classe de stockage, les modes d’accès et la taille ne sont pas conservés, exactement comme pour persistent : un class ou un accessModes écrit par l’auteur déclenche un avertissement unsupported-field à volumes.<name>.persistentTemplate.class ou volumes.<name>.persistentTemplate.accessModes, et le size obligatoire n’en déclenche aucun |
Le subPath d’un montage monte une partie d’un volume là où compose a une forme pour cela. Une entrée volumeMounts nommant un volume persistent ou persistentTemplate avec subPath devient une entrée volumes en forme longue portant volume.subpath, de sorte que le montage voit le répertoire ou le fichier nommé à l’intérieur du volume plutôt que sa racine, et deux montages d’un même volume avec deux valeurs subPath différentes en voient deux parties différentes :
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: uploadsUn montage écrit sans subPath ne porte aucun bloc volume:. Un subPath sur un montage d’un volume ephemeral, configmap ou secret arrête le build avec une erreur TRANSLATION_ERROR nommant le composant, le conteneur, le chemin écrit du montage (containers.<name>.volumeMounts[<i>]), le volume et le subPath : ces variantes atteignent compose sous la forme d’une entrée tmpfs, d’une référence configs: et d’un montage bind, dont aucun ne monte une partie de ce qu’il fournit, de sorte que le montage verrait sinon le volume entier. Retirez subPath d’un tel montage, ou montez un volume persistent. Docker Compose lit volume.subpath à partir de la version 2.26.0, sur Docker Engine 26.0 ou ultérieur ; le build ne peut pas voir l’hôte qui exécutera le fichier, de sorte qu’un fichier qui en porte un s’assemble de la même façon partout où il s’exécutera.
Un volume dit quelle variante il est, et rien de plus. Un volume secret a exactement une traduction — le montage bind en lecture seule ci-dessus — et un volume ne porte aucun champ as: pour en sélectionner une autre. Livrer ce qu’un slot a publié sous forme de variable d’environnement relève d’une entrée attachments du conteneur (as: env) plutôt que d’un volume ; ce que compose fait d’une telle entrée est décrit sous Ce que le fournisseur compose ne fournit pas.
Trois variantes portent une taille de stockage, et une seule d’entre elles avertit que la taille a été abandonnée. La différence tient à ce que vous ayez eu le choix ou non. Le sizeLimit d’un volume ephemeral est facultatif, l’écrire était donc une décision, et l’avertissement vous indique que la valeur ne façonne rien sur cette cible et peut être retirée — il est consultatif et hors bande, le fichier émis est identique octet pour octet à ce qu’il serait sans lui, et --no-unsupported-field-warnings le fait taire avec le reste de la classe. Le size d’un volume persistent ou persistentTemplate est obligatoire, de sorte qu’aucune version du document ne l’omet : un avertissement à chaque build se déclencherait là sur chaque charge de travail avec état sans rien nommer que vous puissiez changer, la différence est donc expliquée ici plutôt que signalée à chaque build. Avec compose pour cible, le size, le class et les accessModes d’un volume persistant ne façonnent rien dans le fichier émis — vous obtenez un simple volume nommé, dimensionné et adossé à ce que fait par défaut le pilote de volume de l’hôte compose. class et accessModes sont facultatifs, de sorte que chacun de ceux que vous écrivez est signalé comme l’est le sizeLimit d’un volume ephemeral : un avertissement unsupported-field par champ, consultatif et hors bande, que le même indicateur fait taire. Dimensionnez le stockage sous-jacent sur l’hôte, ou sur la cible Kubernetes, où les champs atteignent bien la sortie.
Un volume qu’aucun conteneur ne monte déclenche un avertissement unsupported-field qui le nomme à sa coordonnée de rédaction (volumes.<name>), car ce qui atteint le fichier émis diffère alors nettement selon la variante. persistent et persistentTemplate produisent quand même leur déclaration de premier niveau, de sorte que le volume est créé et que rien ne l’utilise. ephemeral, configmap et secret n’ont aucune expression en dehors du montage lui-même — chacun se traduit en quelque chose d’écrit au chemin de montage, respectivement une entrée tmpfs, une référence configs ou un montage bind — de sorte que, si rien n’en monte un, le volume que vous avez déclaré ne laisse aucune trace dans la sortie. Ce second cas est la raison d’être de l’avertissement : sans lui, un volume configmap dont vous auriez oublié le montage serait tout simplement absent, sans rien dans le fichier émis pour le remarquer. Chaque conteneur de la charge de travail compte comme un conteneur qui monte le volume, init containers compris, de sorte qu’un volume monté uniquement par un init container est câblé et ne déclenche rien. L’avertissement est consultatif et hors bande — le fichier émis est identique octet pour octet à ce qu’il serait sans lui — et --no-unsupported-field-warnings fait taire la classe.
Comment un nom de volume est dérivé
Un volume persistent ou persistentTemplate devient un volume nommé compose : une entrée volumes: de premier niveau, référencée par chaque conteneur qui le monte. Un volume compose est un stockage partagé, et le bloc volumes: de premier niveau fusionne ses entrées par nom — deux volumes écrits qui aboutissent à un même nom deviennent donc un seul volume dans lequel écrivent les deux conteneurs, sans rien dans le fichier émis pour montrer qu’il y en avait deux de prévus. Le nom est donc construit à partir des deux identités qui, ensemble, disent de quel volume il s’agit : le <component> auquel appartient le volume, et le nom que le Workload a donné au volume sous volumes:.
Un nom de volume compose accepte un ensemble de caractères plus restreint que celui que chacune des deux identités peut contenir : lettres, chiffres, points, tirets bas et traits d’union. Plutôt que de remplacer un caractère que compose n’accepte pas, la dérivation l’écrit en toutes lettres, de sorte que deux volumes qui diffèrent si peu que ce soit aboutissent à deux noms — et un nom assemblé peut être relu pour retrouver les deux identités à partir desquelles il a été construit.
- Une lettre, un chiffre, un point et un tiret bas sont repris exactement tels qu’ils ont été écrits.
- Un trait d’union est conservé tel qu’il a été écrit partout où le caractère qui le suit est repris directement et n’est pas un
zminuscule. Un trait d’union suivi d’unzminuscule ouvre une séquence d’échappement, de sorte qu’un trait d’union écrit à cette position est lui-même écrit en toutes lettres —api-zonedevientapi-zhzone, ce qui permet de relire n’importe quel nom sans deviner. Un trait d’union suivi de rien est écrit en toutes lettres pour la même raison, de sorte quedb-donnedb-zh. - Tout autre caractère est écrit comme
-zsuivi d’une lettre qui le nomme :spour un séparateur de chemin,hpour un trait d’union que la règle ci-dessus ne conserve pas. Tout le reste — y compris une espace et une lettre non ASCII — est écrit commexsuivi du point de code hexadécimal à six chiffres du caractère, et un octet qui ne commence aucun caractère commebsuivi de sa propre valeur à deux chiffres, de sorte qu’un nom qui n’est pas un texte valide est quand même écrit de façon distincte plutôt que confondu avec un autre. - Une valeur vide est écrite
-ze, ce qu’aucune valeur non vide ne peut produire. - Les deux identités sont jointes par
--. Une identité encodée ne contient jamais cette paire, de sorte que le nom joint indique sans ambiguïté où une identité se termine et où l’autre commence.
Ainsi, le composant store avec un volume que le Workload appelle data donne le nom de volume store--data, et db-server avec data donne db-server--data. Une entrée identique produit toujours le nom identique.
C’est la jonction doublée qui rend la paire non ambiguë, et une jonction d’un seul caractère ne le peut pas. Chacune des deux identités peut elle-même contenir un trait d’union, de sorte qu’une jonction par un seul trait d’union laisse un nom qui se divise à plus d’un endroit : db avec un volume appelé data-cache et db-data avec un volume appelé cache s’écriraient tous deux db-data-cache, et comme le bloc de premier niveau fusionne par nom, les deux composants partageraient un seul volume sans rien dans le fichier émis pour le montrer. Une identité encodée ne contient jamais une paire de traits d’union, de sorte que la jonction doublée n’admet aucune seconde lecture : les deux aboutissent à db--data-cache et db-data--cache.
Changer l’une ou l’autre identité renomme le volume compose, et compose ne renomme pas un volume sur place. Le volume est créé à neuf sous le nouveau nom tandis que l’ancien reste derrière avec les données qu’il contient, de sorte que le conteneur démarre sur un stockage vide et que le contenu reste dans un volume que rien ne monte. Ne renommez l’une ou l’autre identité que comme un remplacement à planifier — sauvegardé, copié ou programmé — et non comme un simple changement à déployer.
Forme de contrôleur
Le form du Workload sélectionne une forme abstraite de contrôleur (voir entities/workload.md). Compose rend stateless et stateful (ainsi que la valeur par défaut vide, traitée comme stateless) sous forme de services de longue durée ; la forme stateful ajoute le volume nommé pour un compagnon persistentTemplate. Les formes daemon, scheduled et task n’ont pas de correspondance compose nette sur un hôte unique, de sorte qu’un Workload déclarant l’une d’elles en ciblant une frontière compose arrête le build avec une erreur TRANSLATION_ERROR qui nomme la forme et l’ensemble pris en charge — compose ne dégrade pas une forme non prise en charge en un simple service qui dénaturerait l’intention. Un Workload reference déclare un endpoint externe et aucun conteneur, de sorte que compose n’émet aucun service pour lui.
Comme aucun service n’est émis pour un Workload reference, rien ne lit le pipe de livraison du composant qu’il réalise : un identifiant secret rattaché à ce composant — livré sur son pipe par dotenv-secret, ou par le bloc inject: propre à un rattachement — n’atteindrait aucun fichier émis. Chaque Recipe Compose de la bibliothèque standard qui réalise ainsi un service externe, et dont le Component déclare un slot d’identifiant, refuse donc un identifiant qui remplit ce slot : le build s’arrête en nommant le slot et le composant, plutôt que de réussir sans l’identifiant. Sur compose, un identifiant destiné à un service externe est rattaché au composant qui l’appelle, sous la variable d’environnement que lit ce composant. Ce refus est une assertion propre à chaque Recipe, et il s’exécute avant que ce fournisseur ne rende quoi que ce soit. Ce fournisseur refuse aussi sur le nœud lui-même, quel que soit le catalogue dont provient la Recipe : un rattachement sur un nœud reference dont le contenu est déclaré sensible — sa Feature déclare un champ sensitive: true, ou le slot qu’il remplit le fait — arrête le build avec TRANSLATION_ERROR (E0288), en nommant le nœud et chacun de ces rattachements, qu’un slot déclare ou non le nom sous lequel il est rattaché. Un rattachement qui ne porte rien de déclaré sensible n’est pas refusé ici. Ces Components déclarent leurs slots d’identifiant facultatifs, de sorte que, sur compose, un slot laissé vide n’arrête rien. Là où la réalisation Kubernetes a besoin de l’identifiant — les Recipes helm de twilio, vonage, telnyx, bland, letta, retell et vapi — cette Recipe exige le slot à la place, et arrête le build en le nommant lorsqu’il est vide.
Exposition des services
Le champ type d’une entrée services du Workload décide si compose publie des ports, et sur quelle adresse de l’hôte :
| Type de service du Workload | Comportement de Compose |
|---|---|
ClusterIP | Aucune publication ports: — le service n’est joignable que sur le réseau compose |
NodePort | Publication ports: [<host>:<container>], sur toutes les interfaces de l’hôte |
LoadBalancer | Publication ports: [<host>:<container>], sur toutes les interfaces de l’hôte (compose n’a pas d’équivalent de load balancer géré ; la publication sur un port de l’hôte est l’analogue le plus proche) |
Loopback | Publication ports: [127.0.0.1:<host>:<container>] — joignable depuis l’hôte lui-même et depuis nulle part ailleurs |
Headless | Aucune publication ports: |
Quel numéro va de quel côté. Une entrée de service nomme un port de conteneur et lui donne un numéro, comme un Service Kubernetes fait correspondre son port à un targetPort. Le numéro de l’entrée est le côté <host> de la paire publiée, et le numéro du port de conteneur auquel le nom se résout est le côté <container>. Ainsi, un conteneur déclarant http: 8080 et une entrée NodePort écrivant http: 8081 publient 8081:8080 : le port 8081 de l’hôte atteint le port sur lequel le conteneur sert. Une entrée qui porte le numéro propre au port de conteneur publie ce numéro des deux côtés, 8080:8080. Un pair sur le réseau compose atteint le service par son nom de service sur le port du conteneur, jamais sur le port publié — le port publié appartient à l’hôte — de sorte qu’une Recipe qui publie un port de son choix remet tout de même à ses consommateurs le port du conteneur.
Une entrée Loopback se lie uniquement à l’adresse de loopback IPv4. L’adresse de loopback IPv6 ::1 n’est pas liée : la syntaxe de port de compose porte une seule adresse d’hôte par entrée, et un hôte dont l’interface de loopback ne porte aucune adresse IPv6 ne pourrait pas la lier, de sorte que le service n’y démarrerait pas. Les clients sur l’hôte atteignent le port à 127.0.0.1.
Lorsque plusieurs services d’un même Workload publient le même port de conteneur sous le même numéro, il est publié une seule fois, et la portée la plus large l’emporte : toute référence NodePort ou LoadBalancer le publie sur toutes les interfaces de l’hôte, même lorsqu’une entrée Loopback le nomme aussi et quelle que soit l’entrée déclarée en premier ; un port que seules des entrées Loopback nomment est publié sur 127.0.0.1. Un port de conteneur publié sous deux numéros est publié deux fois, une fois sous chacun. Les ports publiés sont listés dans l’ordre des ports de conteneur, et par port publié au sein d’un même port de conteneur.
Transport des ports. Une entrée publiée porte le transport déclaré sur le port de conteneur qu’elle nomme, sous la forme du suffixe /protocol de compose : 53:53/udp, ou 127.0.0.1:53:53/udp pour une entrée Loopback. Un port qui ne déclare aucun transport est publié comme <host>:<container> sans suffixe, ce qui laisse en vigueur la valeur par défaut de compose. Compose écrit le transport d’un port publié tcp ou udp ; un port qui déclare SCTP n’a pas de graphie compose, il arrête donc le build avec une erreur TRANSLATION_ERROR plutôt que de publier un port qui porterait un transport différent. Un port de conteneur qu’aucun service ne publie n’atteint aucune partie du fichier compose, de sorte qu’un transport déclaré sur un tel port n’a rien sur quoi être écrit et n’arrête pas le build.
Workloads multi-conteneurs
Un Workload à plusieurs conteneurs devient un service principal plus un service sidecar par conteneur non principal. Le conteneur principal est celui nommé main (s’il est présent) ou le premier conteneur dans l’ordre de déclaration. Les sidecars partagent le namespace réseau du service principal via network_mode: "service:<main>" — la primitive compose la plus proche du modèle de réseau partagé d’un pod Kubernetes.
Comment un service sidecar ou init est nommé
Le service principal porte le nom <component> tel quel. Tout autre service que produit le Workload — un par sidecar, et un par conteneur init — est nommé à partir de deux identités réunies : le <component>, et le nom du conteneur, qui est sa clé sous containers: pour un sidecar et son name pour un conteneur init, ou le init-<index> positionnel que prend une entrée init sans nom. Le bloc services: assemblé contient un service par nom, de sorte que le nom est construit pour que deux conteneurs différant par l’une ou l’autre identité aboutissent toujours à deux noms.
Chaque identité est écrite exactement comme le sont les deux parties d’un nom de volume — une lettre, un chiffre, un point et un trait de soulignement tels qu’écrits, un trait d’union conservé là où les règles de cette section le conservent, et tout autre caractère transcrit — et les deux sont joints par --, qu’aucune identité transcrite ne contient. Ainsi, le composant api avec un sidecar logger l’exécute sous le nom api--logger, le conteneur init import-seed de platform s’exécute sous le nom platform--import-seed, et une première entrée init sans nom de api s’exécute sous le nom api--init-0. Un nom de conteneur comportant un caractère qu’un nom de service n’admet pas est transcrit plutôt qu’émis tel qu’écrit : un conteneur init nommé warm cache/x de api s’exécute sous le nom api--warm-zx000020cache-zsx.
La double jonction sépare les conteneurs de deux composants. api avec un conteneur warm-cache et api-warm avec un conteneur cache s’exécutent sous les noms api--warm-cache et api-warm--cache, deux services, là où une jonction à un seul trait d’union les écrirait tous deux api-warm-cache.
Les sidecars et les conteneurs init partagent ce seul nommage, de sorte qu’une entrée containers et une entrée initContainers portant le même nom aboutissent au même nom de service, et la compilation s’arrête sur la paire plutôt que d’exécuter un conteneur à la place de l’autre (voir Init containers).
Le service propre d’un composant ne prend aucun de ces noms. Le service principal est nommé d’après le composant, et un double trait d’union écrit dans le nom d’un composant y est lui-même transcrit — un composant nommé api--prep s’exécute sous le nom api-zh-prep — de sorte qu’il ne porte jamais la jonction --. Là où des services de deux composants différents se rencontrent malgré tout sur un nom dans un même fichier compose — par un service qu’un artefact nomme pour lui-même, par exemple — la compilation s’arrête en nommant les deux, comme le décrit Sortie par (path, provider).
Changer le nom du composant ou le nom du conteneur renomme le service. Compose traite un service sous un nouveau nom comme un nouveau service, si bien que son conteneur est recréé sous le nouveau nom.
Champs au niveau du pod
Les champs du Workload au niveau du pod s’appliquent uniquement au service principal — les sidecars partagent le namespace réseau du service principal — et un service d’initialisation suit la même règle. La seule exception est l’utilisateur du pod : un pod exécute chacun de ses conteneurs en tant que podSecurityContext.runAsUser et runAsGroup, de sorte que ceux-ci atteignent chaque service que produit le Workload, services sidecar et d’initialisation compris.
Plusieurs correspondent à un champ de service compose :
| Champ du Workload | Champ Compose |
|---|---|
podSecurityContext.runAsUser / runAsGroup | user ("1000", ou 1000:3000 avec un groupe) sur chaque service du Workload. Un conteneur qui définit son propre securityContext.runAsUser s’exécute à la place sous cet utilisateur sur son propre service, avec son propre runAsGroup lorsqu’il en définit un |
terminationGracePeriodSeconds | stop_grace_period: <n>s |
dnsConfig.nameservers / dnsConfig.searches | dns / dns_search |
hostAliases | une entrée extra_hosts par nom d’hôte, dans l’ordre de l’auteur |
hostNetwork: true | network_mode: host |
Exécution sur le réseau du nœud. Une charge de travail qui déclare hostNetwork: true reçoit network_mode: host sur son propre service, et ce service est alors laissé hors du réseau de la frontière au lieu d’y être connecté : compose refuse un service qui déclare à la fois networks: et network_mode:, de sorte que les deux sont des alternatives et non des ajouts. La conséquence pratique est celle qu’entraîne toujours le réseau de l’hôte — les pairs n’atteignent plus le service par son nom de service compose sur ce réseau, car il n’y est plus ; ils l’atteignent sur les adresses propres de l’hôte, ce que la déclaration a demandé. Aucun autre service de la frontière n’est affecté.
Deux formes se combinent avec cela. Un sidecar continue de nommer le service principal (network_mode: "service:<main>"), de sorte qu’il suit le service principal sur le réseau de l’hôte sans rien déclarer lui-même — de la même façon que les conteneurs d’un pod Kubernetes partagent un seul namespace. Un service d’initialisation, non : il rejoint le réseau de la frontière de plein droit, car partager le namespace du service principal rendrait circulaire l’attente du service principal sur lui. Ainsi, une charge de travail avec à la fois hostNetwork et initContainers exécute son propre service sur le réseau de l’hôte tandis que ses services d’initialisation restent sur le réseau de la frontière, ce qui est plus restreint que la forme de pod qu’elle modélise ; un avertissement unsupported-field nomme cette différence plutôt que de la laisser découvrir à l’exécution.
Les autres n’ont pas d’équivalent sur un hôte unique. Aucun n’est abandonné en silence : chacun de ceux qui sont écrits déclenche un avertissement unsupported-field qui nomme le champ, de sorte qu’un auteur apprend quel réglage la cible n’a pas pu respecter plutôt que de le découvrir dans la stack en cours d’exécution.
| Champ du Workload | Pourquoi compose ne peut pas le respecter |
|---|---|
scheduling | Le placement — nodeSelector, affinity, tolerations, topologySpreadConstraints — présuppose un scheduler qui choisit parmi des nœuds. Compose s’exécute sur un seul hôte |
replicas | Le nombre de réplicas propre à compose se trouve sous deploy: et est une fonctionnalité du mode swarm |
runtimeClassName | La sélection d’un runtime de conteneur alternatif — un runtime compatible GPU, par exemple — n’a pas d’expression compose |
priorityClassName | L’ordre de préemption présuppose un scheduler |
serviceAccount | L’identité de Workload est un concept de cluster |
imagePullSecrets | Les identifiants de registre sur un hôte compose sont l’état de connexion propre de l’hôte, et non un champ du fichier |
dnsPolicy, dnsConfig.options | Compose expose dns et dns_search et rien de plus fin |
podSecurityContext.fsGroup, podSecurityContext.supplementalGroups | user porte un utilisateur et un groupe ; le groupe propriétaire des volumes d’un pod, et les groupes supplémentaires de ses processus, ne sont pas traduits |
podSecurityContext.runAsGroup, lorsque le pod ne définit aucun runAsUser, ou lorsqu’un conteneur — principal, sidecar ou d’initialisation — définit son propre runAsUser et aucun runAsGroup | user ne nomme un groupe qu’à côté d’un utilisateur, et l’utilisateur propre d’un conteneur prend la place de celui du pod, de sorte que le groupe du pod n’atteint aucun service écrit de cette façon |
Le securityContext au niveau du conteneur se traduit partiellement : readOnlyRootFilesystem → read_only, capabilities.add / drop → cap_add / cap_drop, runAsUser / runAsGroup → user. runAsNonRoot et allowPrivilegeEscalation n’ont pas d’expression compose et déclenchent le même avertissement unsupported-field, tout comme un runAsGroup de conteneur écrit sans runAsUser à côté : le service s’exécute alors sous l’utilisateur du pod lorsque le pod en définit un, sans ce groupe.
Chaque avertissement de cette section est consultatif et hors bande : le build réussit, et le fichier émis est identique octet pour octet à ce qu’il serait sans lui. --no-unsupported-field-warnings fait taire la classe.
Init containers
Les entrées initContainers d’un Workload deviennent des services à part entière, selon l’idiome d’exécution jusqu’à complétion de compose. Chaque entrée ajoute un service, nommé à partir de <component> et du name de l’entrée selon le même nommage que celui des sidecars — <component>--<container-name> pour un nom ordinaire ; une entrée qui omet name prend le nom positionnel init-<index> que documente la référence Workload, et est nommée à partir de celui-ci.
L’ordre que promet le contrat de rédaction — les init containers s’exécutent jusqu’à complétion dans l’ordre où ils sont écrits, et tout autre conteneur ne démarre qu’une fois qu’ils ont tous terminé — est exprimé avec la forme longue de depends_on :
- Chaque service d’initialisation après le premier attend son prédécesseur avec
condition: service_completed_successfully. - Le service principal, et chaque service sidecar, attend le dernier service d’initialisation avec la même condition. Attendre le dernier suffit, car les services d’initialisation forment une chaîne.
- Chaque service d’initialisation porte
restart: "no". Un service d’initialisation s’exécute une fois ; un service qui redémarrerait n’atteindrait jamais l’état terminé qu’attendent ses dépendants, de sorte qu’unerestartPolicyécrite sur un init container n’y change rien.
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"Un init container est traduit exactement comme tout autre conteneur : son image (y compris la réécriture de registre qu’applique une annotation aggrega.ai/image-registry), command, args, variables, attachments, volumeMounts et securityContext atteignent tous le service d’initialisation. C’est ce qui permet à la configuration que porte un init container — le plus souvent un fichier qu’il monte et écrit dans un volume que le conteneur principal monte aussi — de survivre sur la cible compose plutôt que d’être perdue avec le conteneur. Une forme que compose ne peut pas exprimer échoue de la même façon pour un init container que pour un conteneur ordinaire : un lifecycle ou un envFrom déclaré arrête le build avec une erreur TRANSLATION_ERROR qui nomme l’init container dont il provient.
Deux différences par rapport au service principal découlent du fait qu’un service d’initialisation est un service non principal :
- Les champs du Workload au niveau du pod ne sont pas appliqués, la même règle que suivent les sidecars — à l’exception de l’utilisateur du pod, qui atteint chaque service comme le décrit Champs au niveau du pod.
- Un service d’initialisation rejoint directement le réseau de sa frontière au lieu de partager le namespace réseau du service principal comme le fait un sidecar. Il le doit : le service principal attend le service d’initialisation, et partager un namespace est en soi une dépendance envers le service principal, qui refermerait l’attente en un cycle que compose refuse de démarrer. Un init container atteint donc les autres services sur le réseau de la frontière par leur nom de service, mais il ne partage pas le
localhostdu service principal.
Les services d’initialisation et les services sidecar partagent un même espace de noms, parce qu’un seul nommage nomme les deux, de sorte qu’une entrée initContainers et une entrée containers ne peuvent pas porter le même nom. Lorsque c’est le cas, le compilateur s’arrête avec un TRANSLATION_ERROR qui nomme le nœud, le nom du conteneur et le nom de service que tous deux voulaient, plutôt que de laisser un service remplacer discrètement l’autre.
L’émission de la condition de complétion n’élève aucune version minimale de Compose. condition et ses valeurs appartiennent à la Compose Specification de base — contrairement aux champs restart et required qui les accompagnent dans le même bloc en forme longue, que la spécification lie à des versions particulières de Compose. Chaque version minimale que demande la sortie du fournisseur compose accompagne la construction qui en a besoin : ≥ 2.23.1 pour configs.content inline, ≥ 2.26.0 pour le subPath d’un montage (voir Volumes), et 2.38 pour les modèles. La première concerne toute sortie compose qui porte une config avec content: inline, ce qui est la façon dont arrivent à la fois le fichier derrière un volume configmap et la config derrière une arête inter-réseaux pontée — et non un seul chemin de rédaction.
Quel réseau un service rejoint
Chaque service rejoint un réseau Docker ; les sidecars en héritent par leur référence network_mode au service principal. Le réseau sur lequel atterrit un nœud est lu dans l’annotation aggrega.ai/namespace de ce nœud, avec repli sur le chemin du fichier compose lorsque le nœud ne porte pas cette annotation — le répertoire dans lequel le fichier est écrit sous le répertoire de sortie du build, comme bridge/compose pour une frontière dont le directory: est bridge. Ainsi, chaque nœud sans l’annotation dans un fichier compose rejoint un seul réseau nommé d’après le chemin du fichier, quelle que soit la frontière où il se trouve : les frontières non annotées qui partagent un fichier compose partagent ce réseau, et c’est aggrega.ai/namespace qui les sépare. Les nœuds qui portent des annotations différentes atterrissent sur un réseau par annotation distincte. Comment un nom de réseau est dérivé est le nom que produit cette identité.
Comment un nom de réseau est dérivé
Un réseau compose est une connectivité L3 partagée, et le bloc networks: de premier niveau fusionne ses entrées par nom — deux identités qui aboutissent à un même nom deviennent donc un seul réseau sur lequel se trouvent les deux ensembles de services, qui s’atteignent mutuellement par nom de service, sans rien dans le fichier émis pour montrer que deux réseaux étaient prévus. Le nom est donc construit à partir de l’identité qui dit de quel réseau il s’agit : l’annotation aggrega.ai/namespace du nœud, ou le chemin du fichier compose lorsque le nœud n’en porte aucune.
Un nom de réseau compose accepte un ensemble de caractères plus restreint que celui que chacune des identités peut contenir : lettres, chiffres, points, tirets bas et traits d’union. Plutôt que de remplacer un caractère que compose n’accepte pas, la dérivation l’écrit en toutes lettres, de sorte que deux identités qui diffèrent si peu que ce soit aboutissent à deux réseaux — et un nom peut être relu pour retrouver l’identité à partir de laquelle il a été construit.
- Une lettre, un chiffre, un point et un tiret bas sont repris exactement tels qu’ils ont été écrits, dans la casse où ils ont été écrits. Ainsi,
prodetProdsont deux réseaux, et non un seul. - Un trait d’union est conservé tel qu’il a été écrit partout où le caractère qui le suit est repris directement et n’est pas un
zminuscule. Un trait d’union suivi d’unzminuscule ouvre une séquence d’échappement, de sorte qu’un trait d’union écrit à cette position est lui-même écrit en toutes lettres —api-zonedevientapi-zhzone, ce qui permet de relire n’importe quel nom sans deviner. Un trait d’union suivi de rien est écrit en toutes lettres pour la même raison, de sorte quedb-donnedb-zh. - Tout autre caractère est écrit comme
-zsuivi d’une lettre qui le nomme :spour un séparateur de chemin,hpour un trait d’union que la règle ci-dessus ne conserve pas. Tout le reste — y compris une espace et une lettre non ASCII — est écrit commexsuivi du point de code hexadécimal à six chiffres du caractère, et un octet qui ne commence aucun caractère commebsuivi de sa propre valeur à deux chiffres, de sorte qu’une identité qui n’est pas un texte valide est quand même écrite de façon distincte plutôt que confondue avec une autre. - Une identité totalement absente — un nœud sans annotation
aggrega.ai/namespacedans un fichier compose sans chemin — est écrite-ze, ce qu’aucune identité écrite par un auteur ne peut produire. Un réseau sans identité ne partage donc jamais la connectivité avec un réseau dont l’identité est écrite d’une façon particulière.
Ainsi, un namespace prod donne le réseau prod, core-net donne core-net, et un fichier compose à dist/app/compose donne dist-zsapp-zscompose. Une entrée identique produit toujours le nom identique.
Un namespace et le chemin d’un fichier compose sont écrits dans le même espace. Ce sont deux façons de nommer la même chose — le réseau sur lequel se trouve un nœud — de sorte qu’un nœud dont le namespace est app/compose et un nœud sans namespace dans le fichier compose à app/compose atterrissent délibérément sur un même réseau, exactement comme le font deux frontières qui portent la même annotation aggrega.ai/namespace. Si vous voulez séparer deux nœuds, donnez-leur des identités qui diffèrent.
Changer l’identité d’un nœud renomme le réseau compose, et compose ne renomme pas un réseau sur place. Le réseau est créé à neuf sous le nouveau nom et chaque service qui s’y trouve est recréé pour s’y connecter, tandis que l’ancien réseau reste derrière jusqu’à ce que quelque chose le supprime. Un réseau ne porte aucune donnée, donc rien n’est perdu — mais les conteneurs qui s’y trouvent redémarrent bel et bien, et tout ce qui maintient une connexion à travers le changement la voit tomber. Traitez le changement d’une annotation de namespace, ou du répertoire dans lequel un fichier compose est écrit, comme un redéploiement à planifier plutôt que comme une valeur à ajuster sur place.
Lorsque deux frontières se rejoignent dans un même chemin d’assemblage (directory: partagé), leurs nœuds sans annotation aggrega.ai/namespace partagent l’unique réseau du fichier ; donnez à chaque frontière sa propre annotation aggrega.ai/namespace et le docker-compose.yaml fusionné déclare une entrée networks: de premier niveau par annotation. Les services de frontières différentes au sein d’un même fichier compose peuvent communiquer par leurs noms de service dans le cadre de la résolution DNS par défaut de compose, sous réserve des propres règles d’accessibilité inter-réseaux de compose. Le routage L4 inter-réseaux au sein d’un seul fichier compose est ce que permet la Feature compose-bridge de la bibliothèque standard, en tant que contenu de catalogue dont ce fournisseur ne détient aucune logique : rattachée à la frontière ancêtre commune, sa FeatureRecipe dérive une passerelle des arêtes uses de la frontière dont les deux extrémités sont assemblées dans son propre fichier compose et se trouvent sur des réseaux différents de celui-ci — un service aggrega-gw dont la config nginx stream sert de proxy à chaque arête pontée (un bloc server par arête, sur le port de la cible avec un repli portBase en cas de collision) — et son propre injectMapping réécrit la variable d’environnement d’hôte de chaque consommateur en aggrega-gw:<port>, ou en aggrega-gw avec la variable de port réécrite vers le port d’écoute lorsque la même connexion fournit les deux. Cette réécriture remplace la valeur que la propre connexion du consommateur a fournie ; si une autre Feature rattachée au consommateur a fourni la même variable, le build s’arrête en nommant les deux plutôt que de la remplacer. Le valuesMapping de la FeatureRecipe écrit cette config sous la forme d’une config compose montée — une entrée configs: de premier niveau avec content: inline, référencée depuis la passerelle et montée à /etc/nginx/nginx.conf ; ce n’est pas un montage dont l’opérateur a la charge — et nomme chaque endpoint ponté sous le x-aggrega-networks-of de la passerelle, que ce fournisseur résout en réseaux sur lesquels ces endpoints sont placés (ci-dessous). Une arête dont les deux extrémités sont assemblées dans deux fichiers compose n’est pas pontée et conserve le nom propre de la cible ; une frontière qui n’a rien à ponter porte quand même la passerelle inactive, sans config et sans réseau autre que le sien ; et un bridge rattaché à une frontière dont le fichier compose ne contient aucun composant arrête le build plutôt que d’écrire la passerelle nulle part. La config stream porte une directive resolver et fait office de proxy via une variable par arête (set $uN <host>; proxy_pass $uN) afin que chaque upstream soit résolu au moment de la connexion plutôt qu’une seule fois au démarrage — sinon, un simple proxy_pass vers une cible pas encore démarrée ferait échouer la passerelle au démarrage. (Le $ de ces variables est échappé en $$ dans configs.content afin que l’interpolation $ propre à Docker Compose laisse un $ littéral pour nginx.) configs.content inline nécessite Docker Compose ≥ 2.23.1. Voir le modèle compose-bridge.
Rejoindre les réseaux d’autres composants — x-aggrega-networks-of
Un service qu’écrit un fragment — un fichier compose issu d’une source une fois sa surcouche fusionnée, ou un corps artifacts: — peut rejoindre les réseaux d’autres composants assemblés dans le même fichier compose en les nommant sous la clé d’extension x-aggrega-networks-of : une liste d’identifiants de composants, les identifiants que l’Aggregate donne à ses composants, qu’une FeatureRecipe de portée frontière lit comme les clés de .boundary.components et comme le source et le target de ses listes d’arêtes .boundary. Le fournisseur résout chaque identifiant en réseau sur lequel ce composant est placé dans ce fichier, selon le même placement que reçoit chaque nœud, et ajoute ces réseaux au service, chacun une seule fois et dans l’ordre des noms, avant le réseau propre du service, qu’il rejoint toujours. La clé elle-même est omise du fichier assemblé. Le fournisseur lit les identifiants comme des références à résoudre et rien de ce que fait le service, de sorte que toute Recipe ou FeatureRecipe peut utiliser la clé ; la passerelle du bridge compose rejoint ainsi les réseaux des endpoints entre lesquels elle relaie.
# 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-zscomposeTrois choses arrêtent le build avec TRANSLATION_ERROR lors de l’assemblage du fichier, chacune en nommant le service :
- Un identifiant qu’aucun composant assemblé dans ce fichier ne porte — un composant assemblé dans un autre fichier compose, par exemple. Un réseau appartient à un seul fichier, de sorte que le message nomme l’identifiant et le fichier dans lequel se trouve le service. Ne nommez que des composants assemblés dans le même fichier, ou supprimez l’identifiant.
- Une valeur qui n’est pas une liste de chaînes. La clé prend une liste d’identifiants de composants, même pour un seul identifiant.
- La clé sur un service qui écrit
network_mode. Compose ne permet pas à un service doté d’unnetwork_modede rejoindre des réseaux ; supprimez l’un des deux.
Inférence de depends_on
Le fournisseur compose dérive automatiquement depends_on des arêtes uses de l’IR. Pour chaque arête dont la source et la cible apportent toutes deux des services au fichier compose fusionné, le fournisseur ajoute depends_on: [<target>] au service source.
La dépendance porte sur le service propre du composant source, et sur aucun autre service que ce composant apporte. Un composant qui déclare aussi des init containers apporte un service exécuté jusqu’à son terme par entrée, et aucun d’eux ne reçoit la dépendance dérivée de l’arête — une arête nomme le composant, et un service d’init porte un nom qui lui est propre. Ainsi, un init container qui doit atteindre la cible de l’arête, comme une migration de schéma vers une base de données que le composant cible par uses, ne porte aucun ordonnancement par rapport à cette cible et peut s’exécuter avant qu’elle soit joignable, tandis que le service propre du composant attend à la fois que la chaîne d’init se termine et que la cible ait démarré.
Les entrées dérivées des arêtes sont émises sans condition : elles ont la sémantique service_started, que la cible déclare ou non un healthcheck. Les conditionner à la santé de la cible — ce qui permettrait au runtime compose de bloquer le démarrage jusqu’à ce que le healthcheck de la cible se signale en bonne santé — est exprimable, et une arête uses ne le demande pas. Une vague qui nomme la même paire est la seule chose qui change la condition d’une entrée dérivée d’une arête, et elle le fait parce que la vague le demande, et non parce que l’arête le demande.
Les entrées dérivées des arêtes sont émises dans l’ordre alphabétique des cibles pour la stabilité de la sortie. Les arêtes dont la source ou la cible est servie par un autre fournisseur (helm ou helm-chart) sont ignorées — depends_on ne s’applique qu’au sein du sous-ensemble de la Release servi par compose.
Le depends_on d’un service est émis sous l’une des deux formes de compose, jamais sous un mélange des deux, car compose exige une condition sur chaque entrée de la forme longue :
- Liste en forme courte (
depends_on: [<service-name>]) lorsqu’aucune entrée de ce service ne porte de condition. C’est le cas de tout service dont les seules dépendances proviennent d’arêtesuses. - Mapping en forme longue lorsqu’une entrée quelconque en porte une — ce qui arrive lorsque le service attend aussi un init container, ou lorsqu’une vague de déploiement l’ordonne. Les entrées dérivées des arêtes y émettent alors la
condition: service_startedexplicite, que la Compose Specification définit comme l’équivalent de la forme courte, de sorte que leur sens reste inchangé.
Au sein d’un service, les sources conservent leur propre ordre et ne s’entremêlent pas : l’attente de la chaîne d’init, dont l’ordre est celui dans lequel l’auteur a écrit la liste, est émise en premier, puis les entrées dérivées des arêtes, par ordre alphabétique, puis celles dérivées des vagues, par ordre alphabétique.
Ordre par vagues de déploiement
La valeur syncWave: d’une frontière de Release ordonne les services du fichier compose dans lequel cette frontière est rendue. Chaque composant de la frontière hérite de la vague de la frontière, et lorsque plusieurs frontières partagent un même directory: — de sorte que leurs contributions se fondent en un seul docker-compose.yaml —, le fichier fusionné contient plus d’une vague et le fournisseur exprime l’ordre entre elles sous forme de depends_on.
Chaque service attend chaque service de la vague immédiatement précédente qui contient des services, et aucune vague antérieure à celle-ci. Compose résout le reste de manière transitive : un service de la vague 2 attend la vague 1, qui attend la vague 0, de sorte que toute la séquence est ordonnée tandis que la liste propre à chaque service reste de la taille d’une seule vague plutôt que du fichier entier. Les vagues n’ont pas besoin d’être contiguës, et les valeurs négatives sont ordinaires — -1 est un choix courant pour une migration qui s’exécute avant tout le reste.
La condition dépend de ce que la cible peut satisfaire. Une vague signifie que le groupe précédent est opérationnel avant que le suivant ne démarre, ce qui relève de la disponibilité plutôt que du lancement du processus, donc :
- lorsque le service cible déclare un
healthcheck, l’attente estcondition: service_healthy; - lorsqu’il n’en déclare pas, l’attente est
condition: service_started, car un service sans healthcheck ne peut jamais se signaler en bonne santé et une attente conditionnée à sa santé ne serait jamais satisfaite — le fichier ne démarrerait jamais.
La condition la plus faible est visible dans le fichier émis à côté de la plus forte, et le build nomme en outre chacun de ces services dans un avertissement, de sorte qu’un auteur qui attendait un ordonnancement par disponibilité apprend quelle partie de la vague qu’il a déclarée n’arrive que comme ordonnancement de démarrage. L’avertissement est consultatif : le build réussit et les octets rendus sont exactement ce qu’ils seraient sans lui. Ajouter un bloc health: à ce conteneur est ce qui renforce l’attente. --no-unsupported-field-warnings réduit la classe au silence.
La vague reste enregistrée comme label. L’ordonnancement est ajouté à côté du label aggrega.ai/sync-wave, et non à sa place : le label est l’endroit où un lecteur qui inspecte le fichier émis voit de quelle vague provient un service, ce que les entrées depends_on n’indiquent pas.
Lorsqu’une vague et une arête uses nomment la même paire, une seule entrée porte les deux. Compose accepte une entrée par dépendance, de sorte qu’un service qui utilise une cible par uses et se situe aussi une vague après elle émet une seule entrée conditionnée par la condition de la vague — l’exigence de la vague est la plus forte des deux et c’est celle qui est exprimée.
Une frontière dont tous les composants se trouvent dans une même vague n’émet rien à ce titre. Il en va de même pour une Release qui ne déclare aucun syncWave : chaque contributeur porte la valeur par défaut du champ, 0, le fichier fusionné contient une seule vague, et la sortie est exactement ce qu’elle serait si le fournisseur n’exprimait aucun ordre de vagues.
L’ordre entre deux fichiers compose n’est pas exprimable, et il n’est pas approximé. depends_on nomme un service à l’intérieur du même fichier, et les frontières qui s’évaluent en chemins d’assemblage distincts produisent des fichiers docker-compose.yaml distincts que le runtime compose traite comme des projets indépendants. Une vague ordonne donc chaque service du fichier dans lequel elle est rendue, et rien en dehors. Séquencer deux projets compose relève de l’opérateur, de la même manière que le routage entre fichiers ; déclarer un directory: partagé est ce qui amène deux frontières dans un seul fichier, et c’est une décision de forme de sortie à prendre pour ses propres raisons plutôt que pour obtenir un ordre.
Une arête uses pointant vers une vague ultérieure est émise telle qu’écrite, et signalée. Le depends_on émis reflète ce qui a été déclaré — à la fois les arêtes uses et les vagues. Une arête dont le consommateur se trouve dans une vague antérieure à celle de la cible qu’il utilise affirme le contraire de ce qu’affirment les vagues : l’arête oblige le consommateur à attendre la cible, tandis que les vagues obligent la cible, à travers chaque vague entre eux, à attendre le consommateur. Le fichier fusionné exprime les deux, ce qui forme un ensemble de dépendances circulaires que Docker Compose refuse de démarrer. Le build nomme chacune de ces arêtes dans un avertissement indiquant les deux services et les deux vagues, de sorte que le cycle apparaît au moment du build plutôt qu’à docker compose up. L’avertissement est consultatif — le build réussit et les octets rendus sont exactement ce qu’ils seraient sans lui — et --no-unsupported-field-warnings ne le réduit pas au silence, car rien n’a été écarté : les deux déclarations sont chacune exprimées, et ensemble elles ne peuvent pas démarrer. Il ne couvre que la paire directe : il nomme les deux services qu’une arête relie plutôt que de retracer tout le cycle. Tout cycle construit à partir d’arêtes uses et de vagues ensemble passe par au moins une telle arête, il est donc toujours signalé ; un cycle formé uniquement d’arêtes uses, sans vague impliquée, et un cycle fermé par une entrée depends_on écrite dans un fichier compose que fournit la Recipe sont émis tels qu’écrits et ne sont pas signalés. Gardez cohérents le sens des arêtes et l’ordre des vagues : placez le consommateur dans la vague de la cible ou dans une vague ultérieure, ou la cible dans la vague du consommateur ou dans une vague antérieure.
# 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 ne nomme pas migrator : l’ordonnancement atteint la vague immédiatement précédente et compose enchaîne le reste à travers store.
Mode avec source
Le source: du fournisseur compose nomme un fichier YAML docker-compose que le fournisseur peut lire et analyser, et il accepte les deux formes que prend le champ source: : une simple chaîne de chemin du système de fichiers, et un objet structuré dont le url: porte l’emplacement. Partout où cet emplacement est un chemin du système de fichiers, il est ancré au répertoire qui contient le recipe.yaml qui le déclare, et non au répertoire depuis lequel le build est invoqué, et il doit rester à l’intérieur de ce répertoire : un chemin qui en sort, ou un chemin absolu, est refusé, car chaque fichier qu’emporte une publication de la Recipe est pris dans son répertoire — voir entities/recipe.md « Content paths stay inside the Recipe’s own directory (Les chemins de contenu restent dans le répertoire propre de la Recipe) ». Le fichier ainsi nommé est publié avec la Recipe, tandis qu’un fichier à côté de la Recipe que rien de ce qu’elle déclare ne nomme ne l’est pas.
spec: capability: compose source: ./docker-compose.base.yaml # filesystem path to the base compose file valuesMapping: | services: api: image: "{{ .values.image }}"Dans la forme structurée, ce que porte url: décide si quelque chose est récupéré. Un fragment publié via https:// est récupéré et épinglé avec kind: compose-https-fragment ; aggrega pull l’acquiert et le build le lit depuis le cache. Un url: qui nomme un chemin du système de fichiers n’est pas récupéré — il est lu depuis le disque, ancré exactement comme la forme en simple chaîne ci-dessus, et aggrega pin enregistre le digest du fichier qu’il nomme dans le fichier entity.lock à côté de la Recipe, qu’un build compare ensuite avant que le fragment soit lu. Copier localement un fragment distant (vendoring) et faire pointer source: vers la copie locale est pris en charge comme alternative à la récupération, et n’est pas obligatoire. Le schéma accepte un objet structuré ouvert.
Une Recipe avec source: <path-to-compose-file> et valuesMapping: exécute le pipeline suivant :
- Le fichier compose de base situé à
<path>est lu et analysé en tant que YAML. - Le template
valuesMappingest évalué par rapport au contexte de template de la Recipe. Sa sortie est traitée comme un document de surcouche compose — un fichier compose partiel qui complète ou remplace des champs de la base. - La base et la surcouche sont fusionnées en profondeur selon la sémantique de surcouche native de docker-compose.
Les règles de la fusion en profondeur :
- Scalaires : la surcouche l’emporte. Lorsque la base et la surcouche définissent toutes deux le même champ scalaire, la valeur de la surcouche remplace la valeur de la base.
- Tables : fusion récursive. Lorsque la base et la surcouche définissent toutes deux le même champ de type table, la fusion descend récursivement dans la table. Les clés présentes dans les deux suivent les mêmes règles ; les clés présentes dans une seule sont conservées telles quelles.
- Listes : remplacement. Lorsque la base et la surcouche définissent toutes deux le même champ de type liste, la liste de la surcouche remplace entièrement la liste de la base (aucune fusion élément par élément ni ajout en fin). Cela correspond au comportement de
docker compose -f base.yaml -f overlay.yaml config. null: remplace, et reste. Une clé que la surcouche définit ànullsur un service — l’une des clés propres du service, commeuser,commandouhealthcheck, une entréeenvironment, un label, ou une clé directement soushealthcheckoudeploy— remplace la valeur de la base comme n’importe quel scalaire et est écrite dans le fichier compose sous la formekey: null; elle ne supprime pas la clé. Lorsque le fournisseur écrit une valeur qui lui est propre dans cette clé, le fichier porte à la place la valeur du fournisseur :labels: nulllaisse les labels de provenance que le fournisseur appose, etnetworks: nullle réseau qu’il attache. Unnullécrit n’importe où ailleurs dans la surcouche est hors de cette règle. Ce que signifie ensuite unnullrelève de la lecture que Compose fait de cet attribut — une entréeenvironmentsans valeur, par exemple, prend sa valeur dans l’environnement où s’exécutedocker compose.
Chaque label écrit par l’auteur d’un service est conservé. Les labels: d’un service dans le fichier de base ou dans la surcouche peuvent être écrits sous forme de table ou de liste d’entrées key=value de Compose, et chaque label atteint le fichier compose à côté des labels de provenance que le fournisseur appose. Une entrée de liste est lue comme Compose la lit : le texte avant son premier = nomme le label et le texte après est la valeur, et une entrée sans = est un label à valeur vide. Un nombre ou une valeur true/false est écrit sous forme de son texte, de sorte que replicas-hint: 2 atteint le fichier sous la forme replicas-hint: "2", et un label écrit null reste null. Lorsqu’un label écrit par l’auteur et un label de provenance partagent une clé, le fichier porte la valeur de provenance. Une valeur labels: qui n’est ni une table ni une liste, et une entrée de liste qui n’est pas du texte, arrêtent le build, en nommant le fichier source et le service. Les labels de service d’un corps artifacts: prennent la forme de table : une liste à cet endroit arrête le build, en nommant l’artefact et le service.
Le document fusionné rejoint ensuite la fusion au niveau de la Release aux côtés des éventuelles contributions en mode synthétisé, avec le même réseau par frontière et la même inférence de depends_on.
Laisser de côté des services, des volumes et des configs. La surcouche ne peut rien supprimer du fichier de base — une valeur de surcouche remplace, elle ne supprime jamais — donc un fichier récupéré qui embarque un service que la Release ne doit pas exécuter est précisément ce à quoi servent les entrées omits: d’une Recipe ou d’une FeatureRecipe. Ce fournisseur les respecte dans ce mode et dans aucun autre : un Workload synthétisé et un corps artifacts: sont rendus sans elles. Une entrée nomme une unité de premier niveau du fichier par son kind — service, volume ou config — et son name, la clé de l’unité sous services:, volumes: ou configs:, comparée exactement. Un fichier compose n’a pas d’espaces de noms, donc une entrée portant un namespace, comme une entrée nommant tout autre type, arrête le build lorsque le composant est rendu, en nommant l’entrée et les types que ce fournisseur accepte ; chaque entrée est vérifiée avant que quoi que ce soit soit laissé de côté. Les entrées sont confrontées au fichier une fois que la surcouche ci-dessus y a été fusionnée, de sorte qu’une unité ajoutée par la surcouche est laissée de côté exactement comme une unité déclarée par la base, et avant que le fournisseur n’ajoute quoi que ce soit qui lui soit propre, de sorte qu’une entrée ne nomme jamais cela. Une unité nommée par une entrée est supprimée, et une section dont chaque unité est laissée de côté est supprimée avec elles ; toute autre unité est écrite exactement comme elle le serait sans les entrées. Les entrées atteignent le fichier de la Recipe ou de la FeatureRecipe qui les déclare, et rien d’autre : ce qu’un autre composant ou une Feature rattachée apporte au même docker-compose.yaml reste intact, y compris une unité ayant la même clé. Le fournisseur indique combien d’unités chaque entrée a laissées de côté, et une entrée qui n’en a laissé aucune arrête le build ; voir An omits entry left out nothing the source rendered (Une entrée omits n’a rien laissé de côté de ce que la source a rendu).
Une unité laissée de côté ne doit pas rester nommée par ce qui reste, car compose refuse un fichier qui nomme un service, un volume ou une config qu’il ne déclare pas. Une fois les unités supprimées, chaque référence que le fichier fait encore à l’une d’elles arrête le build, et le message nomme chaque service ou job qui fait la référence, l’unité qu’il nomme et le champ dans lequel se trouve la référence. Une référence est ce que la Compose Specification définit comme une entrée d’un fichier qui en nomme une autre :
- un service, nommé par
depends_onsous l’une ou l’autre forme, parlinks(SERVICEouSERVICE:ALIAS), parvolumes_from(SERVICEouSERVICE:MODE), parnetwork_mode,ipc,pidouutsdéfini àservice:<name>, parextendsnommant un service du même fichier, ou par une valeurservice:<name>debuild.additional_contexts; - un volume, nommé comme source d’une entrée
volumes:— la forme courteSOURCE:TARGEToù la source est un nom plutôt qu’un chemin, et la forme longue detype: volume; - une config, nommée par une entrée
configs:, sous l’une ou l’autre forme.
Les hooks pre_start d’un service et chaque entrée jobs: de premier niveau sont également lus, pour les références que la spécification permet à chacun d’eux de porter. Certaines valeurs ne font que ressembler à des références et ne sont pas lues comme telles : une entrée volumes_from ou network_mode commençant par container: nomme un conteneur, external_links nomme un conteneur que ce fichier ne déclare pas, un extends avec un file: nomme un service d’un autre fichier, et un credential_spec.config peut nommer une config détenue par la plateforme plutôt que par le fichier. Chaque valeur est comparée telle qu’elle est écrite, de sorte qu’une référence écrite au moyen d’un ${VARIABLE} n’est pas une référence que cette vérification voit, et qu’une référence à une unité que le fichier n’a jamais déclarée est laissée telle quelle.
La vérification lit uniquement le fichier propre de la Recipe ou de la FeatureRecipe qui déclare, de sorte qu’une référence à un service laissé de côté arrête le build même là où un autre contributeur au même chemin d’assemblage déclare un service portant ce nom. Pour conserver la référence, conservez l’unité. Pour la supprimer, modifiez l’entrée qui fait la référence via valuesMapping: — une liste à cet endroit remplace la liste du fichier de base, donc depends_on: [] en vide une — ou laissez aussi de côté le service qui fait la référence.
Sortie par (path, provider)
Chaque chemin d’assemblage compose produit un docker-compose.yaml. Les frontières qui s’évaluent en chemins distincts produisent des fichiers compose distincts ; les frontières qui partagent un chemin évalué produisent un seul fichier compose fusionné contenant chaque contributeur à ce chemin. Le chemin est le directory: de la frontière joint au subDirectory: propre à chaque composant (dont la valeur par défaut est {{ .capability }}, de sorte que les contributeurs compose aboutissent par défaut dans un sous-dossier compose/).
Les collisions de noms de service au sein d’un même chemin d’assemblage arrêtent le build. Lorsque deux nœuds différents contribuent des services ayant le même ID d’instance au même tuple (path, provider), le compilateur s’arrête et le diagnostic nomme chaque tuple (boundary, node) contributeur par ordre alphabétique. L’auteur résout la collision en renommant l’un des contributeurs (généralement en ajustant l’identifiant du nœud pour que le synthétiseur produise un nom de service différent), ou en dirigeant les contributeurs vers des chemins distincts au moyen de déclarations directory: différentes.
Les volumes de premier niveau fusionnent au sein d’un chemin d’assemblage, et deux contributeurs peuvent déclarer un même nom à condition d’être d’accord à son sujet. Un contributeur est un fragment, donc deux fragments d’un même composant — son propre fichier compose et une entrée artifacts:, ou deux entrées artifacts: — sont deux contributeurs exactement comme le sont deux composants. Un volume nommé est un seul volume physique, donc deux déclarations identiques décrivent toutes deux exactement l’entrée que contient finalement le fichier assemblé, et celui-ci garde une seule entrée sous ce nom. Un volume que le fournisseur a dérivé ne porte aucun corps, donc deux d’entre eux s’accordent trivialement, et ils ne peuvent de toute façon pas se rencontrer (voir Comment un nom de volume est dérivé).
Une entrée volumes: rédigée par l’auteur est celle à surveiller, car elle peut porter un corps qui lui est propre — un driver, des driver_opts ou des labels. Lorsque deux contributeurs déclarent un même nom avec des corps différents, le build s’arrête avec TRANSLATION_ERROR, en nommant le volume et chaque tuple (boundary, node, fragment) contributeur. Lorsque deux auteurs sont en désaccord sur un même volume, l’assembleur n’a aucune réponse entre laquelle choisir : garder l’un ou l’autre corps écarte ce que l’autre auteur a écrit, d’un build qui réussirait autrement. Résolvez-le en rendant les deux déclarations identiques, lorsque les deux auteurs visaient le même volume, ou en renommant l’une d’elles, lorsqu’ils en visaient deux. Les réseaux de premier niveau sont un par annotation aggrega.ai/namespace distincte, plus un nommé d’après le chemin du fichier compose pour les nœuds qui n’en portent aucune, nommés selon Comment un nom de réseau est dérivé ; deux frontières contributrices avec la même annotation aggrega.ai/namespace fusionnent en un seul réseau partagé par les deux, tout comme deux frontières non annotées qui partagent le fichier.
Chaque clé qu’un fragment écrit est portée ou refusée
Un fragment — un fichier compose issu d’une source une fois sa surcouche fusionnée, ou un corps artifacts: qui s’évalue en YAML compose — n’atteint le docker-compose.yaml assemblé qu’à travers les clés que le fournisseur porte, et cet ensemble est fixe. Chaque clé qu’un fragment écrit est soit portée dans le fichier assemblé telle qu’elle est écrite, soit refusée nommément ; aucune n’est laissée de côté sans un mot. Un fragment est un seul fichier compose, il est donc un seul document YAML.
- Portées. Au premier niveau :
services,volumes,configsetmodels. Sur un 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_hostsetprofiles. À l’intérieur des blocs que le fournisseur décrit :deploy.resourcesavec seslimits(cpus,memory) et sesreservations(cpus,memory,devices, et pour chaque entrée de périphériquedriver,count,device_ids,capabilitiesetoptions) ;test,interval,timeout,retriesetstart_periodd’unhealthcheck;type,source,target,read_onlyetvolume.subpathd’une entréevolumes:en forme longue ;sourceettargetd’une entréeconfigs:en forme longue ;conditiond’une entréedepends_on:en forme longue ;driver,driver_optsetlabelsd’un volume de premier niveau ;contentd’une config de premier niveau. Le corps d’un modèle et l’entréemodels:en forme longue d’un service portent chaque membre, comme le décrit Modèles. Un membre d’extension — une clé commençant parx-— est porté au premier niveau et sur un service, comme le décrit Membres d’extension. - Refusées. Toute autre clé —
stdin_opensur un service, unsecrets:ou unname:de premier niveau,deploy.replicas, unrestart:ou unrequired:dans une entréedepends_on:en forme longue, une cléx-dans le corps d’un volume de premier niveau ou d’unhealthcheck— arrête le build avecTRANSLATION_ERROR, en nommant chacune de ces clés, son chemin dans le fragment (services.migrate.stdin_open), le fragment et le composant, et nomme les deux endroits d’où provient une telle clé. L’un est le fragment lui-même, et la correction consiste à en retirer la clé. L’autre est une Recipe issue d’une source qui ne déclare aucunvaluesMapping:: les valeurs du nœud sont alors superposées au fichier compose telles quelles, de sorte que chaque clé de valeur arrive comme clé de premier niveau du fragment, et la correction consiste à déclarer unvaluesMapping:qui place chaque valeur sous une clé que le fournisseur porte. Une clé qu’une clé de fusion YAML (<<: *anchor) introduit dans un bloc est jugée là où elle arrive, comme si elle y était écrite. Un fragment rendu depuis la source s’appelle<component>.compose-fragment.yaml; un fragmentartifacts:porte le nom que lui donne sa Recipe. - Refusé en bloc : un réseau propre au fragment. Une entrée sous les
networks:de premier niveau d’un fragment arrête le build avecTRANSLATION_ERRORquel que soit le contenu de son corps — une entrée vide, undriver, quoi que ce soit d’autre — en nommant l’entrée (networks.back), le fragment et le composant, car le fichier assemblé ne contient que les réseaux que le fournisseur dérive (voir Quel réseau un service rejoint). Supprimez l’entrée : un service rejoint le réseau de son propre composant sans rien déclarer, l’annotationaggrega.ai/namespacechoisit quel réseau rejoint un composant, un service nomme les composants dont il rejoint aussi les réseaux sousx-aggrega-networks-of, et la Featurecompose-bridgeroute entre les services de réseaux différents. Unnetworks: {}vide ne déclare rien et n’est pas refusé, et la listenetworks:propre à un service est portée comme ci-dessus. - Refusé en bloc : un fragment de plus d’un document. Un corps
artifacts:contenant deux documents YAML ou plus séparés par---arrête le build avecTRANSLATION_ERROR, en nommant le fragment, le composant et le nombre de documents qu’il contient, car la fusion lit un fragment comme un seul fichier compose et chaque document après le premier serait sinon absent du fichier assemblé. Écrivez le fragment comme un seul document, ou donnez à chaque document sa propre entréeartifacts:. Un document qui ne contient rien — le document vide qu’ouvre un---final — n’est pas compté. Un fichier compose issu d’une source formé de plusieurs documents ne devient jamais un tel fragment : il est refusé à la lecture du fichier.
Le fournisseur ne lit le sens d’aucune clé : une clé est portée parce qu’elle fait partie de l’ensemble ci-dessus et refusée parce qu’elle n’en fait pas partie.
Les membres d’extension sont portés tels qu’ils sont écrits
La Compose Specification réserve les clés commençant par x- aux extensions : des données qu’un outil lisant le fichier peut utiliser et que Compose lui-même ignore. Les membres d’extension d’un fragment au premier niveau et sur un service atteignent le fichier assemblé tels qu’ils sont écrits, après chaque clé que le fournisseur modélise à ce niveau, dans l’ordre où le fragment les contient ; le fournisseur ne lit rien à l’intérieur, sauf le x-aggrega-networks-of d’un service, qu’il résout en réseaux que le service rejoint et qu’il laisse hors du fichier assemblé (voir Rejoindre les réseaux d’autres composants). Un corps artifacts: les contient dans l’ordre où il les écrit. Les clés d’un fichier compose issu d’une source atteignent son fragment par ordre de nom une fois sa surcouche fusionnée, donc ses membres d’extension sont écrits par ordre de nom.
# an artifacts: bodyx-owner: team-bservices: migrate: image: example/migrate:1 x-schedule: manualUn membre atteint par un alias YAML est écrit en entier, et aucune ancre n’est portée, de sorte que le fichier assemblé ne contient jamais un alias dont l’ancre lui manque ; c’est ce qui permet à un membre de premier niveau de contenir une ancre que la clé de fusion d’un service (<<: *base) fait intervenir. Les membres d’un service voyagent avec leur service. Les membres de premier niveau fusionnent au sein d’un chemin d’assemblage selon la règle que suivent les volumes : deux fragments écrivant un même membre avec le même contenu laissent une seule entrée, qu’ils l’écrivent en style bloc ou en style flux, et deux l’écrivant avec un contenu différent arrêtent le build avec TRANSLATION_ERROR, en nommant le membre et chaque tuple (boundary, node, fragment) contributeur — y compris deux fragments d’un même composant. Rendez les deux déclarations identiques, ou donnez à l’une d’elles un nom différent.
profiles conditionne un service à un profil Compose. Un service qui liste profiles: est un service que docker compose up laisse de côté sauf si l’un de ses profils est activé, et que docker compose run --rm <service> démarre à la demande — la forme compose d’une tâche exécutée à la demande. La liste est portée telle que le fragment l’écrit, dans son ordre :
# a sourced compose fileservices: migrate: image: example/migrate:1 profiles: [manual]Modèles
La section models: de premier niveau d’un fichier compose déclare les modèles d’IA qu’utilisent les services du fichier, et un modèle est accordé à un service par sa propre entrée models:. Le fournisseur porte les deux d’un fragment vers le docker-compose.yaml assemblé, dans la graphie propre à Compose, que le fragment soit un fichier compose issu d’une source ou un corps artifacts: qui s’évalue en YAML compose. Un Workload ne déclare aucun modèle, donc une Recipe en mode Workload n’en apporte aucun.
- Le corps d’un modèle est écrit tel que le fragment l’a écrit.
model— l’identifiant d’artefact OCI du modèle —context_sizeetruntime_flagsgardent leurs noms, et tout autre membre, dont une extensionx-, est porté à côté d’eux. Au sein d’un modèle, les trois membres nommés viennent en premier et le reste suit par ordre de clé, et les modèles sont écrits par ordre de nom, de sorte qu’une entrée identique produit un fichier identique octet pour octet. Le fournisseur ne lit rien dans le corps : il ne vérifie pas l’identifiant, et il ne sait rien de ce qui servira le modèle. - La référence d’un service garde sa forme. La forme courte liste des noms de modèles (
models: [llm]) ; la forme longue associe chaque modèle àendpoint_varetmodel_var, les noms des variables qui reçoivent l’adresse du model runner et l’identifiant du modèle. L’une comme l’autre est écrite dans la forme et l’ordre qu’a utilisés le fragment, et voyage avec son service. Lorsque la forme longue laisse une variable sans nom, Compose la nomme lorsqu’il exécute le fichier. - Les modèles fusionnent au sein d’un chemin d’assemblage, selon la règle que suivent les volumes. Deux contributeurs déclarant un même nom de modèle avec des corps émis de façon identique laissent une seule entrée sous ce nom ; deux le déclarant avec des corps différents arrêtent le build avec
TRANSLATION_ERROR, en nommant le modèle et chaque tuple(boundary, node, fragment)contributeur. Deux fragments d’un même composant sont ici aussi deux contributeurs. Rendez les déclarations identiques lorsque les deux contributeurs visent un même modèle, ou donnez à l’une d’elles un nom différent. - Chaque référence nomme un modèle déclaré. Une fois les fragments du chemin d’assemblage fusionnés, un service auquel est accordé un modèle qu’aucun contributeur à ce chemin ne déclare arrête le build avec
TRANSLATION_ERROR, en nommant le service et le modèle. La vérification porte sur la fusion complète, de sorte qu’un composant peut accorder à son service un modèle qu’un autre composant au même chemin d’assemblage déclare. - Une entrée
omits:ne peut pas laisser de côté un modèle.service,volumeetconfigsont les types que ce fournisseur accepte, et une entrée nommant un modèle arrête le build comme une entrée nommant tout autre type.
Les modèles sont servis lorsque le fichier s’exécute, et non lors du build. Docker Compose 2.38 ou ultérieur, sur une plateforme qui prend en charge les modèles Compose comme Docker Model Runner, récupère et exécute chaque modèle accordé à un service, en laissant de côté tout autre sauf démarrage avec --all-resources, et définit, dans chaque service auquel il est accordé, les variables que nomme sa référence sur l’adresse du model runner et l’identifiant du modèle. Le build ne peut pas voir l’hôte qui exécutera le fichier, il ne vérifie donc ni la version de Compose ni la plateforme : un fichier portant des modèles s’assemble de la même façon, quel que soit ce qui l’exécute.
Une Feature rattachée à un composant contribue au même fichier
Une Feature rattachée à un composant apporte ses services au docker-compose.yaml dans lequel son composant hôte est assemblé, aux mêmes conditions que la propre Recipe de l’hôte. Il n’y a pas de second fichier à côté : un chemin d’assemblage produit un seul document, si bien que les services d’une Feature rattachée sont soit dans ce document, soit pas déployés du tout. Détacher la Feature retire exactement ces services et laisse intacts ceux du composant hôte.
Ce sont des contributeurs à ce chemin d’assemblage comme les autres, si bien que tout ce qui précède s’applique à eux sans changement — la règle des noms de service, et l’exigence que deux contributeurs déclarant un même nom de volume ou de config de premier niveau s’accordent sur ce qu’il est. Ils rejoignent aussi le même réseau que le reste de la frontière, de sorte qu’un composant et une Feature qui lui est rattachée s’atteignent mutuellement par nom de service sans rien d’autre à déclarer.
Chaque service qu’une Feature apporte porte l’identité composée pour ce rattachement plutôt que celle du composant hôte, de sorte que les deux restent distinguables au sein d’un document auquel tous deux ont contribué. Labels et annotations explique comment cette identité est construite.
Il s’agit d’un mécanisme différent du bloc attachments: au niveau du conteneur d’un Workload, et il est facile de lire les deux comme un seul parce qu’ils partagent un mot. Rattacher une Feature à un composant ajoute des services au document assemblé ; l’entrée attachments: d’un conteneur lit des informations d’identification qu’un slot a publiées dans ce seul conteneur, et est traitée sous Champs du conteneur.
Fragments compose émis comme artefacts
Lorsque le bloc artifacts: d’une Recipe s’évalue en YAML compose — un fragment portant ses propres blocs services:, volumes:, configs:, models: ou networks: (chaque entrée inline ou chargée entrée par entrée via $import:) —, la fusion dans l’assemblage par (path, provider) suit des règles propres à chaque forme :
- Les
services:issus des artefacts fusionnent dans le fichier compose assemblé aux côtés des services par composant. Un nom de service apporté par deux composants différents au même chemin d’assemblage arrête le build, et le diagnostic nomme chaque contributeur. Une collision au sein d’un seul composant — entre le propre fragment d’artefact de ce composant et les services synthétisés pour lui — n’est pas détectée, et la contribution la plus tardive remplace la précédente ; gardez donc le nom d’un service rédigé dans un artefact distinct des noms<component>et<component>--<container-name>que produit le synthétiseur (voir Comment un service sidecar ou d’initialisation est nommé). - Les
volumes:issus des artefacts fusionnent dans le blocvolumes:de premier niveau. Deux entrées aboutissant à un même nom laissent une seule entrée sous ce nom lorsqu’elles le déclarent à l’identique, selon la même règle que les volumes par composant ; deux qui le déclarent différemment arrêtent le build, qu’elles proviennent de deux composants ou de deux fragments d’un même composant — deux de ses entréesartifacts:, ou l’une d’elles et le propre fichier compose du composant. Comme un fragment d’artefact écrit ses propres corps, c’est la voie sur laquelle deux contributeurs risquent le plus d’être en désaccord. Gardez le nom d’un volume rédigé dans un artefact distinct des autres à son chemin d’assemblage, y compris de la forme<component>--<volume-name>que produit la dérivation — à moins que deux contributeurs ne soient censés décrire un même volume partagé, auquel cas leurs déclarations doivent correspondre. - Les
configs:issus des artefacts fusionnent dans le blocconfigs:de premier niveau. C’est ainsi que le fichier derrière un volumeconfigmapatteint l’assemblage : le volume devient une référenceconfigs:au niveau du service qui nomme la configmap, et le fragment d’artefact déclare une entrée de ce nom aveccontent:inline. Une fois les fragments du chemin d’assemblage réunis, chaque référence au niveau du service doit se résoudre en une entrée déclarée, sinon le build s’arrête avecTRANSLATION_ERRORen nommant chaque référence non résolue — le service, le nom de la config et le chemin de montage. La vérification porte sur l’union complète plutôt que sur chaque composant, de sorte qu’un composant peut référencer une config qu’un autre composant au même chemin d’assemblage déclare. L’union se réconcilie par nom lorsque les contributeurs sont d’accord : deux qui déclarent un même nom de config avec uncontent:identique laissent l’unique entrée qu’ils ont tous deux décrite. Deux qui déclarent un même nom avec uncontent:différent arrêtent le build avecTRANSLATION_ERROR, en nommant la config et chaque tuple(boundary, node, fragment)contributeur, deux fragments d’un même composant compris — une entrée de config porte toujours un contenu, de sorte que conserver l’une ou l’autre déclaration écarterait un fichier qu’un auteur a écrit. Gardez un nom de config distinct à travers tous les contributeurs à son chemin d’assemblage, ou rendez les déclarations identiques lorsque deux contributeurs sont censés fournir un même fichier partagé. - Les
models:issus des artefacts fusionnent dans le blocmodels:de premier niveau, et la référencemodels:d’un service voyage avec son service, selon les règles de Modèles : deux contributeurs qui déclarent un même nom de modèle doivent le déclarer à l’identique, et chaque référence doit nommer un modèle que déclare un contributeur au chemin d’assemblage. - Les
networks:issus des artefacts sont refusés. Le fournisseur compose dérive les réseaux des annotations de la frontière (un réseau par annotationaggrega.ai/namespacedistincte, plus un réseau nommé d’après le chemin du fichier compose, que rejoint chaque nœud qui n’en porte pas, chacun nommé selon Comment un nom de réseau est dérivé), de sorte qu’une déclaration de réseau fournie par un artefact n’a pas sa place dans le fichier assemblé : toute entrée arrête le build, en nommant l’entrée et le fragment, selon les règles de Chaque clé qu’un fragment écrit est portée ou refusée. Retirez l’entrée et façonnez les réseaux au moyen de l’annotationaggrega.ai/namespace, ou faites rejoindre à un service les réseaux de composants nommés viax-aggrega-networks-of; les auteurs qui ont besoin d’un routage inter-réseaux au sein d’un seul fichier compose utilisent la Featurecompose-bridge. - Les membres d’extension issus des artefacts sont portés. Une clé
x-de premier niveau est écrite après les autres sections du fichier assemblé, dans l’ordre d’écriture, selon les règles de Les membres d’extension sont portés tels qu’ils sont écrits. - Toute autre clé de premier niveau issue des artefacts arrête le build.
services:,volumes:,configs:,models:et les membres d’extension constituent l’ensemble de ce que l’assembleur porte depuis un fragment. Un blocsecrets:et unname:de premier niveau arrêtent chacun le build en nommant la clé et le fragment, selon les règles de Chaque clé qu’un fragment écrit est portée ou refusée. - Un corps
artifacts:est un seul document. Un corps contenant plusieurs documents YAML arrête le build en nommant le fragment et le nombre de documents qu’il contient ; donnez à chaque document sa propre entréeartifacts:.
L’asymétrie entre les quatre premiers et networks: est structurelle : services:, volumes:, configs: et models: portent un contenu par Recipe que l’assembleur accumule dans le fichier assemblé ; networks: est une infrastructure par frontière que l’assembleur dérive de l’état de la frontière. Les artefacts peuvent étendre les premiers ; seules les annotations de la frontière peuvent façonner la seconde, c’est pourquoi l’entrée de réseau propre à un artefact est refusée. Les membres d’extension sont des données que la Compose Specification définit pour d’autres outils, ils sont donc portés tels qu’ils sont écrits. Tout le reste est une forme pour laquelle le document assemblé n’a pas de place, c’est pourquoi elle est refusée plutôt que fusionnée.
Ce que le fournisseur compose ne fournit pas
- Routage L4 inter-réseaux au sein d’un même fichier compose. Le fournisseur place chaque nœud sur son réseau et fait rejoindre à un service les réseaux que nomme
x-aggrega-networks-of, et n’achemine lui-même rien entre les réseaux. Un service du réseau A qui atteint un service du réseau B par autre chose que le DNS par défaut de docker-compose nécessite la Featurecompose-bridge, dont la FeatureRecipe écrit la passerelle et la réécriture. - Routage entre fichiers compose. Les frontières qui s’évaluent en chemins d’assemblage distincts produisent des fichiers
docker-compose.yamldistincts ; le runtime compose les traite comme des projets indépendants, et la Featurecompose-bridgelaisse une connexion entre deux fichiers telle qu’elle est écrite. La communication entre fichiers relève de l’opérateur (publication de ports de l’hôte, partage de réseaux externes, ou regroupement des frontières sur un même chemin via undirectory:partagé). - Alimenter une variable d’environnement depuis un rattachement. Compose n’a pas de primitive pour cela, de sorte qu’une entrée
attachmentsd’un Workload avecas: envémet le nom de la variable avec une valeur vide plutôt qu’une référence résolue à l’exécution. L’espace réservé est délibéré — une variable présente mais vide est visible par quiconque débogue le conteneur, alors qu’une variable absente ne laisse rien à examiner — et le build le signale plutôt que de le laisser découvrir : chacune de ces entrées déclenche un avertissementunsupported-fieldqui nomme l’entrée à sa coordonnée de rédaction (containers.<name>.attachments.<KEY>, ouinitContainers[<i>].attachments.<KEY>), afin que l’auteur sache quelle variable arrive vide et à quel conteneur elle appartient. L’avertissement est consultatif : le build réussit, et le fichier rendu est octet pour octet ce qu’il serait sans lui.--no-unsupported-field-warningsfait taire la classe. Une entréeattachmentsavecas: filen’est pas concernée — compose la monte en bind mount, et aucun avertissement n’est émis. - Contenu
deploy:du mode swarm. Les réplicas, les contraintes de placement et la stratégie de mise à jour sousdeploy:sont des fonctionnalités du mode swarm, et le fournisseur compose ne cible que compose sur un seul hôte, il n’en émet donc aucune. Il émet biendeploy.resources— les réservations et limites auxquelles correspondent lesresourcesd’un conteneur, que docker compose respecte hors mode swarm (voir Ressources des conteneurs). depends_onconditionné à l’état de santé depuis une arêteuses. Une dépendance dérivée d’une arêteusesest émise sans condition, avec la sémantiqueservice_started; elle n’est pas conditionnée au fait que le healthcheck de la cible signale qu’elle est en bonne santé. Il s’agit de ce que signifie une arêteuses, et non d’une forme que le fournisseur ne peut pas produire : la forme longue est émise pour l’attente d’un init container, et une vague de déploiement conditionne bel et bien l’attente à la santé de la cible lorsque la cible déclare un healthcheck.
Exemple de rédaction
Un déploiement compose à deux services avec une arête depends_on dérivée de 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.0Le fournisseur compose produit un seul docker-compose.yaml au chemin évalué de la frontière (par défaut dist/boundaries/production/compose/docker-compose.yaml, car le directory: d’une frontière vaut par défaut dist/boundaries/<name> et subDirectory: vaut par défaut {{ .capability }}) contenant :
services.api(le service api principal, réseauprod, ports8080:8080, healthcheck viacurl,depends_on: [db])services.db(le service db principal, réseauprod)networks.prod(le réseau docker de la frontière)
Références associées
- Entité Workload — le type Workload détenu par la plateforme que traduit le fournisseur compose.
- Architecture des Provider — comment les fournisseurs s’insèrent dans le pipeline de compilation.
- Annotations bien connues — les annotations
aggrega.ai/*que consomme le fournisseur compose. - Index de référence des Provider — ce que produit chaque fournisseur de la bibliothèque standard, et quelle page répond à quelle question.
- Composition des entrées de Recipe — la Matrice des capacités par Provider canonique.