Zum Inhalt springen
AggregaAggrega
Sprache wählen: Deutsch
Diese Seite wurde maschinell übersetzt. Das englische Original lesen.

Compose-Provider

Der compose-Provider rendert Recipes von Aggrega in eine Docker-Compose-Datei. Der Provider setzt pro (path, provider) zusammen: Die compose-Beitragenden jeder Boundary werden an den Assembler geleitet, dessen Schlüssel das ausgewertete directory: der Boundary verbunden mit dem subDirectory: der jeweiligen Komponente ist, und dieser Assembler gibt eine einzige docker-compose.yaml aus, die jeden Beitragenden an diesem Pfad enthält. Zwei Geschwister-Boundaries, die zum selben Pfad ausgewertet werden, fallen in eine einzige zusammengeführte compose-Datei zusammen — das kanonische Beispiel ist eine Eltern-Boundary plus zwei Kind-Boundaries mit directory: "{{ .parent_boundary.directory }}" (das Compose-Bridge-Muster).

Unterstützte Eingabearten

Der compose-Provider akzeptiert alle drei Recipe-Eingabearten:

  • Quellbasierter Modus. Ein Recipe mit source:, das auf eine vorhandene compose-Datei zeigt, plus valuesMapping:, das ein Overlay-Dokument erzeugt. Die Basis-compose-Datei wird geladen, das Overlay wird ausgewertet, und beide werden gemäß der nativen Overlay-Semantik von docker-compose tief zusammengeführt.
  • Workload-Modus. Ein Recipe mit workload: (inline oder über $import: geladen) deklariert ein Dokument Workload. Der Provider synthetisiert aus der Workload-Spezifikation einen oder mehrere compose-Services.
  • Artefakt-Modus. Die Einträge artifacts: eines Recipe werden zu compose-Fragmenten ausgewertet, die nach den Regeln in Als Artefakte ausgegebene compose-Fragmente in die zusammengesetzte Datei zusammengeführt werden. Artefakte können neben einer Quelle oder einer Workload mitlaufen, und sie können auch die gesamte Ausgabe eines Recipe sein: Ein Recipe, das artifacts: und weder source: noch workload: deklariert, wird hier gerendert und trägt bei, was auch immer seine Fragmente deklarieren. So erreicht eine Komponente, die nur aus Ressourcen besteht — ein gemeinsamer Satz aus Netzwerk und Volumes, eine vorbefüllte Konfiguration —, eine compose-Bereitstellung, ohne dass eine Platzhalter-Workload für Rechenleistung einspringt, die sie nicht hat.

Die drei Arten kombinieren sich additiv, und ein Recipe, das keine davon deklariert, wird beim Laden abgelehnt. Ein valuesMapping: ohne ein source: daneben wird beim Laden des Recipe ebenfalls abgelehnt, gleich welchen Provider es nennt: Es gibt nichts, worauf das Overlay angewendet werden könnte, und die Diagnose fordert Sie auf, den Zeiger source: zu deklarieren oder das valuesMapping: zu entfernen.

Zuordnung der Workload-Funktionen

Wenn ein Recipe workload: deklariert, übersetzt der Provider die plattformeigene Workload-Gestalt in compose-Primitive. Die Zuordnung ist bewusst schmal — die Oberfläche von Compose ist formenärmer als die von Kubernetes, und mehrere Workload-Funktionen werden mit dokumentiertem Verlust auf das nächstliegende compose-Äquivalent herabgestuft.

Container-Felder

Workload-FeldCompose-Feld
imageimage
imagePullPolicy: Always / IfNotPresent / Neverpull_policy: always / if_not_present / never
commandentrypoint (Listenform) — es überschreibt den Einstiegspunkt des Images, und genau das tut dieser compose-Schlüssel
argscommand (Listenform) — es liefert die Argumente, die der Einstiegspunkt erhält, und genau das überschreibt das command von compose
variablesenvironment (Map-Form)
attachments[as: env]Eintrag in environment mit leerem Wert und eine Warnung, die den Eintrag nennt (siehe Was der compose-Provider nicht liefert)
attachments[as: file]Bind-Mount in Langform unter volumes, schreibgeschützt
volumeMountsdas compose-Primitiv, auf das die referenzierte Volume-Variante abgebildet wird — ein Eintrag in Langform unter volumes, ein Eintrag tmpfs: auf Service-Ebene oder eine Referenz configs: auf Service-Ebene (siehe Volumes)
portsimplizit (compose-Container geben die Ports frei, auf denen das Image lauscht)
restartPolicy: Alwaysrestart: unless-stopped
restartPolicy: OnFailurerestart: on-failure
restartPolicy: Neverrestart: "no"

variables und attachments[as: env] landen in der einen Map environment, zuerst die Einträge aus Anbindungen und danach die variables, jede in der Reihenfolge, in der sie verfasst ist — die Reihenfolge, die der helm-Provider schreibt, sodass eine Workload auf jedem Ziel eine einzige Umgebungsreihenfolge rendert. Compose expandiert keine Referenz $(NAME) zwischen den Umgebungseinträgen eines Service, daher hat diese Reihenfolge auf compose keine Bedeutung zur Laufzeit. Weil die Map jeden Namen nur einmal enthält, bricht ein Container, der einen Namen sowohl als Eintrag in variables als auch als as: env gelieferten Eintrag in attachments angibt, den Build ab, statt einen der beiden Werte zu behalten (siehe A container gives one environment variable two values (Ein Container gibt einer Umgebungsvariable zwei Werte)).

Container-Ressourcen

Die resources eines Containers erreichen den Block deploy.resources von compose, den docker compose im Nicht-Swarm-Modus berücksichtigt. Die requests von Kubernetes drücken ein garantiertes Minimum aus, daher werden sie in compose zu reservations; limits drücken eine harte Obergrenze aus, daher bleiben sie limits.

Workload-FeldCompose-FeldÜbersetzung
resources.requests.cpudeploy.resources.reservations.cpusEine dezimale Anzahl von Kernen. Eine als bloße Zahl geschriebene Kernanzahl (2, 0.5) wird so ausgegeben, wie sie geschrieben ist; jede andere Form wird aus ihrem Wert umgerechnet (500m → 0.5, 1500m → 1.5, 5n → 0.000000005, 1e1 → 10)
resources.limits.cpudeploy.resources.limits.cpusDieselbe Umrechnung
resources.requests.memorydeploy.resources.reservations.memoryEine exakte Byteanzahl, umgerechnet aus dem Wert, in welcher Form er auch geschrieben ist — 8Gi wird zu 8589934592, 1.5Gi wird zu 1610612736, 1e3 wird zu 1000
resources.limits.memorydeploy.resources.limits.memoryDieselbe Umrechnung
nvidia.com/gpu, unter resources.limits, resources.requests oder beidendeploy.resources.reservations.devicesEin NVIDIA-Geräteeintrag am Service des Containers — driver: nvidia, count: die GPU-Anzahl, capabilities: [gpu]. Die Anzahl ist die des Limits, wo ein Limit geschrieben ist — die Anzahl, die Kubernetes für eine erweiterte Ressource einplant —, und sonst die der Anforderung. Eine Anzahl von 0 fordert keine GPU an und schreibt keinen Eintrag
jeder andere Schlüssel einer erweiterten Ressource — amd.com/gpu und jedes andere <domain>/<name>—Kein compose-Gegenstück auf einem einzelnen Host. Der Schlüssel wird verworfen, und der Build gibt eine Warnung unsupported-field aus, die ihn nennt, eine pro unterschiedlichem Schlüssel, gleich wie viele von requests und limits ihn trugen. Sein Wert wird nicht ausgegeben und daher nicht geprüft

Jeder Wert von cpu, memory und nvidia.com/gpu wird als Menge gelesen, in der unter Workload → Ressourcenmengen dargelegten Form, an der Workload, wie die Templates des Recipe sie ausgewertet haben. Zwei Dinge brechen den Build mit einem TRANSLATION_ERROR ab, und der Fehler sagt, auf welches der beiden er gestoßen ist, und nennt den Pfad des Containers, ob der Wert eine Anforderung oder ein Limit ist, die Ressource und den Wert:

  • ein Wert, der keine Menge ist — lots, 1.5 cores oder das m, das ein leeres Template in "{{ .infra.cpu }}m" hinterlässt;
  • eine Menge, die compose nicht exakt darstellen kann — ein negativer Betrag; ein Speicherbetrag, der keine ganze Zahl von Bytes ist (1500m, 4u) oder größer als 9223372036854775807 Bytes ist (8Ei); ein CPU-Betrag, der feiner als neun Dezimalstellen eines Kerns ist, die feinste Genauigkeit, die eine Kubernetes-Menge selbst behält, oder größer als 9223372036.854775807 Kerne; eine GPU-Anzahl, die keine ganze Zahl von Geräten ist (0.5, 500m).

Ein Container, dessen Anforderung und Limit für nvidia.com/gpu unterschiedliche Anzahlen verlangen, bricht den Build auf dieselbe Weise ab und nennt beide Pfade: compose reserviert eine Anzahl pro Service, daher müsste die Übersetzung sonst eine auswählen. Schreiben Sie in beide dieselbe Anzahl oder nur das Limit.

Nichts wird gerundet, und es wird kein Wert ausgegeben, der etwas anderes bedeutet.

Eine GPU-Anforderung reserviert NVIDIA-GPUs. Ein Workload-Container, der nvidia.com/gpu: "1" anfordert, wird zu einem Service gerendert, der diese Reservierung trägt, neben allen cpus und memory, die seine Anforderungen reservieren:

deploy:
resources:
reservations:
devices:
- driver: nvidia
count: 1
capabilities:
- gpu

Docker Compose übergibt die reservierten GPUs an den Container, wenn der Docker-Host so viele NVIDIA-GPUs hat und dafür eingerichtet ist, sie an Container zu geben; der Build kann den Host nicht sehen, daher wird eine Datei, die GPUs reserviert, überall gleich zusammengesetzt, wo sie auch laufen wird. Der Eintrag nennt immer seine Anzahl, weil Compose einen Geräteeintrag ohne Anzahl als jede GPU auf dem Host liest. Nur der NVIDIA-Schlüssel wird übersetzt: amd.com/gpu und der Schlüssel jedes anderen Herstellers behalten die Warnung aus der Zeile der verworfenen Schlüssel. Die Zeile runtimeClassName in Felder auf Pod-Ebene ist unverändert — compose hat kein Gegenstück zur Runtime-Klasse, daher wird einer Workload, die eine GPU-fähige Runtime nennt, mitgeteilt, dass die Runtime ausgelassen wurde, während ihre GPU-Anzahl reserviert wird.

Probes

Die drei Probe-Slots einer Workload (live, ready, startup) fallen auf den einzigen healthcheck pro Service von compose zusammen, mit der Priorität live > ready > startup (das kanonischste Liveness-Signal gewinnt). Wo dieses Zusammenfallen einen vom Autor deklarierten Slot verwirft, gibt der Build eine Warnung unsupported-field aus, die den übersetzten Slot und die verworfenen Slots nennt, sodass eine Absicht, die keinen Teil der Ausgabe erreicht, gemeldet statt verloren wird. Ein Block health, der einen Slot deklariert, wird ohne Verlust übersetzt und löst nichts aus, es sei denn, der Slot setzt successThreshold: Ein compose-Healthcheck hat dafür kein Feld, daher wird ein verfasster Wert — 1 eingeschlossen — mit einer Warnung unsupported-field ausgelassen, die ihn nennt (containers.<name>.health.<slot>.successThreshold), und der Rest des Slots wird so übersetzt, wie die folgende Tabelle zeigt.

Probe-Form der Workloadhealthcheck.test von 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, ...]

Die HTTP-Form verlangt, dass der Container mindestens einen benannten Port deklariert; der Synthesizer wählt den alphabetisch ersten Portnamen und verwendet dessen Nummer, um die URL für curl zu bilden. Container ohne deklarierte Ports können keine HTTP-Probes verwenden — der Compiler bricht mit einem TRANSLATION_ERROR ab, der die betreffende Probe nennt.

Timeout-Felder von Probes werden auf Dauer-Zeichenketten im compose-Stil abgebildet:

Workload-FeldFeld healthcheck von Compose
periodSecondsinterval: <n>s
timeoutSecondstimeout: <n>s
failureThresholdretries: <n>
initialDelaySecondsstart_period: <n>s

Volumes

Compose hat ein eigenes Config-Primitiv, in das ein Volume configmap übersetzt wird. Für ein Secret oder für Volume-Templates pro Replikat hat es kein Kubernetes-Äquivalent, daher werden diese Varianten auf das nächstliegende compose-Primitiv herabgestuft:

Volume-Variante der WorkloadCompose-ÜbersetzungHinweise zu Verlusten
ephemeralListeneintrag tmpfs: auf Service-EbenesizeLimit bleibt nicht erhalten (die Kurzform von tmpfs in compose hat keine Größe). Ein vom Autor geschriebenes sizeLimit löst eine Warnung unsupported-field aus, die es an seiner Authoring-Koordinate (volumes.<name>.ephemeral.sizeLimit) nennt, unabhängig davon, ob ein Container das Volume einhängt; wird das Feld weggelassen, wird nichts ausgelöst
configmapVerweis configs: auf Service-Ebene, der die Configmap nennt und am Pfad des Volume-Mounts eingehängt wird🔴 Der Mount-Pfad ist der Pfad einer einzelnen Datei, nicht eines Verzeichnisses. Compose schreibt den Inhalt der Config genau an den Zielpfad, während ein Kubernetes-Ziel, das eine ConfigMap an einem Pfad einhängt, ein Verzeichnis mit einer Datei pro Schlüssel erzeugt. Derselbe geschriebene path: bezeichnet hier also eine Datei und dort ein Verzeichnis: Richten Sie den Mount eines Volumes configmap auf den Dateinamen aus, den der Container lesen soll (/seed/config.json), nicht auf das Verzeichnis, das ihn enthalten würde, und ein Recipe, das für beide Ziele geschrieben ist, trägt pro Ziel einen anderen Pfad. Nichts im Build kann einen Pfad erkennen, der für die Gestalt des anderen Ziels geschrieben wurde — der Pfad ist ein opaker String, den der Compiler unverändert durchreicht, und die erzeugte Ausgabe ist in beiden Fällen gültig. Der Verweis erfolgt über den Namen, genau wie ein Kubernetes-Ziel auf eine ConfigMap-Ressource verweist — nichts liest den Inhalt der Config. Der passende Top-Level-Eintrag configs: stammt aus der Eingabe artifacts: des Recipe, dessen compose-Fragment ihn inline mit content: deklariert; ein Verweis ohne einen solchen Eintrag bricht den Build ab (siehe Als Artefakte ausgegebene compose-Fragmente). Ein Verweis configs: trägt den Namen der Config und den Mount-Pfad und sonst nichts, sodass das readOnly des Mounts keinen eigenen Ausdruck hat
secretBind-Mount in Langform unter volumes, schreibgeschütztEin Secret-Volume folgt bewusst nicht der Übersetzung configmap: Ein Inline-Eintrag configs: würde den Wert des Secrets im Klartext in die ausgegebene compose-Datei schreiben, und der Compiler löst ein Secret nie in Klartext auf — ein Secret bleibt in jeder Phase des Builds ein Zeiger. Die Bind-Quelle ist der Name source des Secrets, aufgelöst als Pfad, den der Betreiber auf dem compose-Host unabhängig vom Build erreichbar macht
persistentbenanntes Volume + Top-Level-Deklaration volumes: { <volume-name>: {} }, benannt gemäß Wie ein Volume-Name abgeleitet wirdStorage-Class, Zugriffsmodi und Größe bleiben nicht erhalten (compose hat keine entsprechende Gestalt). Ein vom Autor geschriebenes class oder accessModes löst eine Warnung unsupported-field aus, die es an seiner Authoring-Koordinate (volumes.<name>.persistent.class, volumes.<name>.persistent.accessModes) nennt; werden sie weggelassen, wird nichts ausgelöst. Das erforderliche size löst keine Warnung aus — siehe unten
persistentTemplatebenanntes Volume + Top-Level-Deklaration, auf dieselbe Weise benannt (wie bei persistent)Begleiter von form: stateful; compose hat kein Primitiv für Volume-Templates pro Replikat, daher geht das Verhalten pro Replikat verloren, und eine Warnung unsupported-field meldet, dass das Volume zu einem einzigen Volume geworden ist, das alle Replikate gemeinsam nutzen. Storage-Class, Zugriffsmodi und Größe bleiben nicht erhalten, genau wie bei persistent: Ein vom Autor geschriebenes class oder accessModes löst eine Warnung unsupported-field an volumes.<name>.persistentTemplate.class oder volumes.<name>.persistentTemplate.accessModes aus, und das erforderliche size löst keine aus

Das subPath eines Mounts hängt einen Teil eines Volumes ein, wo compose eine Form dafür hat. Ein Eintrag volumeMounts, der ein Volume persistent oder persistentTemplate mit subPath nennt, wird zu einem Langform-Eintrag volumes mit volume.subpath, sodass der Mount das benannte Verzeichnis oder die benannte Datei innerhalb des Volumes sieht statt dessen Wurzel, und zwei Mounts eines Volumes mit zwei unterschiedlichen Werten subPath sehen zwei unterschiedliche Teile davon:

volumes:
- type: volume
source: store--data
target: /var/lib/app/db
volume:
subpath: db
- type: volume
source: store--data
target: /var/lib/app/uploads
volume:
subpath: uploads

Ein ohne subPath geschriebener Mount trägt keinen Block volume:. Ein subPath auf einem Mount eines Volumes ephemeral, configmap oder secret bricht den Build mit einem Fehler TRANSLATION_ERROR ab, der die Komponente, den Container, den geschriebenen Pfad des Mounts (containers.<name>.volumeMounts[<i>]), das Volume und das subPath nennt: Diese Varianten erreichen compose als Eintrag tmpfs, als Verweis configs: und als Bind-Mount, von denen keiner einen Teil dessen einhängt, was er liefert, sodass der Mount sonst das ganze Volume sähe. Entfernen Sie subPath aus einem solchen Mount, oder hängen Sie ein Volume persistent ein. Docker Compose liest volume.subpath ab Version 2.26.0, auf Docker Engine 26.0 oder neuer; der Build kann den Host nicht sehen, der die Datei ausführen wird, sodass eine Datei, die es enthält, überall gleich zusammengesetzt wird, wo sie laufen wird.

Ein Volume sagt, welche Variante es ist, und nichts weiter. Ein Volume secret hat genau eine Übersetzung — den oben beschriebenen schreibgeschützten Bind-Mount —, und ein Volume trägt kein Feld as:, um eine andere auszuwählen. Was ein Slot als Umgebungsvariable veröffentlicht hat, wird über einen Eintrag attachments des Containers (as: env) geliefert statt über ein Volume; was compose mit einem solchen Eintrag tut, steht unter Was der compose-Provider nicht liefert.

Drei Varianten tragen eine Speichergröße, und nur eine davon warnt, dass die Größe verworfen wurde. Der Unterschied liegt darin, ob Sie eine Wahl hatten. Das sizeLimit eines Volumes ephemeral ist optional, es zu schreiben war also eine Entscheidung, und die Warnung teilt Ihnen mit, dass der Wert auf diesem Ziel nichts gestaltet und entfernt werden kann — sie ist beratend und Out-of-Band, die ausgegebene Datei ist Byte für Byte so, wie sie ohne sie wäre, und --no-unsupported-field-warnings schaltet sie zusammen mit dem Rest der Klasse stumm. Das size eines Volumes persistent oder persistentTemplate ist erforderlich, sodass keine Version des Dokuments es weglässt: Eine Warnung bei jedem Build würde dort bei jeder zustandsbehafteten Arbeitslast ausgelöst, ohne etwas zu nennen, das Sie ändern könnten, daher wird der Unterschied hier erklärt statt bei jedem Build gemeldet. Mit compose als Ziel gestalten size, class und accessModes eines persistenten Volumes nichts in der ausgegebenen Datei — Sie erhalten ein einfaches benanntes Volume, dimensioniert und hinterlegt durch das, was der Volume-Treiber des compose-Hosts standardmäßig tut. class und accessModes sind optional, daher wird jedes, das Sie schreiben, so gemeldet wie das sizeLimit eines Volumes ephemeral: eine Warnung unsupported-field pro Feld, beratend und Out-of-Band, stummgeschaltet durch dasselbe Flag. Dimensionieren Sie den zugrunde liegenden Speicher auf dem Host oder auf dem Kubernetes-Ziel, wo die Felder die Ausgabe erreichen.

Ein Volume, das kein Container einhängt, löst eine Warnung unsupported-field aus, die es an seiner Authoring-Koordinate (volumes.<name>) nennt, weil sich das, was die ausgegebene Datei erreicht, dann je nach Variante stark unterscheidet. persistent und persistentTemplate erzeugen weiterhin ihre Top-Level-Deklaration, sodass das Volume angelegt wird und nichts es nutzt. ephemeral, configmap und secret haben keinen Ausdruck außerhalb des Mounts selbst — jede wird zu etwas übersetzt, das am Mount-Pfad geschrieben wird, nämlich einem Eintrag tmpfs, einem Verweis configs beziehungsweise einem Bind-Mount —, sodass das von Ihnen deklarierte Volume, wenn nichts es einhängt, überhaupt keine Spur in der Ausgabe hinterlässt. Dieser zweite Fall ist der Grund, warum es die Warnung gibt: Ohne sie wäre ein Volume configmap, dessen Mount Sie vergessen haben, einfach abwesend, ohne dass in der ausgegebenen Datei etwas darauf hinwiese. Jeder Container der Arbeitslast zählt als einhängender Container, Init-Container eingeschlossen, sodass ein Volume, das nur ein Init-Container einhängt, verdrahtet ist und nichts auslöst. Die Warnung ist beratend und Out-of-Band — die ausgegebene Datei ist Byte für Byte so, wie sie ohne sie wäre —, und --no-unsupported-field-warnings schaltet die Klasse stumm.

Wie ein Volume-Name abgeleitet wird

Ein Volume persistent oder persistentTemplate wird zu einem benannten compose-Volume: einem Top-Level-Eintrag volumes:, auf den jeder Container verweist, der es einhängt. Ein compose-Volume ist gemeinsam genutzter Speicher, und der Top-Level-Block volumes: vereinigt seine Einträge nach Namen — zwei geschriebene Volumes, die bei einem Namen ankommen, werden also zu einem Volume, in das beide Container schreiben, ohne dass in der ausgegebenen Datei etwas zeigt, dass zwei gemeint waren. Der Name wird daher aus den zwei Identitäten gebildet, die zusammen sagen, um welches Volume es sich handelt: der <component>, zu der das Volume gehört, und dem Namen, den die Workload dem Volume unter volumes: gegeben hat.

Ein compose-Volume-Name akzeptiert eine engere Zeichenmenge, als jede der beiden Identitäten enthalten darf: Buchstaben, Ziffern, Punkte, Unterstriche und Bindestriche. Statt ein Zeichen zu ersetzen, das compose nicht akzeptiert, schreibt die Ableitung es aus, sodass zwei Volumes, die sich überhaupt unterscheiden, bei zwei Namen ankommen — und ein zusammengesetzter Name lässt sich in die zwei Identitäten zurücklesen, aus denen er gebildet wurde.

  • Ein Buchstabe, eine Ziffer, ein Punkt und ein Unterstrich werden genau so übernommen, wie sie geschrieben wurden.
  • Ein Bindestrich bleibt wie geschrieben erhalten, wo immer das Zeichen danach direkt übernommen wird und kein kleines z ist. Ein Bindestrich, auf den ein kleines z folgt, leitet ein Escape ein, daher wird ein geschriebener Bindestrich an dieser Stelle selbst ausgeschrieben — api-zone wird zu api-zhzone, und genau das erlaubt es, jeden Namen ohne Raten zurückzulesen. Ein Bindestrich, auf den nichts folgt, wird aus demselben Grund ausgeschrieben, sodass db- zu db-zh wird.
  • Jedes andere Zeichen wird als -z geschrieben, gefolgt von einem Buchstaben, der es benennt: s für ein Pfadtrennzeichen, h für einen Bindestrich, den die obige Regel nicht beibehält. Alles andere — ein Leerzeichen und ein Nicht-ASCII-Buchstabe eingeschlossen — wird als x und der sechsstellige hexadezimale Codepunkt des Zeichens geschrieben, und ein Byte, das überhaupt kein Zeichen beginnt, als b und sein eigener zweistelliger Wert, sodass ein Name, der kein gültiger Text ist, dennoch eindeutig ausgeschrieben wird, statt mit einem anderen zusammenzufallen.
  • Ein leerer Wert wird als -ze geschrieben, was kein nicht leerer Wert erzeugen kann.
  • Die zwei Identitäten werden durch -- verbunden. Eine einzelne kodierte Identität enthält dieses Paar nie, sodass der verbundene Name eindeutig sagt, wo eine Identität endet und die andere beginnt.

Die Komponente store mit einem Volume, das die Workload data nennt, ergibt also den Volume-Namen store--data, und db-server mit data ergibt db-server--data. Identische Eingabe erzeugt immer den identischen Namen.

Die verdoppelte Verbindungsstelle macht das Paar eindeutig, und eine Verbindungsstelle aus einem Zeichen kann das nicht. Jede der beiden Identitäten kann selbst einen Bindestrich enthalten, sodass eine Verbindung mit einem einzelnen Bindestrich einen Namen hinterlässt, der sich an mehr als einer Stelle teilen lässt: db mit einem Volume namens data-cache und db-data mit einem Volume namens cache würden beide db-data-cache ergeben, und da der Top-Level-Block nach Namen vereinigt, würden sich die beiden Komponenten ein Volume teilen, ohne dass in der ausgegebenen Datei etwas darauf hinwiese. Eine kodierte Identität enthält nie ein Paar von Bindestrichen, sodass die verdoppelte Verbindungsstelle keine zweite Lesart zulässt: Die beiden ergeben db--data-cache und db-data--cache.

Wird eine der beiden Identitäten geändert, wird das compose-Volume umbenannt, und compose benennt ein Volume nicht an Ort und Stelle um. Das Volume wird unter dem neuen Namen neu angelegt, während das alte mit den Daten darin zurückbleibt, sodass der Container mit leerem Speicher startet und die Inhalte in einem Volume liegen, das nichts einhängt. Benennen Sie eine der beiden Identitäten nur als geplanten Austausch um — gesichert, hinüberkopiert oder terminiert — statt als Änderung, die einfach bereitgestellt wird.

Controller-Form

Die form der Workload wählt eine abstrakte Controller-Gestalt (siehe entities/workload.md). Compose rendert stateless und stateful (und den leeren Standardwert, der als stateless behandelt wird) als langlaufende Services; die Form stateful fügt das benannte Volume für einen Begleiter persistentTemplate hinzu. Die Formen daemon, scheduled und task haben keine saubere compose-Abbildung auf einem einzelnen Host, sodass eine Workload, die eine davon deklariert und eine compose-Boundary als Ziel hat, den Build mit einem Fehler TRANSLATION_ERROR abbricht, der die Form und die unterstützte Menge nennt — compose stuft eine nicht unterstützte Form nicht zu einem einfachen Service herab, der die Absicht falsch darstellt. Eine Workload reference deklariert einen externen Endpunkt und keine Container, sodass compose für sie keinen Service ausgibt.

Da für eine Workload reference kein Service ausgegeben wird, liest nichts die Liefer-Pipe der Komponente, die sie realisiert: Eine an diese Komponente angebundene Anmeldeinformation — auf ihrer Pipe von dotenv-secret geliefert oder vom eigenen Block inject: einer Anbindung — würde keine ausgegebene Datei erreichen. Jedes Compose-Recipe der Standardbibliothek, das einen externen Dienst auf diese Weise realisiert und dessen Component einen Slot für Anmeldeinformationen deklariert, lehnt daher eine Anmeldeinformation ab, die diesen Slot füllt: Der Build bricht ab und nennt den Slot und die Komponente, statt mit fehlender Anmeldeinformation erfolgreich zu sein. Auf compose wird eine Anmeldeinformation für einen externen Dienst an die Komponente angebunden, die ihn aufruft, unter der Umgebungsvariable, die diese Komponente liest. Diese Ablehnung ist die eigene Assertion jedes Recipe, und sie läuft, bevor dieser Provider irgendetwas rendert. Dieser Provider lehnt auch am Knoten selbst ab, gleich aus welchem Katalog das Recipe stammt: Eine Anbindung an einem Knoten reference, deren Material als sensibel deklariert ist — ihr Feature deklariert ein Feld sensitive: true, oder der Slot, den sie füllt, tut es —, bricht den Build mit TRANSLATION_ERROR (E0288) ab und nennt den Knoten und jede solche Anbindung, unabhängig davon, ob ein Slot den Namen deklariert, unter dem sie angebunden ist. Eine Anbindung, die nichts als sensibel Deklariertes trägt, wird hier nicht abgelehnt. Diese Components deklarieren ihre Slots für Anmeldeinformationen als optional, sodass auf compose ein leer gelassener Slot nichts abbricht. Wo die Kubernetes-Realisierung die Anmeldeinformation benötigt — die Recipes helm von twilio, vonage, telnyx, bland, letta, retell und vapi —, verlangt dieses Recipe stattdessen den Slot und bricht den Build ab, wobei es ihn nennt, wenn er leer ist.

Service-Freigabe

Das Feld type eines Eintrags services der Workload entscheidet, ob compose Ports veröffentlicht und auf welcher Host-Adresse:

Service-Typ der WorkloadCompose-Verhalten
ClusterIPKeine Veröffentlichung über ports: — der Service ist nur im compose-Netzwerk erreichbar
NodePortVeröffentlichung über ports: [<host>:<container>], auf jeder Host-Schnittstelle
LoadBalancerVeröffentlichung über ports: [<host>:<container>], auf jeder Host-Schnittstelle (compose hat kein Äquivalent zu einem verwalteten Load Balancer; die Veröffentlichung auf einem Host-Port ist das nächstliegende Analogon)
LoopbackVeröffentlichung über ports: [127.0.0.1:<host>:<container>] — erreichbar vom Host selbst und von nirgendwo sonst
HeadlessKeine Veröffentlichung über ports:

Welche Nummer auf welche Seite kommt. Ein Service-Eintrag nennt einen Container-Port und gibt ihm eine Nummer, so wie ein Kubernetes-Service seinen port auf einen targetPort abbildet. Die Nummer des Eintrags ist die Seite <host> des veröffentlichten Paares, und die Nummer des Container-Ports, zu dem der Name aufgelöst wird, ist die Seite <container>. Ein Container, der http: 8080 deklariert, und ein Eintrag NodePort, der http: 8081 schreibt, veröffentlichen also 8081:8080: Der Port 8081 des Hosts erreicht den Port, auf dem der Container Anfragen bedient. Ein Eintrag, der die eigene Nummer des Container-Ports trägt, veröffentlicht diese Nummer auf beiden Seiten, 8080:8080. Ein Peer im compose-Netzwerk erreicht den Service über seinen Service-Namen auf dem Port des Containers, nie auf dem veröffentlichten — der veröffentlichte Port gehört dem Host —, sodass ein Recipe, das einen Port seiner Wahl veröffentlicht, seinen Konsumenten dennoch den Port des Containers übergibt.

Ein Eintrag Loopback bindet nur die IPv4-Loopback-Adresse. Die IPv6-Loopback-Adresse ::1 wird nicht gebunden: Die Port-Syntax von compose trägt eine Host-Adresse pro Eintrag, und ein Host, dessen Loopback-Schnittstelle keine IPv6-Adresse trägt, könnte sie nicht binden, sodass der Service dort nicht starten würde. Clients auf dem Host erreichen den Port unter 127.0.0.1.

Wenn mehrere Services einer einzelnen Workload denselben Container-Port unter derselben Nummer veröffentlichen, wird er einmal veröffentlicht, und die größere Reichweite gewinnt: Jeder Verweis NodePort oder LoadBalancer veröffentlicht ihn auf jeder Host-Schnittstelle, auch wenn ein Eintrag Loopback ihn ebenfalls nennt, und unabhängig davon, welcher Eintrag zuerst deklariert ist; ein Port, den nur Einträge Loopback nennen, wird auf 127.0.0.1 veröffentlicht. Ein Container-Port, der unter zwei Nummern veröffentlicht wird, wird zweimal veröffentlicht, einmal unter jeder. Veröffentlichte Ports werden in der Reihenfolge der Container-Ports aufgeführt und innerhalb eines Container-Ports nach veröffentlichtem Port.

Port-Transport. Ein veröffentlichter Eintrag trägt den Transport, der auf dem Container-Port deklariert ist, den er nennt, als Suffix /protocol von compose: 53:53/udp oder 127.0.0.1:53:53/udp für einen Eintrag Loopback. Ein Port, der keinen Transport deklariert, wird als <host>:<container> ohne Suffix veröffentlicht, sodass der eigene Standard von compose gilt. Compose schreibt den Transport eines veröffentlichten Ports als tcp oder udp; ein Port, der SCTP deklariert, hat keine compose-Schreibweise und bricht daher den Build mit einem Fehler TRANSLATION_ERROR ab, statt einen Port zu veröffentlichen, der einen anderen Transport tragen würde. Ein Container-Port, den kein Service veröffentlicht, erreicht keinen Teil der compose-Datei, sodass ein auf einem solchen Port deklarierter Transport nichts hat, worauf er geschrieben werden könnte, und keinen Abbruch auslöst.

Multi-Container-Workloads

Eine Workload mit mehreren Containern wird zu einem Haupt-Service plus einem Sidecar-Service pro Nicht-Haupt-Container. Der Haupt-Container ist derjenige mit dem Namen main (falls vorhanden) oder der erste Container in Deklarationsreihenfolge. Sidecars teilen den Netzwerk-Namespace des Haupt-Service über network_mode: "service:<main>" — die compose-Primitive, die dem Modell des gemeinsam genutzten Netzwerks eines Kubernetes-Pods am nächsten kommt.

Wie ein Sidecar- oder Init-Service benannt wird

Der Haupt-Service trägt den Namen <component> unverändert. Jeder andere Service, den die Workload erzeugt — einer pro Sidecar und einer pro Init-Container —, wird aus zwei Identitäten zusammen benannt: dem <component> und dem Namen des Containers, der bei einem Sidecar sein Schlüssel unter containers: und bei einem Init-Container sein name ist, oder dem positionsbezogenen init-<index>, den ein unbenannter Init-Eintrag erhält. Der zusammengesetzte Block services: enthält einen Service pro Name, daher wird der Name so gebildet, dass zwei Container, die sich in einer der beiden Identitäten unterscheiden, immer zu zwei Namen gelangen.

Jede Identität wird genau so ausgeschrieben wie die beiden Teile eines Volume-Namens — ein Buchstabe, eine Ziffer, ein Punkt und ein Unterstrich wie geschrieben, ein Bindestrich dort beibehalten, wo die dortigen Regeln ihn beibehalten, und jedes andere Zeichen ausgeschrieben —, und die beiden werden durch -- verbunden, das keine ausgeschriebene Identität enthält. So führt die Komponente api mit einem Sidecar logger diesen als api--logger aus, der Init-Container import-seed von platform läuft als platform--import-seed, und ein unbenannter erster Init-Eintrag von api läuft als api--init-0. Ein Container-Name, der ein Zeichen enthält, das ein Service-Name nicht zulässt, wird ausgeschrieben statt wie geschrieben ausgegeben: Ein Init-Container namens warm cache/x von api läuft als api--warm-zx000020cache-zsx.

Die doppelte Verbindung hält die Container zweier Komponenten auseinander. api mit einem Container warm-cache und api-warm mit einem Container cache laufen als api--warm-cache und api-warm--cache, zwei Services, wo eine Verbindung mit einem einzelnen Bindestrich beide als api-warm-cache schreiben würde.

Sidecars und Init-Container teilen sich diese eine Benennung, sodass ein Eintrag containers und ein Eintrag initContainers mit demselben Namen zum selben Service-Namen gelangen, und der Build hält bei diesem Paar an, statt einen Container anstelle des anderen auszuführen (siehe Init-Container).

Der eigene Service einer Komponente erhält keinen dieser Namen. Der Haupt-Service wird nach der Komponente benannt, und ein doppelter Bindestrich im Namen einer Komponente wird dort selbst ausgeschrieben — eine Komponente namens api--prep läuft als api-zh-prep —, sodass er nie die Verbindung -- trägt. Wo Services zweier verschiedener Komponenten in einer Compose-Datei dennoch auf einen Namen treffen — etwa über einen Service, den ein Artefakt für sich selbst benennt —, hält der Build an und nennt beide, wie Ausgabe pro (path, provider) beschreibt.

Eine Änderung des Komponentennamens oder des Containernamens benennt den Service um. Compose behandelt einen Service unter einem neuen Namen als neuen Service, daher wird sein Container unter dem neuen Namen neu erstellt.

Felder auf Pod-Ebene

Workload-Felder auf Pod-Ebene gelten nur für den Haupt-Service — Sidecars teilen den Netzwerk-Namespace des Haupt-Service —, und ein Init-Service folgt derselben Regel. Die einzige Ausnahme ist der Benutzer des Pods: Ein Pod führt jeden seiner Container als podSecurityContext.runAsUser und runAsGroup aus, daher erreichen diese jeden Service, den die Workload erzeugt, Sidecar- und Init-Services eingeschlossen.

Mehrere werden auf ein Feld eines compose-Service abgebildet:

Workload-FeldCompose-Feld
podSecurityContext.runAsUser / runAsGroupuser ("1000" oder 1000:3000 mit einer Gruppe) auf jedem Service der Workload. Ein Container, der sein eigenes securityContext.runAsUser setzt, läuft stattdessen auf seinem eigenen Service als dieser Benutzer, mit seinem eigenen runAsGroup, wo er eines setzt
terminationGracePeriodSecondsstop_grace_period: <n>s
dnsConfig.nameservers / dnsConfig.searchesdns / dns_search
hostAliasesein Eintrag extra_hosts pro Hostname, in der Reihenfolge des Autors
hostNetwork: truenetwork_mode: host

Ausführung im Netzwerk des Knotens. Eine Arbeitslast, die hostNetwork: true deklariert, erhält network_mode: host auf ihrem eigenen Service, und dieser Service wird dann aus dem Boundary-Netzwerk herausgelassen, statt daran angeschlossen zu werden: compose lehnt einen Service ab, der sowohl networks: als auch network_mode: deklariert, daher sind die beiden Alternativen und keine Ergänzungen. Die praktische Folge ist die, die Host-Networking immer mit sich bringt — Peers erreichen den Service nicht mehr über seinen compose-Service-Namen in diesem Netzwerk, weil er nicht mehr darin ist; sie erreichen ihn über die eigenen Adressen des Hosts, was die Deklaration verlangt hat. Kein anderer Service der Boundary ist betroffen.

Zwei Formen lassen sich damit kombinieren. Ein Sidecar nennt weiterhin den Haupt-Service (network_mode: "service:<main>") und folgt dem Haupt-Service also in das Netzwerk des Hosts, ohne selbst etwas zu deklarieren — so wie die Container eines Kubernetes-Pods einen Namespace teilen. Ein Init-Service nicht: Er tritt dem Boundary-Netzwerk aus eigenem Recht bei, weil das Teilen des Namespace des Haupt-Service das Warten des Haupt-Service auf ihn zirkulär machen würde. Eine Arbeitslast mit sowohl hostNetwork als auch initContainers führt ihren eigenen Service also im Netzwerk des Hosts aus, während ihre Init-Services im Boundary-Netzwerk bleiben, was enger ist als die Pod-Form, die sie modelliert; eine Warnung unsupported-field nennt diesen Unterschied, statt ihn erst zur Laufzeit entdecken zu lassen.

Der Rest hat kein Äquivalent auf einem einzelnen Host. Keines wird stillschweigend verworfen: Jedes geschriebene löst eine Warnung unsupported-field aus, die das Feld nennt, sodass ein Autor erfährt, welche Einstellung das Ziel nicht berücksichtigen konnte, statt es am laufenden Stack zu entdecken.

Workload-FeldWarum compose es nicht berücksichtigen kann
schedulingPlatzierung — nodeSelector, affinity, tolerations, topologySpreadConstraints — setzt einen Scheduler voraus, der zwischen Knoten wählt. Compose läuft auf einem einzigen Host
replicasDie eigene Replikatanzahl von compose liegt unter deploy: und ist eine Funktion des Swarm-Modus
runtimeClassNameDie Auswahl einer alternativen Container-Runtime — etwa einer GPU-fähigen — hat keinen compose-Ausdruck
priorityClassNameEine Preemption-Reihenfolge setzt einen Scheduler voraus
serviceAccountWorkload-Identität ist ein Cluster-Konzept
imagePullSecretsRegistry-Anmeldeinformationen auf einem compose-Host sind der eigene Anmeldestatus des Hosts, kein Feld der Datei
dnsPolicy, dnsConfig.optionsCompose bietet dns und dns_search an und nichts Feineres
podSecurityContext.fsGroup, podSecurityContext.supplementalGroupsuser trägt einen Benutzer und eine Gruppe; die Gruppe, der die Volumes eines Pods gehören, und weitere Gruppen für seine Prozesse werden nicht übersetzt
podSecurityContext.runAsGroup, wo der Pod kein runAsUser setzt, oder wo ein Container — Haupt-, Sidecar- oder Init-Container — sein eigenes runAsUser und kein runAsGroup setztuser nennt eine Gruppe nur neben einem Benutzer, und der eigene Benutzer eines Containers tritt an die Stelle des Benutzers des Pods, sodass die Gruppe des Pods keinen so geschriebenen Service erreicht

securityContext auf Container-Ebene wird teilweise übersetzt: readOnlyRootFilesystem → read_only, capabilities.add / drop → cap_add / cap_drop, runAsUser / runAsGroup → user. runAsNonRoot und allowPrivilegeEscalation haben keinen compose-Ausdruck und lösen dieselbe Warnung unsupported-field aus, ebenso ein runAsGroup eines Containers, das ohne ein runAsUser daneben geschrieben ist: Der Service läuft dann als Benutzer des Pods, wo der Pod einen setzt, ohne diese Gruppe.

Jede Warnung in diesem Abschnitt ist beratend und Out-of-Band: Der Build ist erfolgreich, und die ausgegebene Datei ist Byte für Byte so, wie sie ohne sie wäre. --no-unsupported-field-warnings schaltet die Klasse stumm.

Init-Container

Die Einträge initContainers einer Workload werden zu eigenen Services und nutzen das Run-to-Completion-Idiom von compose. Jeder Eintrag fügt einen Service hinzu, dessen Name nach der gleichen Benennung, die Sidecars verwenden, aus <component> und dem name des Eintrags gebildet wird — <component>--<container-name> für einen gewöhnlichen Namen; ein Eintrag, der name weglässt, erhält den positionsbasierten Namen init-<index>, den die Workload-Referenz dokumentiert, und wird danach benannt.

Die Reihenfolge, die der Authoring-Vertrag verspricht — die Init-Container laufen in der Reihenfolge, in der sie geschrieben sind, bis zum Abschluss, und jeder andere Container startet erst, nachdem alle beendet sind —, wird mit der Langform von depends_on ausgedrückt:

  • Jeder Init-Service nach dem ersten wartet mit condition: service_completed_successfully auf seinen Vorgänger.
  • Der Haupt-Service und jeder Sidecar-Service warten mit derselben Bedingung auf den letzten Init-Service. Auf den letzten zu warten genügt, weil die Init-Services eine Kette bilden.
  • Jeder Init-Service trägt restart: "no". Ein Init-Service läuft einmal; ein Service, der wieder hochkäme, würde nie den abgeschlossenen Zustand erreichen, auf den seine Abhängigen warten, daher ändert eine an einem Init-Container geschriebene restartPolicy daran nichts.
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"

Ein Init-Container wird genau wie jeder andere Container übersetzt: Sein image (einschließlich der Registry-Umschreibung, die eine Annotation aggrega.ai/image-registry anwendet), command, args, variables, attachments, volumeMounts und securityContext erreichen alle den Init-Service. Das sorgt dafür, dass die Konfiguration, die ein Init-Container trägt — meist eine Datei, die er einhängt und in ein Volume schreibt, das auch der Haupt-Container einhängt —, auf dem compose-Ziel erhalten bleibt, statt mit dem Container verloren zu gehen. Eine Form, die compose nicht ausdrücken kann, scheitert bei einem Init-Container genauso wie bei einem gewöhnlichen: Ein deklariertes lifecycle oder envFrom bricht den Build mit einem Fehler TRANSLATION_ERROR ab, der den Init-Container nennt, aus dem es stammt.

Zwei Unterschiede zum Haupt-Service ergeben sich daraus, dass ein Init-Service ein Nicht-Haupt-Service ist:

  • Workload-Felder auf Pod-Ebene werden nicht angewendet, dieselbe Regel, der Sidecars folgen — ausgenommen der Benutzer des Pods, der jeden Service erreicht, wie Felder auf Pod-Ebene beschreibt.
  • Ein Init-Service tritt dem Netzwerk seiner Boundary direkt bei, statt den Netzwerk-Namespace des Haupt-Service zu teilen, wie es ein Sidecar tut. Das muss er: Der Haupt-Service wartet auf den Init-Service, und das Teilen eines Namespace ist selbst eine Abhängigkeit vom Haupt-Service, die das Warten zu einem Zyklus schließen würde, dessen Start compose verweigert. Ein Init-Container erreicht andere Services im Boundary-Netzwerk daher über den Service-Namen, teilt aber nicht den localhost des Haupt-Service.

Init-Services und Sidecar-Services teilen sich einen Namensraum, weil eine einzige Benennung beide benennt, daher dürfen ein Eintrag initContainers und ein Eintrag containers nicht denselben Namen tragen. Wenn sie es doch tun, bricht der Compiler mit einem TRANSLATION_ERROR ab, der den Knoten, den Container-Namen und den Service-Namen nennt, den beide wollten, statt einen Service stillschweigend den anderen ersetzen zu lassen.

Das Ausgeben der Abschlussbedingung hebt keine Mindestversion von Compose an. condition und seine Werte gehören zur grundlegenden Compose Specification — anders als die Felder restart und required daneben im selben Langform-Block, die die Spezifikation an bestimmte Compose-Versionen bindet. Jede Mindestversion, die die Ausgabe des compose-Providers verlangt, kommt mit dem Konstrukt, das sie benötigt: ≥ 2.23.1 für inline configs.content, ≥ 2.26.0 für das subPath eines Mounts (siehe Volumes) und 2.38 für Modelle. Die erste betrifft jede compose-Ausgabe, die eine Config mit inline content: trägt, und so kommen sowohl die Datei hinter einem Volume configmap als auch die Config hinter einer per Bridge verbundenen netzwerkübergreifenden Kante an — nicht nur ein einzelner Authoring-Pfad.

Welchem Netzwerk ein Service beitritt

Jeder Service tritt einem Docker-Netzwerk bei; Sidecars erben es über ihren Verweis network_mode auf den Haupt-Service. In welchem Netzwerk ein Knoten landet, wird aus der Annotation aggrega.ai/namespace an diesem Knoten gelesen, mit dem Pfad der compose-Datei als Rückfall, wo der Knoten keine solche Annotation trägt — dem Verzeichnis, in das die Datei unterhalb des Ausgabeverzeichnisses des Builds geschrieben wird, etwa bridge/compose für eine Boundary, deren directory: bridge ist. Jeder Knoten ohne die Annotation in einer compose-Datei tritt also einem einzigen Netzwerk bei, das nach dem Pfad der Datei benannt ist, gleich in welcher Boundary er sich befindet: Nicht annotierte Boundaries, die eine compose-Datei teilen, teilen dieses Netzwerk, und aggrega.ai/namespace ist das, was sie trennt. Knoten mit unterschiedlichen Annotationen landen in einem Netzwerk pro unterschiedlicher Annotation. Wie ein Netzwerkname abgeleitet wird ist der Name, den diese Identität erzeugt.

Wie ein Netzwerkname abgeleitet wird

Ein compose-Netzwerk ist gemeinsam genutzte L3-Konnektivität, und der Top-Level-Block networks: vereinigt seine Einträge nach Namen — zwei Identitäten, die bei einem Namen ankommen, werden also zu einem Netzwerk, in dem beide Gruppen von Services liegen und sich über den Service-Namen erreichen, ohne dass in der ausgegebenen Datei etwas zeigt, dass zwei Netzwerke gemeint waren. Der Name wird daher aus der Identität gebildet, die sagt, um welches Netzwerk es sich handelt: der Annotation aggrega.ai/namespace des Knotens oder dem Pfad der compose-Datei, wo der Knoten keine trägt.

Ein compose-Netzwerkname akzeptiert eine engere Zeichenmenge, als jede der beiden Identitäten enthalten darf: Buchstaben, Ziffern, Punkte, Unterstriche und Bindestriche. Statt ein Zeichen zu ersetzen, das compose nicht akzeptiert, schreibt die Ableitung es aus, sodass zwei Identitäten, die sich überhaupt unterscheiden, bei zwei Netzwerken ankommen — und ein Name lässt sich in die Identität zurücklesen, aus der er gebildet wurde.

  • Ein Buchstabe, eine Ziffer, ein Punkt und ein Unterstrich werden genau so übernommen, wie sie geschrieben wurden, in der Groß- und Kleinschreibung, in der sie geschrieben wurden. prod und Prod sind also zwei Netzwerke, nicht eines.
  • Ein Bindestrich bleibt wie geschrieben erhalten, wo immer das Zeichen danach direkt übernommen wird und kein kleines z ist. Ein Bindestrich, auf den ein kleines z folgt, leitet ein Escape ein, daher wird ein geschriebener Bindestrich an dieser Stelle selbst ausgeschrieben — api-zone wird zu api-zhzone, und genau das erlaubt es, jeden Namen ohne Raten zurückzulesen. Ein Bindestrich, auf den nichts folgt, wird aus demselben Grund ausgeschrieben, sodass db- zu db-zh wird.
  • Jedes andere Zeichen wird als -z geschrieben, gefolgt von einem Buchstaben, der es benennt: s für ein Pfadtrennzeichen, h für einen Bindestrich, den die obige Regel nicht beibehält. Alles andere — ein Leerzeichen und ein Nicht-ASCII-Buchstabe eingeschlossen — wird als x und der sechsstellige hexadezimale Codepunkt des Zeichens geschrieben, und ein Byte, das überhaupt kein Zeichen beginnt, als b und sein eigener zweistelliger Wert, sodass eine Identität, die kein gültiger Text ist, dennoch eindeutig ausgeschrieben wird, statt mit einer anderen zusammenzufallen.
  • Eine gänzlich fehlende Identität — ein Knoten ohne Annotation aggrega.ai/namespace in einer compose-Datei ohne Pfad — wird als -ze geschrieben, was keine von einem Autor geschriebene Identität erzeugen kann. Ein Netzwerk ohne Identität teilt daher nie Konnektivität mit einem, dessen Identität auf irgendeine bestimmte Weise geschrieben ist.

Ein Namespace prod ergibt also das Netzwerk prod, core-net ergibt core-net, und eine compose-Datei unter dist/app/compose ergibt dist-zsapp-zscompose. Identische Eingabe erzeugt immer den identischen Namen.

Ein Namespace und der Pfad einer compose-Datei werden in denselben Raum geschrieben. Sie sind zwei Arten, dasselbe zu benennen — in welchem Netzwerk ein Knoten liegt —, daher landen ein Knoten, dessen Namespace app/compose ist, und ein Knoten ohne Namespace in der compose-Datei unter app/compose absichtlich in einem Netzwerk, genau wie zwei Boundaries, die dieselbe Annotation aggrega.ai/namespace tragen. Wo Sie zwei Knoten getrennt haben wollen, geben Sie ihnen Identitäten, die sich unterscheiden.

Wird die Identität eines Knotens geändert, wird das compose-Netzwerk umbenannt, und compose benennt ein Netzwerk nicht an Ort und Stelle um. Das Netzwerk wird unter dem neuen Namen neu angelegt, und jeder Service darin wird neu erstellt, um sich daran anzuschließen, während das alte Netzwerk zurückbleibt, bis etwas es entfernt. Ein Netzwerk enthält keine Daten, daher geht nichts verloren — aber die Container darin starten tatsächlich neu, und alles, was eine Verbindung über die Änderung hinweg hält, sieht sie abbrechen. Ändern Sie eine Namespace-Annotation oder das Verzeichnis, in das eine compose-Datei geschrieben wird, als zu planende erneute Bereitstellung statt als Wert, den man an Ort und Stelle anpasst.

Wenn zwei Boundaries in einem Zusammensetzungspfad zusammenfallen (gemeinsames directory:), teilen ihre Knoten ohne Annotation aggrega.ai/namespace das eine Netzwerk der Datei; geben Sie jeder Boundary ihre eigene Annotation aggrega.ai/namespace, und die zusammengeführte docker-compose.yaml deklariert einen Top-Level-Eintrag networks: pro Annotation. Services aus verschiedenen Boundaries innerhalb derselben compose-Datei können über ihre Service-Namen innerhalb der standardmäßigen DNS-Auflösung von compose kommunizieren, vorbehaltlich der eigenen Regeln von compose zur netzwerkübergreifenden Erreichbarkeit. Netzwerkübergreifendes L4-Routing innerhalb einer einzelnen compose-Datei ermöglicht das Feature compose-bridge der Standardbibliothek, als Kataloginhalt, von dem dieser Provider keine Logik enthält: An der Boundary des gemeinsamen Vorfahren angebunden, leitet sein FeatureRecipe ein Gateway aus den Kanten uses der Boundary ab, deren beide Enden in ihre eigene compose-Datei zusammengesetzt werden und in verschiedenen Netzwerken darin liegen — einen Service aggrega-gw, dessen nginx-Config stream jede per Bridge verbundene Kante proxyt (ein Block server pro Kante, auf dem Port des Ziels mit einem Rückfall portBase bei Kollisionen) —, und sein eigenes injectMapping schreibt die Host-Umgebungsvariable jedes Konsumenten auf aggrega-gw:<port> um, oder auf aggrega-gw, wobei die Port-Variable auf den Listen-Port umgeschrieben wird, wo dieselbe Verbindung beides liefert. Diese Umschreibung ersetzt den Wert, den die eigene Verbindung des Konsumenten geliefert hat; hat ein anderes an den Konsumenten angebundenes Feature dieselbe Variable geliefert, bricht der Build ab und nennt beide, statt ihn zu ersetzen. Das valuesMapping des FeatureRecipe schreibt diese Config als eingehängte compose-Config — einen Top-Level-Eintrag configs: mit inline content:, auf den das Gateway verweist und der unter /etc/nginx/nginx.conf eingehängt wird; das ist kein Mount, um den sich ein Betreiber kümmert — und nennt jeden per Bridge verbundenen Endpunkt unter dem x-aggrega-networks-of des Gateways, das dieser Provider in die Netzwerke auflöst, in denen diese Endpunkte platziert sind (unten). Eine Kante, deren beide Enden in zwei compose-Dateien zusammengesetzt werden, wird nicht per Bridge verbunden und behält den eigenen Namen des Ziels; eine Boundary, die nichts zu verbinden hat, trägt dennoch das untätige Gateway, ohne Config und ohne Netzwerk außer ihrem eigenen; und eine Bridge, die an eine Boundary angebunden ist, deren compose-Datei keine Komponente enthält, bricht den Build ab, statt das Gateway nirgendwohin zu schreiben. Die Config stream trägt eine Direktive resolver und proxyt über eine Variable pro Kante (set $uN <host>; proxy_pass $uN), sodass jeder Upstream zum Verbindungszeitpunkt statt einmal beim Start aufgelöst wird — ein bloßes proxy_pass auf ein noch nicht laufendes Ziel würde das Gateway sonst beim Hochfahren scheitern lassen. (Das $ in diesen Variablen wird innerhalb von configs.content zu $$ escapt, damit die eigene Interpolation $ von Docker Compose ein literales $ für nginx übrig lässt.) Inline configs.content erfordert Docker Compose ≥ 2.23.1. Siehe das Compose-Bridge-Muster.

Den Netzwerken anderer Komponenten beitreten — x-aggrega-networks-of

Ein Service, den ein Fragment schreibt — eine quellbasierte compose-Datei, sobald ihr Overlay eingemischt ist, oder ein Körper artifacts: —, kann den Netzwerken anderer Komponenten beitreten, die in dieselbe compose-Datei zusammengesetzt werden, indem er sie unter dem Erweiterungsschlüssel x-aggrega-networks-of nennt: eine Liste von Komponenten-IDs, den IDs, die das Aggregate seinen Komponenten gibt und die ein FeatureRecipe mit Boundary-Geltungsbereich als Schlüssel von .boundary.components und als source und target seiner Kantenlisten .boundary liest. Der Provider löst jede ID in das Netzwerk auf, in dem diese Komponente in dieser Datei platziert ist, durch dieselbe Platzierung, die jeder Knoten erhält, und fügt diese Netzwerke dem Service hinzu, jedes einmal und in Namensreihenfolge, vor dem eigenen Netzwerk des Service, dem er weiterhin beitritt. Der Schlüssel selbst wird aus der zusammengesetzten Datei weggelassen. Der Provider liest die IDs als aufzulösende Verweise und nichts darüber, was der Service tut, daher kann jedes Recipe oder FeatureRecipe den Schlüssel verwenden; das Gateway der compose-Bridge tritt auf diese Weise den Netzwerken der Endpunkte bei, zwischen denen es vermittelt.

# written by a FeatureRecipe attached at the boundary `bridge`, whose file holds adminer (namespace frontend) and db (namespace backend)
services:
probe-svc:
image: busybox
x-aggrega-networks-of: ["adminer", "db"]
# dist/bridge/compose/docker-compose.yaml (abridged)
services:
probe-svc:
image: busybox
networks:
- backend
- frontend
- bridge-zscompose

Drei Dinge brechen den Build mit TRANSLATION_ERROR ab, wenn die Datei zusammengesetzt wird, und jedes nennt den Service:

  • Eine ID, die keine in diese Datei zusammengesetzte Komponente trägt — etwa eine, die in eine andere compose-Datei zusammengesetzt wurde. Ein Netzwerk gehört zu einer Datei, daher nennt die Meldung die ID und die Datei, in der sich der Service befindet. Nennen Sie nur Komponenten, die in dieselbe Datei zusammengesetzt werden, oder entfernen Sie die ID.
  • Ein Wert, der keine Liste von Zeichenketten ist. Der Schlüssel nimmt eine Liste von Komponenten-IDs an, auch für eine einzige ID.
  • Der Schlüssel an einem Service, der network_mode schreibt. Compose lässt einen Service mit einem network_mode keinen Netzwerken beitreten; entfernen Sie eines der beiden.

Inferenz von depends_on

Der compose-Provider leitet depends_on automatisch aus den Kanten uses der IR ab. Für jede Kante, deren Quelle und Ziel beide Services zur zusammengeführten compose-Datei beitragen, fügt der Provider dem Quell-Service depends_on: [<target>] hinzu.

Die Abhängigkeit landet auf dem eigenen Service der Quellkomponente und auf keinem anderen Service, den diese Komponente beiträgt. Eine Komponente, die zusätzlich Init-Container deklariert, trägt pro Eintrag einen bis zum Abschluss laufenden Service bei, und keiner davon erhält die aus der Kante abgeleitete Abhängigkeit — eine Kante nennt die Komponente, und ein Init-Service trägt einen eigenen Namen. Ein Init-Container, der das Ziel der Kante erreichen muss, etwa eine Schemamigration gegen eine Datenbank, auf die die Komponente mit uses verweist, trägt daher keine Reihenfolge gegenüber diesem Ziel und kann laufen, bevor es erreichbar ist, während der eigene Service der Komponente sowohl darauf wartet, dass die Init-Kette abgeschlossen ist, als auch darauf, dass das Ziel gestartet ist.

Aus Kanten abgeleitete Einträge werden ohne Bedingung ausgegeben: Sie haben die Semantik service_started, unabhängig davon, ob das Ziel einen Healthcheck deklariert. Sie an die Gesundheit des Ziels zu binden — was die compose-Laufzeit den Start blockieren ließe, bis sich der Healthcheck des Ziels als gesund meldet — ist ausdrückbar, und eine Kante uses verlangt es nicht. Eine Welle, die dasselbe Paar nennt, ist das Einzige, was die Bedingung eines aus einer Kante abgeleiteten Eintrags ändert, und sie tut es, weil die Welle es verlangt, und nicht, weil die Kante es tut.

Aus Kanten abgeleitete Einträge werden für eine stabile Ausgabe in alphabetischer Reihenfolge der Ziele ausgegeben. Kanten, deren Quelle oder Ziel von einem anderen Provider (helm oder helm-chart) bedient wird, werden übersprungen — depends_on gilt nur innerhalb der von compose bedienten Teilmenge des Release.

Das depends_on eines Services wird in einer der beiden Formen von compose ausgegeben, nie gemischt, weil compose für jeden Eintrag der Langform eine Bedingung verlangt:

  • Liste in Kurzform (depends_on: [<service-name>]), wenn kein Eintrag dieses Services eine Bedingung trägt. Das ist jeder Service, dessen einzige Abhängigkeiten aus Kanten uses stammen.
  • Mapping in Langform, wenn irgendein Eintrag eine trägt — was geschieht, wenn der Service auch auf einen Init-Container wartet oder wenn eine Bereitstellungswelle ihn ordnet. Dort geben die aus Kanten abgeleiteten Einträge die explizite condition: service_started aus, die die Compose Specification als Äquivalent der Kurzform definiert, sodass sich ihre Bedeutung nicht ändert.

Innerhalb eines Services behalten die Quellen ihre eigene Reihenfolge und verschränken sich nicht: Das Warten auf die Init-Kette, deren Reihenfolge die ist, in der der Autor die Liste geschrieben hat, wird zuerst ausgegeben, dann die alphabetisch geordneten aus Kanten abgeleiteten Einträge, dann die alphabetisch geordneten aus Wellen abgeleiteten.

Reihenfolge nach Bereitstellungswellen

Der Wert syncWave: einer Boundary eines Release ordnet die Services der compose-Datei, in die diese Boundary gerendert wird. Jede Komponente in der Boundary erbt die Welle der Boundary, und wo mehrere Boundaries ein directory: teilen — sodass ihre Beiträge in einer einzigen docker-compose.yaml zusammenfallen —, enthält die zusammengeführte Datei mehr als eine Welle, und der Provider drückt die Reihenfolge zwischen ihnen als depends_on aus.

Jeder Service wartet auf jeden Service der unmittelbar vorhergehenden Welle, die überhaupt Services hat, und auf keine frühere Welle als diese. Compose löst den Rest transitiv auf: Ein Service in Welle 2 wartet auf Welle 1, die auf Welle 0 wartet, sodass die gesamte Abfolge geordnet ist, während die eigene Liste jedes Services so groß wie eine Welle bleibt statt wie die ganze Datei. Wellen müssen nicht lückenlos sein, und negative Werte sind gewöhnlich — -1 ist eine übliche Wahl für eine Migration, die vor allem anderen läuft.

Die Bedingung hängt davon ab, was das Ziel erfüllen kann. Eine Welle bedeutet, dass die frühere Gruppe läuft, bevor die spätere startet, was Bereitschaft und nicht Prozessstart ist, daher:

  • wo der Ziel-Service einen healthcheck deklariert, ist das Warten condition: service_healthy;
  • wo nicht, ist das Warten condition: service_started, weil ein Service ohne Healthcheck sich nie als gesund melden kann und ein an seine Gesundheit gebundenes Warten nie erfüllt würde — die Datei würde nie hochfahren.

Die schwächere Bedingung ist in der ausgegebenen Datei neben der stärkeren sichtbar, und der Build nennt zusätzlich jeden solchen Service in einer Warnung, sodass ein Autor, der eine Reihenfolge nach Bereitschaft erwartet hat, erfährt, welcher Teil der von ihm deklarierten Welle nur als Startreihenfolge ankommt. Die Warnung ist beratend: Der Build gelingt, und die gerenderten Bytes sind genau so, wie sie ohne sie wären. Einen Block health: zu diesem Container hinzuzufügen ist das, was das Warten aufwertet. --no-unsupported-field-warnings schaltet die Klasse stumm.

Die Welle wird weiterhin als Label festgehalten. Die Reihenfolge wird neben dem Label aggrega.ai/sync-wave hinzugefügt, nicht an seiner Stelle: Am Label sieht jemand, der die ausgegebene Datei untersucht, aus welcher Welle ein Service stammt, was die Einträge depends_on nicht angeben.

Wo eine Welle und eine Kante uses dasselbe Paar nennen, trägt ein Eintrag beides. Compose akzeptiert einen Eintrag pro Abhängigkeit, sodass ein Service, der ein Ziel über uses nutzt und zugleich eine Welle nach ihm liegt, einen einzigen Eintrag ausgibt, der an die Bedingung der Welle gebunden ist — die Anforderung der Welle ist die stärkere der beiden, und sie ist die ausgedrückte.

Eine Boundary, deren Komponenten alle in einer Welle liegen, gibt hieraus nichts aus. Ebenso ein Release, das überhaupt kein syncWave deklariert: Jeder Beitragende trägt den Standardwert des Felds, 0, die zusammengeführte Datei enthält eine einzige Welle, und die Ausgabe ist genau so, wie sie wäre, wenn der Provider keine Wellenreihenfolge ausdrückte.

Eine Reihenfolge über zwei compose-Dateien hinweg ist nicht ausdrückbar, und sie wird nicht angenähert. depends_on nennt einen Service innerhalb derselben Datei, und Boundaries, die zu unterschiedlichen Zusammensetzungspfaden ausgewertet werden, erzeugen unterschiedliche Dateien docker-compose.yaml, die die compose-Laufzeit als unabhängige Projekte behandelt. Eine Welle ordnet also jeden Service in der Datei, in die sie gerendert wird, und nichts außerhalb davon. Zwei compose-Projekte in eine Abfolge zu bringen ist Sache des Betreibers, so wie das dateiübergreifende Routing; ein gemeinsames directory: zu deklarieren ist das, was zwei Boundaries in eine Datei bringt, und es ist eine Entscheidung über die Form der Ausgabe, die aus eigenen Gründen zu treffen ist und nicht, um eine Reihenfolge zu erhalten.

Eine Kante uses, die auf eine spätere Welle zeigt, wird wie geschrieben ausgegeben und gemeldet. Das ausgegebene depends_on spiegelt wider, was deklariert wurde — sowohl die Kanten uses als auch die Wellen. Eine Kante, deren Konsument in einer früheren Welle liegt als das Ziel, das er nutzt, besagt das Gegenteil dessen, was die Wellen besagen: Die Kante lässt den Konsumenten auf das Ziel warten, während die Wellen das Ziel, über jede Welle zwischen ihnen hinweg, auf den Konsumenten warten lassen. Die zusammengeführte Datei drückt beides aus, was eine zirkuläre Menge von Abhängigkeiten ergibt, die Docker Compose nicht startet. Der Build nennt jede solche Kante in einer Warnung, die beide Services und beide Wellen angibt, sodass der Zyklus beim Build zutage tritt statt bei docker compose up. Die Warnung ist beratend — der Build gelingt, und die gerenderten Bytes sind genau so, wie sie ohne sie wären —, und --no-unsupported-field-warnings schaltet sie nicht stumm, weil nichts verworfen wurde: Die beiden Deklarationen sind jeweils ausgedrückt, und zusammen können sie nicht starten. Sie deckt nur das direkte Paar ab: Sie nennt die zwei Services, die eine Kante verbindet, statt den ganzen Zyklus zu verfolgen. Jeder Zyklus, der aus Kanten uses und Wellen zusammen gebildet wird, verläuft durch mindestens eine solche Kante und wird daher immer gemeldet; ein Zyklus, der allein aus Kanten uses gebildet wird, ohne beteiligte Welle, und einer, der durch einen Eintrag depends_on in einer vom Recipe gelieferten compose-Datei geschlossen wird, werden wie geschrieben ausgegeben und nicht gemeldet. Halten Sie die Kantenrichtung und die Wellenreihenfolge konsistent: Platzieren Sie den Konsumenten in der Welle des Ziels oder einer späteren, oder das Ziel in der Welle des Konsumenten oder einer früheren.

# release.yaml fragment — three boundaries collapsing onto one compose file
boundaries:
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 nennt migrator nicht: Die Reihenfolge reicht bis zur unmittelbar vorhergehenden Welle, und compose verkettet den Rest über store.

Modus mit Quelle

Das source: des compose-Providers nennt eine YAML-Datei für docker-compose, die der Provider lesen und parsen kann, und es akzeptiert beide Formen, die das Feld source: annimmt: einen reinen Dateisystempfad als String und ein strukturiertes Objekt, dessen url: den Ort trägt. Wo immer dieser Ort ein Dateisystempfad ist, ist er an dem Verzeichnis verankert, das die recipe.yaml enthält, die ihn deklariert, nicht an dem Verzeichnis, aus dem der Build aufgerufen wird, und er muss innerhalb dieses Verzeichnisses bleiben: Ein Pfad, der daraus hinaussteigt, oder ein absoluter wird abgelehnt, weil jede Datei, die eine Veröffentlichung des Recipe mitführt, aus seinem Verzeichnis genommen wird — siehe entities/recipe.md „Content paths stay inside the Recipe’s own directory (Inhaltspfade bleiben im eigenen Verzeichnis des Recipe)“. Die so benannte Datei wird mit dem Recipe veröffentlicht, eine Datei neben dem Recipe, die nichts von dem, was es deklariert, nennt, dagegen nicht.

spec:
capability: compose
source: ./docker-compose.base.yaml # filesystem path to the base compose file
valuesMapping: |
services:
api:
image: "{{ .values.image }}"

In der strukturierten Form entscheidet das, was url: trägt, darüber, ob etwas abgerufen wird. Ein über https:// veröffentlichtes Fragment wird abgerufen und mit kind: compose-https-fragment fixiert; aggrega pull beschafft es, und der Build liest es aus dem Cache. Ein url:, das einen Dateisystempfad nennt, wird nicht abgerufen — es wird von der Festplatte gelesen, genau wie die obige Form mit reinem String verankert, und aggrega pin hält den Digest der Datei, die es nennt, in der Datei entity.lock neben dem Recipe fest, den ein Build dann vergleicht, bevor das Fragment gelesen wird. Ein entferntes Fragment lokal zu übernehmen (Vendoring) und source: auf die lokale Kopie zeigen zu lassen, wird als Alternative zum Abrufen unterstützt und ist nicht erforderlich. Das Schema akzeptiert ein offenes strukturiertes Objekt.

Ein Recipe mit source: <path-to-compose-file> und valuesMapping: durchläuft die folgende Pipeline:

  1. Die Basis-compose-Datei unter <path> wird gelesen und als YAML geparst.
  2. Das Template valuesMapping wird gegen den Template-Kontext des Recipe ausgewertet. Seine Ausgabe wird als compose-Overlay-Dokument behandelt — eine partielle compose-Datei, die Felder der Basis ergänzt oder überschreibt.
  3. Basis und Overlay werden gemäß der nativen Overlay-Semantik von docker-compose tief zusammengeführt.

Die Regeln der tiefen Zusammenführung:

  • Skalare: Das Overlay gewinnt. Wenn Basis und Overlay dasselbe skalare Feld setzen, ersetzt der Wert des Overlays den Wert der Basis.
  • Maps: rekursiv zusammenführen. Wenn Basis und Overlay dasselbe Map-Feld setzen, steigt die Zusammenführung rekursiv in die Map ab. Schlüssel, die in beiden vorhanden sind, folgen denselben Regeln; Schlüssel, die nur in einer vorhanden sind, bleiben unverändert erhalten.
  • Listen: ersetzen. Wenn Basis und Overlay dasselbe Listenfeld setzen, ersetzt die Liste des Overlays die Liste der Basis vollständig (kein elementweises Zusammenführen oder Anhängen). Das entspricht dem Verhalten von docker compose -f base.yaml -f overlay.yaml config.
  • null: ersetzt und bleibt. Ein Schlüssel, den das Overlay auf einem Service auf null setzt — einer der eigenen Schlüssel des Services wie user, command oder healthcheck, ein Eintrag in environment, ein Label oder ein Schlüssel direkt unter healthcheck oder deploy —, ersetzt den Wert der Basis wie jeder Skalar und wird als key: null in die compose-Datei geschrieben; er entfernt den Schlüssel nicht. Wo der Provider einen eigenen Wert in diesen Schlüssel schreibt, trägt die Datei stattdessen den Wert des Providers: labels: null belässt die Provenienz-Labels, die der Provider anbringt, und networks: null das Netzwerk, das er anhängt. Ein null, das irgendwo sonst im Overlay geschrieben wird, liegt außerhalb dieser Regel. Was ein null dann bedeutet, ist die Lesart von Compose für dieses Attribut — ein Eintrag in environment ohne Wert etwa übernimmt seinen Wert aus der Umgebung, in der docker compose läuft.

Jedes Label, das der Autor eines Services geschrieben hat, bleibt. Die labels: eines Services in der Basisdatei oder im Overlay können als Map oder als Liste von Einträgen key=value von Compose geschrieben werden, und jedes Label erreicht die compose-Datei neben den Provenienz-Labels, die der Provider anbringt. Ein Listeneintrag wird so gelesen, wie Compose ihn liest: Der Text vor seinem ersten = nennt das Label, der Text danach ist der Wert, und ein Eintrag ohne = ist ein Label mit leerem Wert. Eine Zahl oder ein true/false-Wert wird als sein Text geschrieben, sodass replicas-hint: 2 die Datei als replicas-hint: "2" erreicht, und ein als null geschriebenes Label bleibt null. Wo ein geschriebenes Label und ein Provenienz-Label einen Schlüssel teilen, trägt die Datei den Provenienzwert. Ein Wert labels:, der weder eine Map noch eine Liste ist, und ein Listeneintrag, der kein Text ist, brechen den Build ab und nennen die Quelldatei und den Service. Die Service-Labels eines Körpers artifacts: nehmen die Map-Form an: Eine Liste dort bricht den Build ab und nennt das Artefakt und den Service.

Das zusammengeführte Dokument fließt dann neben allen Beiträgen im synthetisierten Modus in die Zusammenführung auf Release-Ebene ein, mit derselben Netzwerkbildung pro Boundary und derselben Inferenz von depends_on.

Services, Volumes und Konfigurationen weglassen. Das Overlay kann nichts aus der Basisdatei entfernen — ein Overlay-Wert ersetzt, er löscht nie —, daher sind die Einträge omits: eines Recipe oder eines FeatureRecipe für eine abgerufene Datei da, die einen Service bündelt, den das Release nicht ausführen darf. Dieser Provider berücksichtigt sie in diesem Modus und in keinem anderen: Eine synthetisierte Workload und ein Körper artifacts: werden ohne sie gerendert. Ein Eintrag nennt eine Top-Level-Einheit der Datei über ihr kind — service, volume oder config — und ihren name, den Schlüssel der Einheit unter services:, volumes: oder configs:, exakt verglichen. Eine compose-Datei hat keine Namespaces, daher bricht ein Eintrag, der einen namespace trägt, wie einer, der irgendeine andere Art nennt, den Build ab, wenn die Komponente gerendert wird, und nennt den Eintrag und die Arten, die dieser Provider akzeptiert; jeder Eintrag wird geprüft, bevor irgendetwas weggelassen wird. Die Einträge werden mit der Datei abgeglichen, sobald das obige Overlay in sie zusammengeführt ist, sodass eine vom Overlay hinzugefügte Einheit genauso weggelassen wird wie eine von der Basis deklarierte, und bevor der Provider etwas Eigenes hinzufügt, sodass ein Eintrag das nie nennt. Eine Einheit, die ein Eintrag nennt, wird entfernt, und ein Abschnitt, dessen Einheiten alle weggelassen werden, wird mit ihnen entfernt; jede andere Einheit wird genau so geschrieben, wie sie es ohne die Einträge würde. Die Einträge erreichen die Datei des Recipe oder FeatureRecipe, das sie deklariert, und nichts sonst: Was eine andere Komponente oder ein angebundenes Feature zur selben docker-compose.yaml beiträgt, bleibt unberührt, eine Einheit mit demselben Schlüssel eingeschlossen. Der Provider meldet, wie viele Einheiten jeder Eintrag weggelassen hat, und ein Eintrag, der keine weggelassen hat, bricht den Build ab; siehe An omits entry left out nothing the source rendered (Ein omits-Eintrag hat nichts von dem weggelassen, was die Quelle gerendert hat).

Eine weggelassene Einheit darf von dem, was übrig bleibt, nicht weiterhin genannt werden, weil compose eine Datei ablehnt, die einen Service, ein Volume oder eine Konfiguration nennt, die sie nicht deklariert. Sobald die Einheiten entfernt sind, bricht jeder Verweis, den die Datei noch auf eine von ihnen enthält, den Build ab, und die Meldung nennt jeden verweisenden Service oder Job, die Einheit, die er nennt, und das Feld, in dem der Verweis steht. Ein Verweis ist das, was die Compose Specification als einen Eintrag einer Datei definiert, der einen anderen nennt:

  • ein Service, genannt durch depends_on in einer der beiden Formen, durch links (SERVICE oder SERVICE:ALIAS), durch volumes_from (SERVICE oder SERVICE:MODE), durch network_mode, ipc, pid oder uts mit dem Wert service:<name>, durch extends, das einen Service derselben Datei nennt, oder durch einen Wert service:<name> von build.additional_contexts;
  • ein Volume, genannt als Quelle eines Eintrags volumes: — die Kurzform SOURCE:TARGET, bei der die Quelle ein Name und kein Pfad ist, und die Langform von type: volume;
  • eine Konfiguration, genannt durch einen Eintrag configs:, in einer der beiden Formen.

Auch die Hooks pre_start eines Services und jeder Top-Level-Eintrag jobs: werden gelesen, auf die Verweise hin, die die Spezifikation jedem von ihnen erlaubt. Manche Werte sehen nur wie Verweise aus und werden nicht als solche gelesen: Ein Eintrag volumes_from oder network_mode, der mit container: beginnt, nennt einen Container, external_links nennt einen Container, den diese Datei nicht deklariert, ein extends mit einem file: nennt einen Service einer anderen Datei, und ein credential_spec.config kann eine Konfiguration nennen, die die Plattform statt der Datei hält. Jeder Wert wird so verglichen, wie er geschrieben ist, sodass ein über ein ${VARIABLE} geschriebener Verweis keiner ist, den diese Prüfung sieht, und ein Verweis auf eine Einheit, die die Datei nie deklariert hat, bleibt, wie er ist.

Die Prüfung liest allein die eigene Datei des deklarierenden Recipe oder FeatureRecipe, sodass ein Verweis auf einen weggelassenen Service den Build auch dort abbricht, wo ein anderer Beitragender am selben Zusammensetzungspfad einen Service dieses Namens deklariert. Um den Verweis zu behalten, behalten Sie die Einheit. Um ihn zu entfernen, ändern Sie den verweisenden Eintrag über valuesMapping: — eine Liste dort ersetzt die Liste der Basisdatei, sodass depends_on: [] eine leert — oder lassen Sie den verweisenden Service ebenfalls weg.

Ausgabe pro (path, provider)

Jeder compose-Zusammensetzungspfad erzeugt eine docker-compose.yaml. Boundaries, die zu unterschiedlichen Pfaden ausgewertet werden, erzeugen unterschiedliche compose-Dateien; Boundaries, die einen ausgewerteten Pfad teilen, erzeugen eine zusammengeführte compose-Datei, die jeden Beitragenden an diesem Pfad enthält. Der Pfad ist das directory: der Boundary, verbunden mit dem komponentenspezifischen subDirectory: (das standardmäßig {{ .capability }} ist, sodass compose-Beitragende standardmäßig unter einem Unterordner compose/ landen).

Kollisionen von Service-Namen innerhalb eines einzelnen Zusammensetzungspfads brechen den Build ab. Wenn zwei verschiedene Knoten Services mit derselben Instanz-ID am selben Tupel (path, provider) beitragen, bricht der Compiler ab, und die Diagnose nennt jedes beitragende Tupel (boundary, node) in alphabetischer Reihenfolge. Der Autor löst die Kollision, indem er einen der Beitragenden umbenennt (typischerweise durch Anpassen des Bezeichners des Knotens, sodass der Synthesizer einen anderen Service-Namen erzeugt), oder indem er die Beitragenden über unterschiedliche Deklarationen directory: an verschiedene Pfade leitet.

Top-Level-Volumes werden innerhalb eines Zusammensetzungspfads vereinigt, und zwei Beitragende dürfen einen Namen deklarieren, sofern sie sich darüber einig sind. Ein Beitragender ist ein Fragment, daher sind zwei Fragmente einer Komponente — ihre eigene compose-Datei und ein Eintrag artifacts: oder zwei Einträge artifacts: — genauso zwei Beitragende wie zwei Komponenten. Ein benanntes Volume ist ein physisches Volume, daher beschreiben zwei identische Deklarationen beide genau den Eintrag, mit dem die zusammengesetzte Datei endet, und sie behält einen einzigen Eintrag unter diesem Namen. Ein vom Provider abgeleitetes Volume trägt keinen Körper, daher stimmen zwei davon trivialerweise überein, und sie können ohnehin nicht aufeinandertreffen (siehe Wie ein Volume-Name abgeleitet wird).

Ein geschriebener Eintrag volumes: ist derjenige, auf den zu achten ist, weil er einen eigenen Körper tragen kann — einen driver, driver_opts oder labels. Wo zwei Beitragende einen Namen mit unterschiedlichen Körpern deklarieren, bricht der Build mit TRANSLATION_ERROR ab und nennt das Volume und jedes beitragende Tupel (boundary, node, fragment). Sind sich zwei Autoren über ein einziges Volume uneinig, gibt es keine Antwort, zwischen der der Assembler wählen könnte: Welchen der beiden Körper er auch behielte, er verwürfe, was der andere Autor geschrieben hat, aus einem Build, der sonst erfolgreich wäre. Lösen Sie es, indem Sie die beiden Deklarationen identisch machen, wo beide Autoren dasselbe Volume meinten, oder indem Sie eine davon umbenennen, wo sie zwei meinten. Top-Level-Netzwerke gibt es eines pro unterschiedlicher Annotation aggrega.ai/namespace, plus eines, das nach dem Pfad der compose-Datei benannt ist, für die Knoten, die keine tragen, benannt nach Wie ein Netzwerkname abgeleitet wird; zwei beitragende Boundaries mit derselben Annotation aggrega.ai/namespace werden zu einem einzigen Netzwerk zusammengeführt, das beide teilen, ebenso zwei nicht annotierte Boundaries, die sich die Datei teilen.

Jeder Schlüssel, den ein Fragment schreibt, wird übernommen oder abgelehnt

Ein Fragment — eine quellbasierte compose-Datei, sobald ihr Overlay eingemischt ist, oder ein Körper artifacts:, der zu compose-YAML ausgewertet wird — erreicht die zusammengesetzte docker-compose.yaml nur über die Schlüssel, die der Provider übernimmt, und diese Menge ist fest. Jeder Schlüssel, den ein Fragment schreibt, wird entweder so, wie er geschrieben ist, in die zusammengesetzte Datei übernommen oder namentlich abgelehnt; keiner wird kommentarlos weggelassen. Ein Fragment ist eine compose-Datei, also ist es ein YAML-Dokument.

  • Übernommen. Auf oberster Ebene: services, volumes, configs und models. An einem 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_hosts und profiles. Innerhalb der Blöcke, die der Provider beschreibt: deploy.resources mit seinen limits (cpus, memory) und reservations (cpus, memory, devices sowie driver, count, device_ids, capabilities und options jedes Geräteeintrags); test, interval, timeout, retries und start_period eines healthcheck; type, source, target, read_only und volume.subpath eines Eintrags volumes: in Langform; source und target eines Eintrags configs: in Langform; condition eines Eintrags depends_on: in Langform; driver, driver_opts und labels eines Top-Level-Volumes; content einer Top-Level-Konfiguration. Beim Körper eines Modells und beim Eintrag models: in Langform eines Services wird jedes Element übernommen, wie Modelle beschreibt. Ein Erweiterungselement — ein Schlüssel, der mit x- beginnt — wird auf oberster Ebene und an einem Service übernommen, wie Erweiterungselemente beschreibt.
  • Abgelehnt. Jeder andere Schlüssel — stdin_open an einem Service, ein secrets: oder name: auf oberster Ebene, deploy.replicas, ein restart: oder required: innerhalb eines Eintrags depends_on: in Langform, ein Schlüssel x- im Körper eines Top-Level-Volumes oder eines healthcheck — bricht den Build mit TRANSLATION_ERROR ab, nennt jeden solchen Schlüssel, seinen Pfad im Fragment (services.migrate.stdin_open), das Fragment und die Komponente und nennt die beiden Stellen, von denen ein solcher Schlüssel stammt. Die eine ist das Fragment selbst, und die Behebung besteht darin, den Schlüssel daraus zu entfernen. Die andere ist ein quellbasiertes Recipe, das kein valuesMapping: deklariert: Die Werte des Knotens werden dann unverändert über die compose-Datei gelegt, sodass jeder Werteschlüssel als Top-Level-Schlüssel des Fragments ankommt, und die Behebung besteht darin, ein valuesMapping: zu deklarieren, das jeden Wert unter einen Schlüssel legt, den der Provider übernimmt. Ein Schlüssel, den ein YAML-Merge-Schlüssel (<<: *anchor) in einen Block bringt, wird dort beurteilt, wo er landet, als wäre er dort geschrieben. Ein aus der Quelle gerendertes Fragment heißt <component>.compose-fragment.yaml; ein Fragment artifacts: trägt den Namen, den sein Recipe ihm gibt.
  • Als Ganzes abgelehnt: ein eigenes Netzwerk des Fragments. Ein Eintrag unter networks: auf oberster Ebene eines Fragments bricht den Build mit TRANSLATION_ERROR ab, was auch immer sein Körper enthält — ein leerer Eintrag, ein driver, irgendetwas anderes —, und nennt den Eintrag (networks.back), das Fragment und die Komponente, weil die zusammengesetzte Datei nur die Netzwerke enthält, die der Provider ableitet (siehe Welchem Netzwerk ein Service beitritt). Entfernen Sie den Eintrag: Ein Service tritt dem Netzwerk seiner eigenen Komponente bei, ohne dass etwas deklariert wird, die Annotation aggrega.ai/namespace wählt, welchem Netzwerk eine Komponente beitritt, ein Service nennt die Komponenten, deren Netzwerken er zusätzlich beitritt, unter x-aggrega-networks-of, und das Feature compose-bridge routet zwischen Services in verschiedenen Netzwerken. Ein leeres networks: {} deklariert nichts und wird nicht abgelehnt, und die eigene Liste networks: eines Services wird wie oben übernommen.
  • Als Ganzes abgelehnt: ein Fragment aus mehr als einem Dokument. Ein Körper artifacts:, der zwei oder mehr durch --- getrennte YAML-Dokumente enthält, bricht den Build mit TRANSLATION_ERROR ab und nennt das Fragment, die Komponente und wie viele Dokumente es enthält, weil die Zusammenführung ein Fragment als eine compose-Datei liest und jedes Dokument nach dem ersten sonst in der zusammengesetzten Datei fehlen würde. Schreiben Sie das Fragment als ein Dokument, oder geben Sie jedem Dokument einen eigenen Eintrag artifacts:. Ein Dokument, das nichts enthält — das leere, das ein abschließendes --- eröffnet —, wird nicht gezählt. Eine quellbasierte compose-Datei aus mehreren Dokumenten wird nie zu einem solchen Fragment: Sie wird abgelehnt, wenn die Datei gelesen wird.

Der Provider liest die Bedeutung keines Schlüssels: Ein Schlüssel wird übernommen, weil er in der obigen Menge ist, und abgelehnt, weil er es nicht ist.

Erweiterungselemente werden so übernommen, wie sie geschrieben sind

Die Compose Specification reserviert Schlüssel, die mit x- beginnen, für Erweiterungen: Daten, die ein Werkzeug, das die Datei liest, verwenden darf und die Compose selbst ignoriert. Die Erweiterungselemente eines Fragments auf oberster Ebene und an einem Service erreichen die zusammengesetzte Datei so, wie sie geschrieben sind, nach jedem Schlüssel, den der Provider auf dieser Ebene modelliert, in der Reihenfolge, in der das Fragment sie enthält; der Provider liest nichts in ihnen, außer dem x-aggrega-networks-of eines Services, das er in Netzwerke auflöst, denen der Service beitritt, und aus der zusammengesetzten Datei weglässt (siehe Den Netzwerken anderer Komponenten beitreten). Ein Körper artifacts: enthält sie in der Reihenfolge, in der er sie schreibt. Die Schlüssel einer quellbasierten compose-Datei erreichen ihr Fragment in Namensreihenfolge, sobald ihr Overlay eingemischt ist, daher werden ihre Erweiterungselemente in Namensreihenfolge geschrieben.

# an artifacts: body
x-owner: team-b
services:
migrate:
image: example/migrate:1
x-schedule: manual

Ein über einen YAML-Alias erreichtes Element wird vollständig ausgeschrieben, und kein Anker wird übernommen, sodass die zusammengesetzte Datei nie einen Alias enthält, dessen Anker ihr fehlt; das ist es, was einem Top-Level-Element erlaubt, einen Anker zu enthalten, den der Merge-Schlüssel eines Services (<<: *base) einbezieht. Die Elemente eines Services reisen mit ihrem Service. Top-Level-Elemente werden innerhalb eines Zusammensetzungspfads nach der Regel vereinigt, der Volumes folgen: Zwei Fragmente, die ein Element mit demselben Inhalt schreiben, hinterlassen einen einzigen Eintrag, ob sie es im Block- oder im Flow-Stil schreiben, und zwei, die es mit unterschiedlichem Inhalt schreiben, brechen den Build mit TRANSLATION_ERROR ab und nennen das Element und jedes beitragende Tupel (boundary, node, fragment) — zwei Fragmente einer Komponente eingeschlossen. Machen Sie die beiden Deklarationen identisch, oder geben Sie einer von ihnen einen anderen Namen.

profiles bindet einen Service an ein Compose-Profil. Ein Service, der profiles: auflistet, ist einer, den docker compose up unberührt lässt, sofern nicht eines seiner Profile aktiviert ist, und den docker compose run --rm <service> auf Anforderung startet — die compose-Form einer bei Bedarf ausgeführten Aufgabe. Die Liste wird so übernommen, wie das Fragment sie schreibt, in ihrer Reihenfolge:

# a sourced compose file
services:
migrate:
image: example/migrate:1
profiles: [manual]

Modelle

Der Top-Level-Abschnitt models: einer compose-Datei deklariert die KI-Modelle, die die Services der Datei verwenden, und einem Service wird ein Modell über seinen eigenen Eintrag models: gewährt. Der Provider übernimmt beides aus einem Fragment in die zusammengesetzte docker-compose.yaml, in der eigenen Schreibweise von Compose, ob das Fragment eine quellbasierte compose-Datei oder ein Körper artifacts: ist, der zu compose-YAML ausgewertet wird. Eine Workload deklariert kein Modell, daher trägt ein Recipe im Workload-Modus keines bei.

  • Der Körper eines Modells wird so geschrieben, wie das Fragment ihn geschrieben hat. model — die OCI-Artefaktkennung des Modells —, context_size und runtime_flags behalten ihre Namen, und jedes andere Element, darunter eine Erweiterung x-, wird neben ihnen übernommen. Innerhalb eines Modells kommen die drei genannten Elemente zuerst und der Rest folgt in Schlüsselreihenfolge, und die Modelle werden in Namensreihenfolge geschrieben, sodass identische Eingabe eine byte-identische Datei erzeugt. Der Provider liest nichts im Körper: Er prüft die Kennung nicht, und er weiß nichts davon, was das Modell ausliefern wird.
  • Der Verweis eines Services behält seine Form. Die Kurzform listet Modellnamen auf (models: [llm]); die Langform ordnet jedes Modell endpoint_var und model_var zu, den Namen der Variablen, die die Adresse des Model Runners und die Kennung des Modells erhalten. Beide werden in der Form und der Reihenfolge geschrieben, die das Fragment verwendet hat, und reisen mit ihrem Service. Wo die Langform eine Variable unbenannt lässt, benennt Compose sie, wenn es die Datei ausführt.
  • Modelle werden innerhalb eines Zusammensetzungspfads vereinigt, nach der Regel, der Volumes folgen. Zwei Beitragende, die einen Modellnamen mit Körpern deklarieren, die identisch ausgegeben werden, hinterlassen einen einzigen Eintrag darunter; zwei, die ihn mit unterschiedlichen Körpern deklarieren, brechen den Build mit TRANSLATION_ERROR ab und nennen das Modell und jedes beitragende Tupel (boundary, node, fragment). Zwei Fragmente einer Komponente sind auch hier zwei Beitragende. Machen Sie die Deklarationen identisch, wo beide Beitragende ein Modell meinen, oder geben Sie einer von ihnen einen anderen Namen.
  • Jeder Verweis nennt ein deklariertes Modell. Sobald die Fragmente des Zusammensetzungspfads vereinigt sind, bricht ein Service, dem ein Modell gewährt wird, das kein Beitragender an diesem Pfad deklariert, den Build mit TRANSLATION_ERROR ab und nennt den Service und das Modell. Die Prüfung läuft über die vollständige Vereinigung, sodass eine Komponente ihrem Service ein Modell gewähren darf, das eine andere Komponente am selben Zusammensetzungspfad deklariert.
  • Ein Eintrag omits: kann kein Modell weglassen. service, volume und config sind die Arten, die dieser Provider akzeptiert, und ein Eintrag, der ein Modell nennt, bricht den Build ab wie einer, der irgendeine andere Art nennt.

Die Modelle werden ausgeliefert, wenn die Datei läuft, nicht wenn sie gebaut wird. Docker Compose 2.38 oder neuer zieht auf einer Plattform, die Compose-Modelle unterstützt, wie Docker Model Runner, jedes Modell, das einem Service gewährt wird, und führt es aus, wobei jedes andere ausgelassen wird, sofern nicht mit --all-resources gestartet wird, und setzt in jedem Service, dem es gewährt wird, die Variablen, die sein Verweis nennt, auf die Adresse des Model Runners und die Kennung des Modells. Der Build kann den Host nicht sehen, der die Datei ausführen wird, daher prüft er weder die Compose-Version noch die Plattform: Eine Datei, die Modelle trägt, wird gleich zusammengesetzt, was auch immer sie ausführt.

Ein an eine Komponente angebundenes Feature trägt zur selben Datei bei

Ein an eine Komponente angebundenes Feature trägt seine Services zu der docker-compose.yaml bei, in die seine Host-Komponente zusammengesetzt wird, zu denselben Bedingungen wie das eigene Recipe des Hosts. Daneben gibt es keine zweite Datei: Ein Zusammensetzungspfad erzeugt ein Dokument, daher sind die Services eines angebundenen Feature entweder in diesem Dokument, oder sie werden überhaupt nicht bereitgestellt. Das Lösen der Anbindung des Feature entfernt genau diese Services und lässt die eigenen der Host-Komponente unberührt.

Sie sind Beitragende an diesem Zusammensetzungspfad wie alle anderen, daher gilt alles Obige unverändert für sie — die Regel für Service-Namen und die Anforderung, dass zwei Beitragende, die einen Top-Level-Volume- oder Konfigurationsnamen deklarieren, sich darüber einig sind, was er ist. Sie treten außerdem demselben Netzwerk bei wie der Rest der Boundary, sodass eine Komponente und ein an sie angebundenes Feature einander über den Service-Namen erreichen, ohne dass weiter etwas zu deklarieren ist.

Jeder Service, den ein Feature beiträgt, trägt die für diese Anbindung gebildete Identität statt der der Host-Komponente, sodass beide innerhalb eines Dokuments unterscheidbar bleiben, zu dem beide beigetragen haben. Labels und Annotationen beschreibt, wie diese Identität gebildet wird.

Dies ist ein anderer Mechanismus als der Block attachments: einer Workload auf Container-Ebene, und die beiden lassen sich leicht als einer lesen, weil sie ein Wort teilen. Ein Feature an eine Komponente anzubinden fügt dem zusammengesetzten Dokument Services hinzu; der Eintrag attachments: eines Containers liest eine Anmeldeinformation, die ein Slot in genau diesen einen Container veröffentlicht hat, und wird unter Container-Felder behandelt.

Als Artefakte ausgegebene compose-Fragmente

Wenn der Block artifacts: eines Recipe zu compose-YAML ausgewertet wird — einem Fragment, das eigene Blöcke services:, volumes:, configs:, models: oder networks: trägt (jeder Eintrag inline oder pro Eintrag über $import: geladen) —, folgt die Zusammenführung in die Zusammensetzung pro (path, provider) formspezifischen Regeln:

  • services: aus Artefakten werden neben den Services pro Komponente in die zusammengesetzte compose-Datei zusammengeführt. Ein Service-Name, den zwei verschiedene Komponenten am selben Zusammensetzungspfad beitragen, bricht den Build ab, und die Diagnose nennt jeden Beitragenden. Eine Kollision innerhalb einer einzelnen Komponente — zwischen dem eigenen Artefakt-Fragment dieser Komponente und den für sie synthetisierten Services — wird nicht erkannt, und der spätere Beitrag ersetzt den früheren; halten Sie einen in einem Artefakt verfassten Service-Namen daher von den Namen <component> und <component>--<container-name> getrennt, die der Synthesizer erzeugt (siehe Wie ein Sidecar- oder Init-Service benannt wird).
  • volumes: aus Artefakten werden in den Top-Level-Block volumes: zusammengeführt. Zwei Einträge, die bei einem Namen ankommen, hinterlassen darunter einen einzigen Eintrag, wo sie ihn identisch deklarieren, nach derselben Regel wie Volumes pro Komponente; zwei, die ihn unterschiedlich deklarieren, brechen den Build ab, ob sie von zwei Komponenten stammen oder von zwei Fragmenten einer einzigen — zwei ihrer Einträge in artifacts: oder einer davon und die eigene compose-Datei der Komponente. Weil ein Artefakt-Fragment seine eigenen Körper schreibt, ist dies der Weg, auf dem zwei Beitragende am ehesten uneins sind. Halten Sie einen in einem Artefakt verfassten Volume-Namen von den anderen an seinem Zusammensetzungspfad getrennt, auch von der Form <component>--<volume-name>, die die Ableitung erzeugt — es sei denn, zwei Beitragende sollen ein einziges gemeinsames Volume beschreiben; dann müssen ihre Deklarationen übereinstimmen.
  • configs: aus Artefakten werden in den Top-Level-Block configs: zusammengeführt. So erreicht die Datei hinter einem Volume configmap die Zusammensetzung: Das Volume wird zu einem Verweis configs: auf Service-Ebene, der die Configmap nennt, und das Artefakt-Fragment deklariert einen Eintrag dieses Namens mit inline content:. Sobald die Fragmente des Zusammensetzungspfads vereinigt sind, muss jeder Verweis auf Service-Ebene zu einem deklarierten Eintrag aufgelöst werden, oder der Build bricht mit TRANSLATION_ERROR ab und nennt jeden nicht aufgelösten Verweis — den Service, den Konfigurationsnamen und den Mount-Pfad. Die Prüfung läuft über die vollständige Vereinigung statt pro Komponente, sodass eine Komponente auf eine Konfiguration verweisen kann, die eine andere Komponente am selben Zusammensetzungspfad deklariert. Die Vereinigung gleicht nach Namen ab, wo die Beitragenden übereinstimmen: Zwei, die einen Konfigurationsnamen mit identischem content: deklarieren, hinterlassen den einzigen Eintrag, den beide beschrieben haben. Zwei, die einen Namen mit unterschiedlichem content: deklarieren, brechen den Build mit TRANSLATION_ERROR ab und nennen die Konfiguration und jedes beitragende Tupel (boundary, node, fragment), zwei Fragmente einer Komponente eingeschlossen — ein Konfigurationseintrag trägt immer Inhalt, sodass das Beibehalten einer der beiden Deklarationen eine Datei verwerfen würde, die ein Autor geschrieben hat. Halten Sie einen Konfigurationsnamen über alle Beitragenden an seinem Zusammensetzungspfad hinweg eindeutig, oder machen Sie die Deklarationen identisch, wo zwei Beitragende eine einzige gemeinsame Datei liefern sollen.
  • models: aus Artefakten werden in den Top-Level-Block models: zusammengeführt, und der Verweis models: eines Service wandert mit seinem Service, nach den Regeln in Modelle: Zwei Beitragende, die einen Modellnamen deklarieren, müssen ihn identisch deklarieren, und jeder Verweis muss ein Modell nennen, das irgendein Beitragender am Zusammensetzungspfad deklariert.
  • networks: aus Artefakten werden abgelehnt. Der compose-Provider leitet Netzwerke aus den Annotationen der Boundary ab (ein Netzwerk pro unterschiedlicher Annotation aggrega.ai/namespace, plus eines, das nach dem Pfad der compose-Datei benannt ist und dem jeder Knoten ohne eine solche Annotation beitritt, jedes benannt gemäß Wie ein Netzwerkname abgeleitet wird), sodass eine von einem Artefakt gelieferte Netzwerkdeklaration in der zusammengesetzten Datei keinen Platz hat: Jeder Eintrag bricht den Build ab und nennt den Eintrag und das Fragment, nach den Regeln in Jeder Schlüssel, den ein Fragment schreibt, wird übernommen oder abgelehnt. Entfernen Sie den Eintrag und gestalten Sie Netzwerke über die Annotation aggrega.ai/namespace, oder lassen Sie einen Service über x-aggrega-networks-of den Netzwerken benannter Komponenten beitreten; Autoren, die netzwerkübergreifendes Routing innerhalb einer einzelnen compose-Datei benötigen, verwenden das Feature compose-bridge.
  • Erweiterungselemente aus Artefakten werden übernommen. Ein Top-Level-Schlüssel x- wird nach den anderen Abschnitten der zusammengesetzten Datei geschrieben, in der geschriebenen Reihenfolge, nach den Regeln in Erweiterungselemente werden so übernommen, wie sie geschrieben sind.
  • Jeder andere Top-Level-Schlüssel aus Artefakten bricht den Build ab. services:, volumes:, configs:, models: und die Erweiterungselemente sind alles, was der Assembler aus einem Fragment übernimmt. Ein Block secrets: und ein name: auf oberster Ebene brechen den Build jeweils ab und nennen den Schlüssel und das Fragment, nach den Regeln in Jeder Schlüssel, den ein Fragment schreibt, wird übernommen oder abgelehnt.
  • Ein Körper artifacts: ist ein einziges Dokument. Ein Körper, der mehrere YAML-Dokumente enthält, bricht den Build ab und nennt das Fragment und wie viele Dokumente es enthält; geben Sie jedem Dokument einen eigenen Eintrag artifacts:.

Die Asymmetrie zwischen den ersten vier und networks: ist strukturell: services:, volumes:, configs: und models: tragen Inhalt pro Recipe, den der Assembler in der zusammengesetzten Datei ansammelt; networks: ist Infrastruktur pro Boundary, die der Assembler aus dem Zustand der Boundary ableitet. Artefakte können Ersteres erweitern; nur Annotationen der Boundary können Letzteres gestalten, weshalb der eigene Netzwerkeintrag eines Artefakts abgelehnt wird. Erweiterungselemente sind Daten, die die Compose Specification für andere Werkzeuge definiert, daher werden sie so übernommen, wie sie geschrieben sind. Alles andere ist eine Form, für die das zusammengesetzte Dokument keinen Platz hat, weshalb es abgelehnt statt zusammengeführt wird.

Was der compose-Provider nicht liefert

  • Netzwerkübergreifendes L4-Routing innerhalb einer compose-Datei. Der Provider platziert jeden Knoten in seinem Netzwerk und lässt einen Service den Netzwerken beitreten, die x-aggrega-networks-of nennt, und routet selbst nichts zwischen Netzwerken. Ein Service in Netzwerk A, der einen Service in Netzwerk B über etwas anderes als das Standard-DNS von docker-compose erreicht, erfordert das Feature compose-bridge, dessen FeatureRecipe das Gateway und die Umschreibung schreibt.
  • Routing über compose-Dateien hinweg. Boundaries, die zu unterschiedlichen Zusammensetzungspfaden ausgewertet werden, erzeugen unterschiedliche Dateien docker-compose.yaml; die compose-Laufzeit behandelt sie als unabhängige Projekte, und das Feature compose-bridge lässt eine Verbindung zwischen zwei Dateien so, wie sie geschrieben ist. Dateiübergreifende Kommunikation ist Sache des Betreibers (Host-Ports veröffentlichen, externe Netzwerke teilen oder die Boundaries über ein gemeinsames directory: auf einen Pfad zusammenlegen).
  • Eine Umgebungsvariable aus einer Anbindung beziehen. Compose hat dafür kein Primitiv, daher gibt ein Eintrag attachments einer Workload mit as: env den Variablennamen mit leerem Wert aus statt eines zur Laufzeit aufgelösten Verweises. Der Platzhalter ist beabsichtigt — eine Variable, die vorhanden, aber leer ist, ist für jeden sichtbar, der den Container debuggt, während eine fehlende nichts zum Ansehen hinterlässt —, und der Build sagt es, statt es entdecken zu lassen: Jeder solche Eintrag löst eine Warnung unsupported-field aus, die den Eintrag an seiner Authoring-Koordinate nennt (containers.<name>.attachments.<KEY> oder initContainers[<i>].attachments.<KEY>), sodass der Autor weiß, welche Variable leer ankommt und zu welchem Container sie gehört. Die Warnung ist beratend: Der Build gelingt, und die gerenderte Datei ist Byte für Byte das, was sie ohne die Warnung wäre. --no-unsupported-field-warnings unterdrückt die Klasse. Ein Eintrag attachments mit as: file ist nicht betroffen — compose bindet ihn per Bind-Mount ein, und es wird keine Warnung ausgelöst.
  • Inhalt von deploy: im Swarm-Modus. Replikate, Platzierungsbedingungen und Update-Strategie unter deploy: sind Funktionen des Swarm-Modus, und der compose-Provider zielt nur auf compose auf einem einzelnen Host ab, daher gibt er keine davon aus. Er gibt jedoch deploy.resources aus — die Reservierungen und Limits, auf die die resources eines Containers abgebildet werden und die docker compose außerhalb des Swarm-Modus berücksichtigt (siehe Container-Ressourcen).
  • An die Gesundheitsbedingung gebundenes depends_on aus einer Kante uses. Eine aus einer Kante uses abgeleitete Abhängigkeit wird ohne Bedingung ausgegeben, mit der Semantik service_started; sie ist nicht daran gebunden, dass der Healthcheck des Ziels einen gesunden Zustand meldet. Es geht dabei darum, was eine Kante uses bedeutet, nicht um eine Form, die der Provider nicht erzeugen kann: Die Langform wird für das Warten auf einen Init-Container ausgegeben, und eine Bereitstellungswelle bindet das Warten sehr wohl an die Gesundheit des Ziels, wo das Ziel einen Healthcheck deklariert.

Authoring-Beispiel

Eine compose-Bereitstellung mit zwei Services und einer aus uses abgeleiteten depends_on-Kante:

# release.yaml fragment
spec:
boundaries:
production:
annotations:
aggrega.ai/namespace: prod
components:
api: {}
db: {}
# api Recipe
apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: api
version: 1.0.0
spec:
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 declares
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
spec:
components:
api:
type: example/compute/api:1.0.0
uses:
backend:
db:
target: db
db:
type: example/datastore/db:1.0.0

Der compose-Provider erzeugt eine einzige docker-compose.yaml am ausgewerteten Pfad der Boundary (standardmäßig dist/boundaries/production/compose/docker-compose.yaml, weil das directory: einer Boundary standardmäßig dist/boundaries/<name> ist und subDirectory: standardmäßig {{ .capability }}), die Folgendes enthält:

  • services.api (der Haupt-Service api, Netzwerk prod, Ports 8080:8080, Healthcheck über curl, depends_on: [db])
  • services.db (der Haupt-Service db, Netzwerk prod)
  • networks.prod (das Docker-Netzwerk der Boundary)