Provider Compose
Il provider compose renderizza le Recipes di Aggrega in un file Docker Compose. Il provider assembla per (path, provider): i contributori compose di ogni confine vengono instradati all’assemblatore indicizzato sulla directory: valutata del confine unita alla subDirectory: di ciascun componente, e quell’assemblatore emette un unico docker-compose.yaml che contiene ogni contributore in quel percorso. Due confini fratelli che si valutano nello stesso percorso confluiscono in un unico file compose unito — l’esempio canonico è un confine padre più due confini figli con directory: "{{ .parent_boundary.directory }}" (il pattern compose-bridge).
Tipi di input supportati
Il provider compose accetta tutti e tre i tipi di input di una Recipe:
- Modalità da sorgente. Una Recipe con
source:che punta a un file compose esistente piùvaluesMapping:che produce un documento di overlay. Il file compose di base viene caricato, l’overlay viene valutato, e i due vengono uniti in profondità secondo la semantica di overlay nativa di docker-compose. - Modalità Workload. Una Recipe con
workload:(inline o caricato tramite$import:) dichiara un documentoWorkload. Il provider sintetizza uno o più servizi compose dalla specifica del Workload. - Modalità artefatti. Le voci
artifacts:di una Recipe si valutano in frammenti compose, che si uniscono nel file assemblato secondo le regole in Frammenti compose emessi come artefatti. Gli artefatti possono affiancare una sorgente o un Workload, e possono anche costituire l’intero output di una Recipe: una Recipe che dichiaraartifacts:e nésource:néworkload:viene renderizzata qui, contribuendo con ciò che i suoi frammenti dichiarano. È così che un componente fatto solo di risorse — un insieme condiviso di rete e volumi, una config precaricata — raggiunge una distribuzione compose senza un Workload segnaposto che faccia le veci di una capacità di calcolo che non ha.
I tre tipi si compongono per addizione, e una Recipe che non ne dichiara nessuno viene rifiutata al caricamento. Anche un valuesMapping: senza un source: accanto viene rifiutato al caricamento della Recipe, qualunque provider essa nomini: non c’è nulla a cui applicare l’overlay, e la diagnostica ti chiede di dichiarare il puntatore source: o di eliminare il valuesMapping:.
Mappatura delle funzionalità del Workload
Quando una Recipe dichiara workload:, il provider traduce la forma Workload di proprietà della piattaforma in primitive compose. La mappatura è volutamente ristretta — la superficie di Compose è più povera di forme rispetto a Kubernetes, e diverse funzionalità del Workload degradano all’equivalente compose più vicino con una perdita documentata.
Campi del container
| Campo del Workload | Campo di Compose |
|---|---|
image | image |
imagePullPolicy: Always / IfNotPresent / Never | pull_policy: always / if_not_present / never |
command | entrypoint (forma a lista) — sovrascrive il punto di ingresso dell’immagine, ed è la chiave compose che fa proprio questo |
args | command (forma a lista) — fornisce gli argomenti che il punto di ingresso riceve, ed è ciò che il command di compose sovrascrive |
variables | environment (forma a mappa) |
attachments[as: env] | voce di environment con valore vuoto, e un avviso che nomina la voce (vedi Cosa non fornisce il provider compose) |
attachments[as: file] | voce volumes in forma lunga di bind-mount, in sola lettura |
volumeMounts | la primitiva compose a cui corrisponde la variante di volume referenziata — una voce volumes in forma lunga, una voce tmpfs: a livello di servizio o un riferimento configs: a livello di servizio (vedi Volumi) |
ports | implicito (i container compose espongono le porte su cui l’immagine è in ascolto) |
restartPolicy: Always | restart: unless-stopped |
restartPolicy: OnFailure | restart: on-failure |
restartPolicy: Never | restart: "no" |
variables e attachments[as: env] confluiscono nell’unica mappa environment, prima le voci delle associazioni e poi le variables, ciascuna nell’ordine in cui è scritta — l’ordine che scrive il provider helm, così un Workload produce una sola sequenza di ambiente su ogni destinazione. Compose non espande alcun riferimento $(NAME) tra le voci di ambiente di un servizio, quindi su compose quell’ordine non ha alcun significato a runtime. Poiché la mappa contiene ogni nome una sola volta, un container che fornisce uno stesso nome sia come voce di variables sia come voce di attachments consegnata as: env arresta la build anziché mantenere uno dei due valori (vedi A container gives one environment variable two values (Un container assegna due valori a una stessa variabile d’ambiente)).
Risorse dei container
Le resources di un container raggiungono il blocco deploy.resources di compose, che docker compose rispetta in modalità non swarm. Le requests di Kubernetes esprimono un minimo garantito, quindi diventano reservations di compose; i limits esprimono un tetto rigido, quindi restano limits.
| Campo del Workload | Campo di Compose | Traduzione |
|---|---|---|
resources.requests.cpu | deploy.resources.reservations.cpus | Un numero decimale di core. Un numero di core scritto come numero semplice (2, 0.5) viene emesso così come è scritto; qualsiasi altra forma viene convertita dal suo valore (500m → 0.5, 1500m → 1.5, 5n → 0.000000005, 1e1 → 10) |
resources.limits.cpu | deploy.resources.limits.cpus | Stessa conversione |
resources.requests.memory | deploy.resources.reservations.memory | Un numero esatto di byte, convertito dal valore in qualunque forma sia scritto — 8Gi diventa 8589934592, 1.5Gi diventa 1610612736, 1e3 diventa 1000 |
resources.limits.memory | deploy.resources.limits.memory | Stessa conversione |
nvidia.com/gpu, sotto resources.limits, resources.requests o entrambi | deploy.resources.reservations.devices | Una voce di dispositivo NVIDIA sul servizio del container — driver: nvidia, count: il numero di GPU, capabilities: [gpu]. Il numero è quello del limite dove è scritto un limite — il numero che Kubernetes pianifica per una risorsa estesa — e altrimenti quello della richiesta. Un numero pari a 0 non chiede alcuna GPU e non scrive alcuna voce |
qualsiasi altra chiave di risorsa estesa — amd.com/gpu e ogni altro <domain>/<name> | — | Nessun analogo compose su un singolo host. La chiave viene scartata e la build genera un avviso unsupported-field che la nomina, uno per ogni chiave distinta, indipendentemente da quante tra requests e limits la contenessero. Il suo valore non viene emesso, quindi non viene controllato |
Ogni valore cpu, memory e nvidia.com/gpu viene letto come quantità, nella forma esposta in Workload → Quantità di risorse, sul Workload così come lo hanno valutato i template della Recipe. Due cose arrestano la build con un TRANSLATION_ERROR, e l’errore dice quale delle due ha incontrato, nominando il percorso del container, se il valore è una richiesta o un limite, la risorsa e il valore:
- un valore che non è una quantità —
lots,1.5 cores, oppure lamche un template vuoto lascia in"{{ .infra.cpu }}m"; - una quantità che compose non può rappresentare esattamente — un importo negativo; un importo di memoria che non è un numero intero di byte (
1500m,4u) o che supera 9223372036854775807 byte (8Ei); un importo di cpu più fine di nove cifre decimali di un core, la precisione più fine che una quantità Kubernetes stessa conserva, o superiore a 9223372036.854775807 core; un numero di GPU che non è un numero intero di dispositivi (0.5,500m).
Un container la cui richiesta e il cui limite nvidia.com/gpu chiedono numeri diversi arresta la build allo stesso modo, nominando entrambi i percorsi: compose riserva un solo numero per un servizio, quindi altrimenti la traduzione dovrebbe sceglierne uno. Scrivi lo stesso numero in entrambi, oppure solo il limite.
Nulla viene arrotondato, e non viene emesso alcun valore che significhi qualcos’altro.
Una richiesta di GPU riserva GPU NVIDIA. Un container del Workload che chiede nvidia.com/gpu: "1" viene renderizzato come un servizio che porta questa riserva, accanto a qualsiasi cpus e memory riservati dalle sue richieste:
deploy: resources: reservations: devices: - driver: nvidia count: 1 capabilities: - gpuDocker Compose consegna le GPU riservate al container quando l’host Docker ha quel numero di GPU NVIDIA ed è configurato per darle ai container; la build non può vedere l’host, quindi un file che riserva GPU viene assemblato allo stesso modo ovunque verrà eseguito. La voce indica sempre il proprio numero, perché Compose legge una voce di dispositivo senza numero come tutte le GPU dell’host. Viene tradotta solo la chiave NVIDIA: amd.com/gpu e la chiave di ogni altro fornitore mantengono l’avviso della riga delle chiavi scartate. La riga runtimeClassName in Campi a livello di pod è invariata — compose non ha un analogo della runtime class, quindi a un Workload che nomina un runtime abilitato per GPU viene detto che il runtime è stato omesso, mentre il suo numero di GPU viene riservato.
Probe
I tre slot di probe di un Workload (live, ready, startup) si riducono all’unico healthcheck per servizio di compose, con priorità live > ready > startup (vince il segnale di liveness più canonico). Dove quella riduzione scarta uno slot dichiarato dall’autore, la build genera un avviso unsupported-field che nomina lo slot tradotto e gli slot scartati, così un intento che non raggiunge alcuna parte dell’output viene segnalato anziché perso. Un blocco health che dichiara un solo slot si traduce senza perdita e non genera nulla, a meno che lo slot imposti successThreshold: un healthcheck compose non ha un campo per esso, quindi un valore scritto dall’autore — 1 compreso — viene omesso con un avviso unsupported-field che lo nomina (containers.<name>.health.<slot>.successThreshold), e il resto dello slot si traduce come mostra la tabella seguente.
| Forma della probe del Workload | healthcheck.test di Compose |
|---|---|
http: /path | ["CMD-SHELL", "curl -f http://localhost:<port>/path || exit 1"] |
tcp: <port> | ["CMD-SHELL", "nc -z localhost <port>"] |
exec: [cmd, ...] | ["CMD", cmd, ...] |
La forma HTTP richiede che il container dichiari almeno una porta con nome; il sintetizzatore sceglie il nome di porta che viene primo in ordine alfabetico e ne usa il numero per costruire l’URL di curl. I container senza porte dichiarate non possono usare probe HTTP — il compilatore si arresta con un TRANSLATION_ERROR che nomina la probe incriminata.
I campi di timeout delle probe corrispondono a stringhe di durata in stile compose:
| Campo del Workload | Campo healthcheck di Compose |
|---|---|
periodSeconds | interval: <n>s |
timeoutSeconds | timeout: <n>s |
failureThreshold | retries: <n> |
initialDelaySeconds | start_period: <n>s |
Volumi
Compose ha una primitiva di config propria, che è ciò in cui si traduce un volume configmap. Non ha un equivalente Kubernetes per i Secret né per i template di volume per replica, quindi quelle varianti degradano alla primitiva compose più vicina:
| Variante di volume del Workload | Traduzione di Compose | Note sulle perdite |
|---|---|---|
ephemeral | voce di lista tmpfs: a livello di servizio | sizeLimit non viene preservato (la forma breve di tmpfs in compose non ha una dimensione). Un sizeLimit scritto dall’autore genera un avviso unsupported-field che lo nomina alla sua coordinata di authoring (volumes.<name>.ephemeral.sizeLimit), che un container monti o meno il volume; omettere il campo non genera nulla |
configmap | riferimento configs: a livello di servizio che nomina la configmap, montata nel percorso del montaggio del volume | 🔴 Il percorso di montaggio è il percorso di un singolo file, non di una directory. Compose scrive il contenuto della config esattamente nel percorso di destinazione, mentre una destinazione Kubernetes che monta una ConfigMap in un percorso produce una directory che contiene un file per chiave. Così lo stesso path: scritto dall’autore indica qui un file e là una directory: punta il montaggio di un volume configmap al nome del file che il container deve leggere (/seed/config.json), non alla directory che lo conterrebbe, e una Recipe scritta per entrambe le destinazioni riporta un percorso diverso per ciascuna destinazione. Nulla nella build può intercettare un percorso scritto per la forma dell’altra destinazione — il percorso è una stringa opaca che il compilatore fa passare così com’è, e l’output emesso è valido in entrambi i casi. Il riferimento è per nome, esattamente come una destinazione Kubernetes fa riferimento a una risorsa ConfigMap — nulla legge il contenuto della config. La voce configs: di primo livello corrispondente proviene dall’input artifacts: della Recipe, il cui frammento compose la dichiara con content: inline; un riferimento senza una tale voce arresta la build (vedi Frammenti compose emessi come artefatti). Un riferimento configs: porta il nome della config e il percorso di montaggio e nient’altro, quindi il readOnly del montaggio non ha un’espressione separata |
secret | voce volumes in forma lunga di bind-mount, in sola lettura | Un volume secret deliberatamente non segue la traduzione configmap: una voce configs: inline scriverebbe il valore del secret in chiaro nel file compose emesso, e il compilatore non risolve mai un secret in chiaro — un secret resta un puntatore in ogni fase della build. La sorgente del bind è il nome source del secret, risolto come un percorso che l’operatore rende raggiungibile sull’host compose indipendentemente dalla build |
persistent | volume con nome + dichiarazione volumes: { <volume-name>: {} } di primo livello, nominato secondo Come viene derivato il nome di un volume | Classe di storage, modalità di accesso e dimensione non vengono preservate (compose non ha una forma equivalente). Un class o un accessModes scritto dall’autore genera un avviso unsupported-field che lo nomina alla sua coordinata di authoring (volumes.<name>.persistent.class, volumes.<name>.persistent.accessModes); ometterli non genera nulla. Il size obbligatorio non genera alcun avviso — vedi sotto |
persistentTemplate | volume con nome + dichiarazione di primo livello, nominato allo stesso modo (come per persistent) | Complemento di form: stateful; compose non ha una primitiva di templating dei volumi per replica, quindi il comportamento per replica va perso, e un avviso unsupported-field segnala che il volume è diventato un unico volume condiviso da tutte le repliche. Classe di storage, modalità di accesso e dimensione non vengono preservate, esattamente come per persistent: un class o un accessModes scritto dall’autore genera un avviso unsupported-field in volumes.<name>.persistentTemplate.class o volumes.<name>.persistentTemplate.accessModes, e il size obbligatorio non ne genera alcuno |
Il subPath di un montaggio monta una parte di un volume dove compose ha una forma per farlo. Una voce volumeMounts che nomina un volume persistent o persistentTemplate con subPath diventa una voce volumes in forma lunga che porta volume.subpath, così il montaggio vede la directory o il file indicato all’interno del volume anziché la sua radice, e due montaggi di uno stesso volume con due valori subPath diversi ne vedono due parti diverse:
volumes: - type: volume source: store--data target: /var/lib/app/db volume: subpath: db - type: volume source: store--data target: /var/lib/app/uploads volume: subpath: uploadsUn montaggio scritto senza subPath non porta alcun blocco volume:. Un subPath su un montaggio di un volume ephemeral, configmap o secret arresta la build con un errore TRANSLATION_ERROR che nomina il componente, il container, il percorso di authoring del montaggio (containers.<name>.volumeMounts[<i>]), il volume e il subPath: quelle varianti arrivano a compose come voce tmpfs, riferimento configs: e montaggio bind, nessuno dei quali monta una parte di ciò che fornisce, quindi altrimenti il montaggio vedrebbe l’intero volume. Rimuovi subPath da un tale montaggio, oppure monta un volume persistent. Docker Compose legge volume.subpath a partire dalla versione 2.26.0, su Docker Engine 26.0 o successivo; la build non può vedere l’host che eseguirà il file, quindi un file che ne contiene uno viene assemblato allo stesso modo ovunque verrà eseguito.
Un volume dice quale variante è e nient’altro. Un volume secret ha esattamente una traduzione — il montaggio bind in sola lettura descritto sopra — e un volume non porta alcun campo as: per selezionarne un’altra. Consegnare ciò che uno slot ha pubblicato come variabile d’ambiente è compito di una voce attachments del container (as: env) anziché di un volume; ciò che compose fa con una tale voce è descritto in Cosa non fornisce il provider compose.
Tre varianti portano una dimensione di storage, e solo una di esse avvisa che la dimensione è stata scartata. La differenza sta nell’avere avuto o meno una scelta. Il sizeLimit di un volume ephemeral è facoltativo, quindi scriverlo è stata una decisione, e l’avviso ti dice che il valore non modella nulla su questa destinazione e può essere rimosso — è consultivo e fuori banda, il file emesso è byte per byte ciò che sarebbe senza di esso, e --no-unsupported-field-warnings lo silenzia insieme al resto della classe. Il size di un volume persistent o persistentTemplate è obbligatorio, quindi nessuna versione del documento lo omette: un avviso a ogni build lì scatterebbe su ogni carico di lavoro stateful senza nominare nulla che tu possa cambiare, quindi la differenza viene spiegata qui anziché segnalata a ogni build. Con compose come destinazione, size, class e accessModes di un volume persistente non modellano nulla nel file emesso — ciò che ottieni è un semplice volume con nome, dimensionato e supportato da ciò che fa per impostazione predefinita il driver di volume dell’host compose. class e accessModes sono facoltativi, quindi ciascuno che scrivi viene segnalato come il sizeLimit di un volume ephemeral: un avviso unsupported-field per campo, consultivo e fuori banda, silenziato dallo stesso flag. Dimensiona lo storage sottostante sull’host, oppure sulla destinazione Kubernetes, dove i campi raggiungono l’output.
Un volume che nessun container monta genera un avviso unsupported-field che lo nomina alla sua coordinata di authoring (volumes.<name>), perché ciò che raggiunge il file emesso differisce allora nettamente a seconda della variante. persistent e persistentTemplate producono comunque la loro dichiarazione di primo livello, quindi il volume viene creato e nulla lo usa. ephemeral, configmap e secret non hanno alcuna espressione al di fuori del montaggio stesso — ciascuno si traduce in qualcosa scritto nel percorso di montaggio, rispettivamente una voce tmpfs, un riferimento configs o un montaggio bind — quindi, se nulla ne monta uno, il volume che hai dichiarato non lascia alcuna traccia nell’output. Questo secondo caso è il motivo per cui l’avviso esiste: senza di esso, un volume configmap di cui hai dimenticato il montaggio sarebbe semplicemente assente, senza nulla nel file emesso da notare. Ogni container del carico di lavoro conta come container che monta il volume, init container compresi, quindi un volume montato solo da un init container è collegato e non genera nulla. L’avviso è consultivo e fuori banda — il file emesso è byte per byte ciò che sarebbe senza di esso — e --no-unsupported-field-warnings silenzia la classe.
Come viene derivato il nome di un volume
Un volume persistent o persistentTemplate diventa un volume con nome di compose: una voce volumes: di primo livello, referenziata da ogni container che lo monta. Un volume compose è storage condiviso, e il blocco volumes: di primo livello unisce le proprie voci per nome — quindi due volumi scritti dall’autore che arrivano a uno stesso nome diventano un solo volume in cui scrivono entrambi i container, senza nulla nel file emesso che mostri che ne erano previsti due. Il nome è quindi costruito a partire dalle due identità che insieme dicono di quale volume si tratta: il <component> a cui il volume appartiene, e il nome che il Workload ha dato al volume sotto volumes:.
Il nome di un volume compose accetta un insieme di caratteri più ristretto di quello che ciascuna delle due identità può contenere: lettere, cifre, punti, underscore e trattini. Anziché sostituire un carattere che compose non accetta, la derivazione lo scrive per esteso, così due volumi che differiscono in qualsiasi modo arrivano a due nomi — e un nome assemblato può essere ricondotto alle due identità da cui è stato costruito.
- Una lettera, una cifra, un punto e un underscore vengono riportati esattamente come scritti dall’autore.
- Un trattino viene mantenuto come scritto dall’autore ovunque il carattere che lo segue sia riportato direttamente e non sia una
zminuscola. Un trattino seguito da unazminuscola apre una sequenza di escape, quindi uno scritto dall’autore in quella posizione viene a sua volta scritto per esteso —api-zonediventaapi-zhzone, ed è questo che permette di ricondurre qualsiasi nome senza dover indovinare. Un trattino senza nulla dopo di sé viene scritto per esteso per lo stesso motivo, quindidb-dàdb-zh. - Ogni altro carattere viene scritto come
-zseguito da una lettera che lo identifica:sper un separatore di percorso,hper un trattino che la regola precedente non mantiene. Qualsiasi altra cosa — compresi uno spazio e una lettera non ASCII — viene scritta comexseguito dal punto di codice esadecimale a sei cifre del carattere, e un byte che non inizia alcun carattere comebseguito dal proprio valore a due cifre, così un nome che non è testo valido viene comunque scritto per esteso in modo distinto anziché essere fuso con un altro. - Un valore vuoto viene scritto
-ze, che nessun valore non vuoto può produrre. - Le due identità sono unite da
--. Una singola identità codificata non contiene mai quella coppia, quindi il nome unito dice senza ambiguità dove finisce un’identità e dove inizia l’altra.
Così il componente store con un volume che il Workload chiama data dà il nome di volume store--data, e db-server con data dà db-server--data. Un input identico produce sempre il nome identico.
È la giunzione doppia a rendere la coppia non ambigua, e una giunzione di un solo carattere non può farlo. Ciascuna identità può contenere essa stessa un trattino, quindi una giunzione con un solo trattino lascia un nome che si divide in più di un punto: db con un volume chiamato data-cache e db-data con un volume chiamato cache darebbero entrambi db-data-cache, e poiché il blocco di primo livello unisce per nome, i due componenti condividerebbero un solo volume senza nulla nel file emesso che lo mostri. Un’identità codificata non contiene mai una coppia di trattini, quindi la giunzione doppia non ammette una seconda lettura: i due arrivano a db--data-cache e db-data--cache.
Cambiare una delle due identità rinomina il volume compose, e compose non rinomina un volume sul posto. Il volume viene creato da zero con il nuovo nome mentre quello vecchio resta indietro con i dati al suo interno, quindi il container si avvia con uno storage vuoto e i contenuti restano in un volume che nulla monta. Rinomina una delle due identità solo come una sostituzione da pianificare — con backup, copia dei dati o una finestra programmata — anziché come una modifica da distribuire e basta.
Forma del controller
Il form del Workload seleziona una forma astratta di controller (vedi entities/workload.md). Compose esegue il rendering di stateless e stateful (e del valore predefinito vuoto, trattato come stateless) come servizi di lunga durata; la forma stateful aggiunge il volume con nome per un complemento persistentTemplate. Le forme daemon, scheduled e task non hanno una mappatura compose pulita su un singolo host, quindi un Workload che ne dichiara una avendo come destinazione un confine compose arresta la build con un errore TRANSLATION_ERROR che nomina la forma e l’insieme supportato — compose non degrada una forma non supportata in un semplice servizio che travisa l’intento. Un Workload reference dichiara un endpoint esterno e nessun container, quindi compose non emette alcun servizio per esso.
Poiché per un Workload reference non viene emesso alcun servizio, nulla legge la pipe di consegna del componente che esso realizza: una credenziale associata a quel componente — consegnata sulla sua pipe da dotenv-secret, o dal blocco inject: proprio di un’associazione — non raggiungerebbe alcun file emesso. Ogni Recipe Compose della libreria standard che realizza in questo modo un servizio esterno, e il cui Component dichiara uno slot di credenziali, rifiuta quindi una credenziale che riempie quello slot: la build si arresta nominando lo slot e il componente, anziché riuscire con la credenziale assente. Su compose, una credenziale per un servizio esterno viene associata al componente che lo chiama, sotto la variabile d’ambiente che quel componente legge. Quel rifiuto è un’asserzione propria di ciascuna Recipe, e viene eseguito prima che questo provider esegua il rendering di qualsiasi cosa. Questo provider rifiuta anche sul nodo stesso, qualunque sia il catalogo da cui proviene la Recipe: un’associazione su un nodo reference il cui materiale è dichiarato sensibile — la sua Feature dichiara un campo sensitive: true, oppure lo fa lo slot che riempie — arresta la build con TRANSLATION_ERROR (E0288), nominando il nodo e ogni associazione di questo tipo, che uno slot dichiari o meno il nome sotto cui è associata. Un’associazione che non porta nulla di dichiarato sensibile non viene rifiutata qui. Quei Components dichiarano facoltativi i propri slot di credenziali, quindi su compose uno slot lasciato vuoto non arresta nulla. Dove la realizzazione Kubernetes ha bisogno della credenziale — le Recipes helm di twilio, vonage, telnyx, bland, letta, retell e vapi — quella Recipe richiede invece lo slot, e arresta la build nominandolo quando è vuoto.
Esposizione dei servizi
Il campo type di una voce services del Workload decide se compose pubblica le porte, e su quale indirizzo dell’host:
| Tipo di servizio del Workload | Comportamento di Compose |
|---|---|
ClusterIP | Nessuna pubblicazione ports: — il servizio è raggiungibile solo sulla rete di compose |
NodePort | Pubblicazione ports: [<host>:<container>], su ogni interfaccia dell’host |
LoadBalancer | Pubblicazione ports: [<host>:<container>], su ogni interfaccia dell’host (compose non ha un equivalente del load balancer gestito; la pubblicazione su una porta dell’host è l’analogo più vicino) |
Loopback | Pubblicazione ports: [127.0.0.1:<host>:<container>] — raggiungibile dall’host stesso e da nessun altro luogo |
Headless | Nessuna pubblicazione ports: |
Quale numero va su quale lato. Una voce di servizio nomina una porta del container e le assegna un numero, come un Service Kubernetes mappa la propria port su una targetPort. Il numero della voce è il lato <host> della coppia pubblicata, e il numero della porta del container a cui il nome si risolve è il lato <container>. Così un container che dichiara http: 8080 e una voce NodePort che scrive http: 8081 pubblicano 8081:8080: la porta 8081 dell’host raggiunge la porta su cui il container serve. Una voce che porta il numero proprio della porta del container pubblica quel numero su entrambi i lati, 8080:8080. Un peer sulla rete di compose raggiunge il servizio tramite il suo nome di servizio sulla porta del container, mai su quella pubblicata — la porta pubblicata appartiene all’host — quindi una Recipe che pubblica una porta di sua scelta consegna comunque ai propri consumatori la porta del container.
Una voce Loopback si associa solo all’indirizzo di loopback IPv4. L’indirizzo di loopback IPv6 ::1 non viene associato: la sintassi delle porte di compose porta un solo indirizzo dell’host per voce, e un host la cui interfaccia di loopback non ha un indirizzo IPv6 non potrebbe associarlo, quindi lì il servizio non si avvierebbe. I client sull’host raggiungono la porta su 127.0.0.1.
Quando più servizi su un singolo Workload pubblicano la stessa porta del container con lo stesso numero, viene pubblicata una sola volta, e prevale la portata più ampia: qualsiasi riferimento NodePort o LoadBalancer la pubblica su ogni interfaccia dell’host, anche dove la nomina anche una voce Loopback e qualunque voce sia dichiarata per prima; una porta che solo voci Loopback nominano viene pubblicata su 127.0.0.1. Una porta del container pubblicata con due numeri viene pubblicata due volte, una con ciascuno. Le porte pubblicate sono elencate in ordine di porta del container, e per porta pubblicata all’interno di una stessa porta del container.
Trasporto delle porte. Una voce pubblicata porta il trasporto dichiarato sulla porta del container che nomina, come suffisso /protocol di compose: 53:53/udp, oppure 127.0.0.1:53:53/udp per una voce Loopback. Una porta che non dichiara alcun trasporto viene pubblicata come <host>:<container> senza suffisso, lasciando in vigore il default di compose. Compose scrive il trasporto di una porta pubblicata come tcp o udp; una porta che dichiara SCTP non ha una grafia compose, quindi arresta la build con un errore TRANSLATION_ERROR anziché pubblicare una porta che porterebbe un trasporto diverso. Una porta del container che nessun servizio pubblica non raggiunge alcuna parte del file compose, quindi un trasporto dichiarato su una tale porta non ha nulla su cui essere scritto e non causa alcun arresto.
Workloads multi-container
Un Workload con più container diventa un servizio principale più un servizio sidecar per ogni container non principale. Il container principale è quello chiamato main (se presente) oppure il primo container nell’ordine di dichiarazione. I sidecar condividono il namespace di rete del servizio principale tramite network_mode: "service:<main>" — la primitiva compose più vicina al modello di rete condivisa di un pod Kubernetes.
Come viene chiamato un servizio sidecar o init
Il servizio principale porta il nome <component> così com’è. Ogni altro servizio prodotto dal Workload — uno per ogni sidecar e uno per ogni init container — prende il nome da due identità insieme: il <component> e il nome del container, che per un sidecar è la sua chiave sotto containers: e per un init container è il suo name, oppure il nome posizionale init-<index> che assume una voce init senza nome. Il blocco services: assemblato contiene un servizio per nome, quindi il nome è costruito in modo che due container che differiscono in una qualsiasi delle due identità arrivino sempre a due nomi diversi.
Ogni identità viene scritta esattamente come le due parti di un nome di volume — una lettera, una cifra, un punto e un underscore così come sono scritti, un trattino mantenuto dove le regole di quella sezione lo mantengono, e ogni altro carattere codificato — e le due vengono unite da --, che nessuna identità codificata contiene. Così il componente api con un sidecar logger lo esegue come api--logger, l’init container import-seed di platform viene eseguito come platform--import-seed, e una prima voce init senza nome di api viene eseguita come api--init-0. Un nome di container che contiene un carattere non ammesso in un nome di servizio viene codificato invece di essere emesso così com’è scritto: un init container chiamato warm cache/x di api viene eseguito come api--warm-zx000020cache-zsx.
La doppia giunzione tiene separati i container di due componenti. api con un container warm-cache e api-warm con un container cache vengono eseguiti come api--warm-cache e api-warm--cache, due servizi, mentre una giunzione con un solo trattino li scriverebbe entrambi api-warm-cache.
Sidecar e init container condividono questa unica denominazione, quindi una voce containers e una voce initContainers con lo stesso nome arrivano allo stesso nome di servizio, e la compilazione si arresta sulla coppia invece di eseguire un container al posto dell’altro (vedi Init container).
Il servizio proprio di un componente non assume uno di questi nomi. Il servizio principale prende il nome dal componente, e un doppio trattino scritto nel nome di un componente viene a sua volta codificato lì — un componente chiamato api--prep viene eseguito come api-zh-prep — quindi non contiene mai la giunzione --. Dove servizi di due componenti diversi coincidono comunque su un nome in un unico file compose — tramite un servizio che un artefatto nomina per sé, ad esempio — la compilazione si arresta indicandoli entrambi, come descrive Output per (path, provider).
Cambiare il nome del componente o il nome del container rinomina il servizio. Compose tratta un servizio con un nuovo nome come un nuovo servizio, quindi il suo container viene creato da zero con il nuovo nome.
Campi a livello di pod
I campi del Workload a livello di pod si applicano solo al servizio principale — i sidecar condividono il namespace di rete del servizio principale — e un servizio di init segue la stessa regola. L’unica eccezione è l’utente del pod: un pod esegue ognuno dei suoi container come podSecurityContext.runAsUser e runAsGroup, quindi questi raggiungono ogni servizio che il Workload produce, servizi sidecar e di init compresi.
Diversi corrispondono a un campo di servizio compose:
| Campo del Workload | Campo di Compose |
|---|---|
podSecurityContext.runAsUser / runAsGroup | user ("1000", oppure 1000:3000 con un gruppo) su ogni servizio del Workload. Un container che imposta il proprio securityContext.runAsUser viene invece eseguito con quell’utente sul proprio servizio, con il proprio runAsGroup dove ne imposta uno |
terminationGracePeriodSeconds | stop_grace_period: <n>s |
dnsConfig.nameservers / dnsConfig.searches | dns / dns_search |
hostAliases | una voce extra_hosts per ogni hostname, nell’ordine dell’autore |
hostNetwork: true | network_mode: host |
Esecuzione sulla rete del nodo. Un carico di lavoro che dichiara hostNetwork: true riceve network_mode: host sul proprio servizio, e quel servizio viene quindi lasciato fuori dalla rete del confine anziché esservi collegato: compose rifiuta un servizio che dichiara sia networks: sia network_mode:, quindi i due sono alternativi e non cumulabili. La conseguenza pratica è quella che il networking dell’host comporta sempre — i peer non raggiungono più il servizio tramite il suo nome di servizio compose su quella rete, perché non vi si trova più; lo raggiungono sugli indirizzi propri dell’host, che è ciò che la dichiarazione ha chiesto. Nessun altro servizio del confine ne è influenzato.
Due forme si combinano con essa. Un sidecar continua a nominare il servizio principale (network_mode: "service:<main>"), quindi segue il servizio principale sulla rete dell’host senza dichiarare nulla esso stesso — allo stesso modo in cui i container di un pod Kubernetes condividono un unico namespace. Un servizio di init no: si unisce alla rete del confine di per sé, perché condividere il namespace del servizio principale renderebbe circolare l’attesa del servizio principale su di esso. Così un carico di lavoro con sia hostNetwork sia initContainers esegue il proprio servizio sulla rete dell’host mentre i suoi servizi di init restano sulla rete del confine, il che è più ristretto della forma di pod che modella; un avviso unsupported-field nomina quella differenza anziché lasciare che la si scopra a runtime.
Gli altri non hanno un equivalente su un singolo host. Nessuno viene scartato in silenzio: ciascuno scritto dall’autore genera un avviso unsupported-field che nomina il campo, così un autore scopre quale impostazione la destinazione non ha potuto rispettare anziché scoprirlo dallo stack in esecuzione.
| Campo del Workload | Perché compose non può rispettarlo |
|---|---|
scheduling | La collocazione — nodeSelector, affinity, tolerations, topologySpreadConstraints — presuppone uno scheduler che sceglie tra i nodi. Compose viene eseguito su un solo host |
replicas | Il numero di repliche proprio di compose si trova sotto deploy: ed è una funzionalità della modalità swarm |
runtimeClassName | La selezione di un runtime di container alternativo — uno abilitato per GPU, per esempio — non ha un’espressione compose |
priorityClassName | L’ordinamento della preemption presuppone uno scheduler |
serviceAccount | L’identità del Workload è un concetto di cluster |
imagePullSecrets | Le credenziali del registry su un host compose sono lo stato di login proprio dell’host, non un campo del file |
dnsPolicy, dnsConfig.options | Compose espone dns e dns_search e nulla di più fine |
podSecurityContext.fsGroup, podSecurityContext.supplementalGroups | user porta un utente e un gruppo; il gruppo a cui appartengono i volumi di un pod, e gli ulteriori gruppi per i suoi processi, non vengono tradotti |
podSecurityContext.runAsGroup, dove il pod non imposta alcun runAsUser, oppure dove un container — principale, sidecar o di init — imposta il proprio runAsUser e nessun runAsGroup | user nomina un gruppo solo accanto a un utente, e l’utente proprio di un container prende il posto di quello del pod, quindi il gruppo del pod non raggiunge alcun servizio scritto in quel modo |
Il securityContext a livello di container si traduce parzialmente: readOnlyRootFilesystem → read_only, capabilities.add / drop → cap_add / cap_drop, runAsUser / runAsGroup → user. runAsNonRoot e allowPrivilegeEscalation non hanno un’espressione compose e generano lo stesso avviso unsupported-field, e così fa un runAsGroup di un container scritto senza un runAsUser accanto: il servizio viene allora eseguito con l’utente del pod dove il pod ne imposta uno, senza quel gruppo.
Ogni avviso in questa sezione è consultivo e fuori banda: la build riesce, e il file emesso è byte per byte ciò che sarebbe senza di esso. --no-unsupported-field-warnings silenzia la classe.
Init container
Le voci initContainers di un Workload diventano servizi a sé stanti, usando l’idioma di esecuzione fino al completamento di compose. Ogni voce aggiunge un servizio, il cui nome è formato da <component> e dal name della voce secondo la stessa denominazione usata dai sidecar — <component>--<container-name> per un nome ordinario; una voce che omette name prende il nome posizionale init-<index> documentato dal riferimento del Workload, e il suo nome è formato da quello.
L’ordinamento promesso dal contratto di authoring — gli init container vengono eseguiti fino al completamento nell’ordine in cui sono scritti, e ogni altro container si avvia solo dopo che tutti hanno terminato — è espresso con la forma lunga di depends_on:
- Ogni servizio di init dopo il primo attende il proprio predecessore con
condition: service_completed_successfully. - Il servizio principale, e ogni servizio sidecar, attende l’ultimo servizio di init con la stessa condizione. Attendere l’ultimo è sufficiente perché i servizi di init formano una catena.
- Ogni servizio di init porta
restart: "no". Un servizio di init viene eseguito una volta; un servizio che tornasse attivo non raggiungerebbe mai lo stato di completamento che i suoi dipendenti attendono, quindi unarestartPolicyscritta su un init container non cambia questo comportamento.
services: platform: image: platform:1.0 depends_on: platform--verify-seed: condition: service_completed_successfully platform--import-seed: image: platform:1.0 restart: "no" platform--verify-seed: image: platform:1.0 depends_on: platform--import-seed: condition: service_completed_successfully restart: "no"Un init container viene tradotto esattamente come qualsiasi altro container: il suo image (compresa la riscrittura del registry applicata da un’annotazione aggrega.ai/image-registry), command, args, variables, attachments, volumeMounts e securityContext raggiungono tutti il servizio di init. È questo che fa sì che la configurazione portata da un init container — molto spesso un file che monta e scrive in un volume montato anche dal container principale — sopravviva sulla destinazione compose anziché andare persa con il container. Una forma che compose non può esprimere fallisce allo stesso modo per un init container come per uno ordinario: un lifecycle o un envFrom dichiarato arresta la build con un errore TRANSLATION_ERROR che nomina l’init container da cui proviene.
Due differenze rispetto al servizio principale derivano dal fatto che un servizio di init è un servizio non principale:
- I campi del Workload a livello di pod non vengono applicati, la stessa regola seguita dai sidecar — eccetto l’utente del pod, che raggiunge ogni servizio come descrive Campi a livello di pod.
- Un servizio di init si unisce direttamente alla rete del proprio confine anziché condividere il namespace di rete del servizio principale come fa un sidecar. Deve farlo: il servizio principale attende il servizio di init, e condividere un namespace è di per sé una dipendenza dal servizio principale, che chiuderebbe l’attesa in un ciclo che compose rifiuta di avviare. Un init container raggiunge quindi gli altri servizi sulla rete del confine tramite il nome di servizio, ma non condivide il
localhostdel servizio principale.
I servizi di init e i servizi sidecar condividono un unico spazio dei nomi, perché un’unica denominazione dà il nome a entrambi, quindi una voce initContainers e una voce containers non possono portare lo stesso nome. Quando lo fanno, il compilatore si arresta con un TRANSLATION_ERROR che nomina il nodo, il nome del container e il nome di servizio che entrambi volevano, anziché lasciare che un servizio sostituisca silenziosamente l’altro.
L’emissione della condizione di completamento non alza alcuna versione minima di Compose. condition e i suoi valori appartengono alla Compose Specification di base — a differenza dei campi restart e required accanto a essi nello stesso blocco in forma lunga, che la specifica lega a particolari versioni di Compose. Ogni versione minima richiesta dall’output del provider compose arriva con il costrutto che ne ha bisogno: ≥ 2.23.1 per configs.content inline, ≥ 2.26.0 per il subPath di un montaggio (vedi Volumi), e 2.38 per i modelli. La prima raggiunge qualsiasi output compose che porti una config con content: inline, che è il modo in cui arrivano sia il file dietro un volume configmap sia la config dietro un arco tra reti instradato tramite bridge — non un singolo percorso di authoring.
A quale rete si unisce un servizio
Ogni servizio si unisce a una rete Docker; i sidecar la ereditano tramite il loro riferimento network_mode al servizio principale. La rete su cui finisce un nodo viene letta dall’annotazione aggrega.ai/namespace su quel nodo, ripiegando sul percorso del file compose dove il nodo non porta tale annotazione — la directory in cui il file viene scritto sotto la directory di output della build, come bridge/compose per un confine il cui directory: è bridge. Così ogni nodo senza l’annotazione in un file compose si unisce a un’unica rete chiamata come il percorso del file, qualunque sia il confine in cui si trova: i confini senza annotazione che condividono un file compose condividono quella rete, ed è aggrega.ai/namespace a separarli. I nodi che portano annotazioni diverse finiscono su una rete per ogni annotazione distinta. Come viene derivato il nome di una rete è il nome che quell’identità produce.
Come viene derivato il nome di una rete
Una rete compose è connettività L3 condivisa, e il blocco networks: di primo livello unisce le proprie voci per nome — quindi due identità che arrivano a uno stesso nome diventano una sola rete su cui si trovano entrambi gli insiemi di servizi, che si raggiungono a vicenda tramite il nome di servizio, senza nulla nel file emesso che mostri che erano previste due reti. Il nome è quindi costruito a partire dall’identità che dice di quale rete si tratta: l’annotazione aggrega.ai/namespace del nodo, oppure il percorso del file compose dove il nodo non ne porta alcuna.
Il nome di una rete compose accetta un insieme di caratteri più ristretto di quello che ciascuna identità può contenere: lettere, cifre, punti, underscore e trattini. Anziché sostituire un carattere che compose non accetta, la derivazione lo scrive per esteso, così due identità che differiscono in qualsiasi modo arrivano a due reti — e un nome può essere ricondotto all’identità da cui è stato costruito.
- Una lettera, una cifra, un punto e un underscore vengono riportati esattamente come scritti dall’autore, con le maiuscole e le minuscole con cui sono stati scritti. Così
prodeProdsono due reti, non una. - Un trattino viene mantenuto come scritto dall’autore ovunque il carattere che lo segue sia riportato direttamente e non sia una
zminuscola. Un trattino seguito da unazminuscola apre una sequenza di escape, quindi uno scritto dall’autore in quella posizione viene a sua volta scritto per esteso —api-zonediventaapi-zhzone, ed è questo che permette di ricondurre qualsiasi nome senza dover indovinare. Un trattino senza nulla dopo di sé viene scritto per esteso per lo stesso motivo, quindidb-dàdb-zh. - Ogni altro carattere viene scritto come
-zseguito da una lettera che lo identifica:sper un separatore di percorso,hper un trattino che la regola precedente non mantiene. Qualsiasi altra cosa — compresi uno spazio e una lettera non ASCII — viene scritta comexseguito dal punto di codice esadecimale a sei cifre del carattere, e un byte che non inizia alcun carattere comebseguito dal proprio valore a due cifre, così un’identità che non è testo valido viene comunque scritta per esteso in modo distinto anziché essere fusa con un’altra. - Un’identità del tutto assente — un nodo senza annotazione
aggrega.ai/namespacein un file compose senza percorso — viene scritta-ze, che nessuna identità scritta da un autore può produrre. Una rete senza identità non condivide quindi mai la connettività con una che ha un’identità scritta in un qualche modo particolare.
Così un namespace prod dà la rete prod, core-net dà core-net, e un file compose in dist/app/compose dà dist-zsapp-zscompose. Un input identico produce sempre il nome identico.
Un namespace e il percorso di un file compose vengono scritti nello stesso spazio. Sono due modi di nominare la stessa cosa — su quale rete si trova un nodo — quindi un nodo il cui namespace è app/compose e un nodo senza namespace nel file compose in app/compose finiscono deliberatamente su un’unica rete, esattamente come fanno due confini che portano la stessa annotazione aggrega.ai/namespace. Dove vuoi tenere separati due nodi, assegna loro identità che differiscono.
Cambiare l’identità di un nodo rinomina la rete compose, e compose non rinomina una rete sul posto. La rete viene creata da zero con il nuovo nome e ogni servizio su di essa viene ricreato per collegarvisi, mentre la vecchia rete resta indietro finché qualcosa non la rimuove. Una rete non contiene dati, quindi nulla va perso — ma i container su di essa si riavviano, e qualunque cosa mantenga una connessione attraverso la modifica la vede cadere. Cambia un’annotazione namespace, o la directory in cui viene scritto un file compose, come una nuova distribuzione da pianificare anziché come un valore da regolare sul posto.
Quando due confini confluiscono in un unico percorso di assemblaggio (directory: condivisa), i loro nodi senza un’annotazione aggrega.ai/namespace condividono l’unica rete del file; assegna a ciascun confine la propria annotazione aggrega.ai/namespace e il docker-compose.yaml unito dichiara una voce networks: di primo livello per ogni annotazione. I servizi di confini diversi all’interno dello stesso file compose possono comunicare tramite i loro nomi di servizio nell’ambito della risoluzione DNS predefinita di compose, nel rispetto delle regole di raggiungibilità tra reti proprie di compose. Il routing L4 tra reti all’interno di un unico file compose è ciò che abilita la Feature compose-bridge della libreria standard, come contenuto di catalogo di cui questo provider non contiene alcuna logica: associata al confine antenato comune, la sua FeatureRecipe deriva un gateway dagli archi uses del confine le cui due estremità sono assemblate nel suo stesso file compose e si trovano su reti diverse di esso — un servizio aggrega-gw la cui config nginx stream fa da proxy per ogni arco collegato tramite bridge (un blocco server per arco, sulla porta della destinazione con un fallback portBase in caso di collisione) — e il suo injectMapping riscrive la variabile d’ambiente dell’host di ciascun consumatore in aggrega-gw:<port>, oppure in aggrega-gw con la variabile della porta riscritta nella porta di ascolto dove la stessa connessione fornisce entrambe. Quella riscrittura sostituisce il valore fornito dalla connessione propria del consumatore; se un’altra Feature associata al consumatore ha fornito la stessa variabile, la build si arresta nominandole entrambe anziché sostituirlo. Il valuesMapping della FeatureRecipe scrive quella config come config compose montata — una voce configs: di primo livello con content: inline, referenziata dal gateway e montata in /etc/nginx/nginx.conf; non è un montaggio a carico dell’operatore — e nomina ogni endpoint collegato tramite bridge sotto l’x-aggrega-networks-of del gateway, che questo provider risolve nelle reti su cui quegli endpoint sono collocati (sotto). Un arco le cui due estremità sono assemblate in due file compose non viene collegato tramite bridge e mantiene il nome proprio della destinazione; un confine senza nulla da collegare porta comunque il gateway inattivo, senza config e senza reti oltre la propria; e un bridge associato a un confine il cui file compose non contiene alcun componente arresta la build anziché scrivere il gateway nel vuoto. La config stream porta una direttiva resolver e fa da proxy tramite una variabile per arco (set $uN <host>; proxy_pass $uN), così ogni upstream viene risolto al momento della connessione anziché una sola volta all’avvio — altrimenti un proxy_pass diretto verso una destinazione non ancora in esecuzione farebbe fallire il gateway all’avvio. (Il $ in quelle variabili viene sottoposto a escape come $$ all’interno di configs.content, così l’interpolazione $ propria di Docker Compose lascia un $ letterale per nginx.) configs.content inline richiede Docker Compose ≥ 2.23.1. Vedi il pattern compose-bridge.
Unirsi alle reti di altri componenti — x-aggrega-networks-of
Un servizio scritto da un frammento — un file compose da sorgente una volta unito il suo overlay, oppure un corpo artifacts: — può unirsi alle reti di altri componenti assemblati nello stesso file compose nominandoli sotto la chiave di estensione x-aggrega-networks-of: una lista di ID di componenti, gli ID che l’Aggregate assegna ai propri componenti, che una FeatureRecipe con ambito di confine legge come chiavi di .boundary.components e come source e target delle proprie liste di archi .boundary. Il provider risolve ciascun ID nella rete su cui quel componente è collocato in questo file, con la stessa collocazione che riceve ogni nodo, e aggiunge quelle reti al servizio, ciascuna una sola volta e in ordine di nome, prima della rete propria del servizio, a cui continua a unirsi. La chiave stessa viene omessa dal file assemblato. Il provider legge gli ID come riferimenti da risolvere e nulla su ciò che il servizio fa, quindi qualsiasi Recipe o FeatureRecipe può usare la chiave; il gateway del bridge compose si unisce in questo modo alle reti degli endpoint tra cui fa da relay.
# 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-zscomposeTre cose arrestano la build con TRANSLATION_ERROR quando il file viene assemblato, ciascuna nominando il servizio:
- Un ID che nessun componente assemblato in questo file porta — uno assemblato in un altro file compose, per esempio. Una rete appartiene a un solo file, quindi il messaggio nomina l’ID e il file in cui si trova il servizio. Nomina solo componenti assemblati nello stesso file, oppure rimuovi l’ID.
- Un valore che non è una lista di stringhe. La chiave accetta una lista di ID di componenti, anche per un solo ID.
- La chiave su un servizio che scrive
network_mode. Compose non consente a un servizio con unnetwork_modedi unirsi a reti; rimuovi uno dei due.
Inferenza di depends_on
Il provider compose deriva automaticamente depends_on dagli archi uses dell’IR. Per ogni arco la cui sorgente e la cui destinazione contribuiscono entrambe con servizi al file compose unito, il provider aggiunge depends_on: [<target>] al servizio sorgente.
La dipendenza ricade sul servizio proprio del componente sorgente, e su nessun altro servizio con cui quel componente contribuisce. Un componente che dichiara anche degli init container contribuisce con un servizio eseguito fino al completamento per ogni voce, e nessuno di questi riceve la dipendenza derivata dall’arco — un arco nomina il componente, e un servizio di init porta un nome proprio. Così un init container che deve raggiungere la destinazione dell’arco, come una migrazione dello schema verso un database a cui il componente punta con uses, non porta alcun ordinamento rispetto a quella destinazione e può essere eseguito prima che sia raggiungibile, mentre il servizio proprio del componente attende sia che la catena di init sia completata sia che la destinazione sia stata avviata.
Le voci derivate dagli archi vengono emesse senza vincolo: hanno la semantica service_started indipendentemente dal fatto che la destinazione dichiari un healthcheck. Vincolarle alla salute della destinazione — il che permetterebbe al runtime di compose di bloccare l’avvio finché l’healthcheck della destinazione non segnala di essere integro — è esprimibile, e un arco uses non lo chiede. Un’ondata che nomina la stessa coppia è l’unica cosa che cambia la condizione su una voce derivata da un arco, e lo fa perché è l’ondata a chiederlo, non l’arco.
Le voci derivate dagli archi vengono emesse in ordine alfabetico di destinazione per la stabilità dell’output. Gli archi la cui sorgente o destinazione è servita da un provider diverso (helm o helm-chart) vengono ignorati — depends_on si applica solo all’interno del sottoinsieme della Release servito da compose.
Il depends_on di un servizio viene emesso in una delle due forme di compose, mai in una combinazione delle due, perché compose richiede una condizione su ogni voce della forma lunga:
- Lista in forma breve (
depends_on: [<service-name>]) quando nessuna voce di quel servizio porta una condizione. È il caso di ogni servizio le cui uniche dipendenze provengono da archiuses. - Mappa in forma lunga quando una qualsiasi voce ne porta una — il che accade quando il servizio attende anche un init container, o quando un’ondata di distribuzione lo ordina. Lì le voci derivate dagli archi emettono l’esplicita
condition: service_started, che la Compose Specification definisce come l’equivalente della forma breve, quindi il loro significato resta invariato.
All’interno di un servizio le sorgenti mantengono il proprio ordine e non si intercalano: l’attesa della catena di init, il cui ordine è quello in cui l’autore ha scritto la lista, viene emessa per prima, poi le voci derivate dagli archi in ordine alfabetico, poi quelle derivate dalle ondate in ordine alfabetico.
Ordine per ondate di distribuzione
Il valore syncWave: del confine di una Release ordina i servizi del file compose in cui quel confine esegue il rendering. Ogni componente del confine eredita l’ondata del confine, e dove più confini condividono una stessa directory: — così che i loro contributi confluiscono in un unico docker-compose.yaml — il file unito contiene più di un’ondata e il provider esprime l’ordinamento tra di esse come depends_on.
Ogni servizio attende ogni servizio dell’ondata immediatamente precedente che abbia dei servizi, e nessuna ondata anteriore a quella. Compose risolve il resto in modo transitivo: un servizio nell’ondata 2 attende l’ondata 1, che attende l’ondata 0, così l’intera sequenza è ordinata mentre la lista propria di ciascun servizio resta della dimensione di una sola ondata anziché dell’intero file. Le ondate non devono essere contigue, e i valori negativi sono normali — -1 è una scelta comune per una migrazione eseguita prima di tutto il resto.
La condizione dipende da ciò che la destinazione può soddisfare. Un’ondata significa che il gruppo precedente è attivo prima che quello successivo si avvii, il che è prontezza anziché avvio del processo, quindi:
- dove il servizio di destinazione dichiara un
healthcheck, l’attesa ècondition: service_healthy; - dove non lo fa, l’attesa è
condition: service_started, perché un servizio senza healthcheck non può mai segnalare di essere integro e un’attesa vincolata alla sua salute non sarebbe mai soddisfatta — il file non si avvierebbe mai.
La condizione più debole è visibile nel file emesso accanto a quella più forte, e la build nomina inoltre ciascuno di questi servizi in un avviso, così un autore che si aspettava un ordinamento per prontezza scopre quale parte dell’ondata che ha dichiarato arriva solo come ordinamento di avvio. L’avviso è consultivo: la build riesce e i byte renderizzati sono esattamente ciò che sarebbero senza di esso. Aggiungere un blocco health: a quel container è ciò che rafforza l’attesa. --no-unsupported-field-warnings silenzia la classe.
L’ondata resta comunque registrata come etichetta. L’ordinamento viene aggiunto accanto all’etichetta aggrega.ai/sync-wave, non al suo posto: l’etichetta è il punto in cui chi ispeziona il file emesso vede da quale ondata proviene un servizio, cosa che le voci depends_on non dicono.
Dove un’ondata e un arco uses nominano la stessa coppia, una sola voce porta entrambi. Compose accetta una voce per dipendenza, quindi un servizio che punta a una destinazione con uses e si trova anche un’ondata dopo di essa emette una singola voce vincolata alla condizione dell’ondata — il requisito dell’ondata è il più forte dei due ed è quello che viene espresso.
Un confine i cui componenti si trovano tutti in un’unica ondata non emette nulla per questo. Lo stesso vale per una Release che non dichiara affatto syncWave: ogni contributore porta il valore predefinito del campo, 0, il file unito contiene una sola ondata, e l’output è esattamente quello che sarebbe se il provider non esprimesse alcun ordinamento per ondate.
L’ordinamento tra due file compose non è esprimibile, e non viene approssimato. depends_on nomina un servizio all’interno dello stesso file, e i confini che si valutano in percorsi di assemblaggio distinti producono file docker-compose.yaml distinti che il runtime di compose tratta come progetti indipendenti. Quindi un’ondata ordina ogni servizio del file in cui esegue il rendering e nulla al di fuori di esso. Mettere in sequenza due progetti compose è compito dell’operatore, nello stesso modo dell’instradamento tra file; dichiarare una directory: condivisa è ciò che porta due confini in un unico file, ed è una decisione sulla forma dell’output da prendere per ragioni proprie anziché per ottenere un ordinamento.
Un arco uses che punta a un’ondata successiva viene emesso come scritto, e segnalato. Il depends_on emesso riflette ciò che è stato dichiarato — sia gli archi uses sia le ondate. Un arco il cui consumatore si trova in un’ondata precedente rispetto alla destinazione che usa afferma il contrario di ciò che affermano le ondate: l’arco fa attendere al consumatore la destinazione, mentre le ondate fanno attendere alla destinazione, attraverso ogni ondata tra i due, il consumatore. Il file unito esprime entrambi, il che costituisce un insieme di dipendenze circolari che Docker Compose rifiuta di avviare. La build nomina ciascuno di questi archi in un avviso che indica entrambi i servizi ed entrambe le ondate, così il ciclo emerge quando esegui la build anziché a docker compose up. L’avviso è consultivo — la build riesce e i byte renderizzati sono esattamente ciò che sarebbero senza di esso — e --no-unsupported-field-warnings non lo silenzia, perché nulla è stato scartato: le due dichiarazioni sono espresse ciascuna, e insieme non possono avviarsi. Copre solo la coppia diretta: nomina i due servizi che un arco collega anziché tracciare l’intero ciclo. Ogni ciclo costruito da archi uses e ondate insieme passa per almeno uno di questi archi, quindi viene sempre segnalato; un ciclo formato solo da archi uses, senza alcuna ondata coinvolta, e uno chiuso da una voce depends_on scritta in un file compose fornito dalla Recipe vengono emessi come scritti e non segnalati. Mantieni coerenti la direzione degli archi e l’ordine delle ondate: colloca il consumatore nell’ondata della destinazione o in una successiva, oppure la destinazione nell’ondata del consumatore o in una precedente.
# release.yaml fragment — three boundaries collapsing onto one compose fileboundaries: data: directory: ./dist/cluster syncWave: -1 components: migrator: {} # no health: block core: directory: ./dist/cluster syncWave: 0 components: store: {} # declares health: edge: directory: ./dist/cluster syncWave: 1 components: frontend: {} # uses: store# dist/cluster/compose/docker-compose.yaml (abridged)services: frontend: labels: aggrega.ai/sync-wave: "1" depends_on: store: condition: service_healthy # store declares a healthcheck migrator: labels: aggrega.ai/sync-wave: "-1" # lowest wave: waits on nothing store: depends_on: migrator: condition: service_started # migrator declares no healthcheck healthcheck: test: [CMD-SHELL, "nc -z localhost 5432"]frontend non nomina migrator: l’ordinamento raggiunge l’ondata immediatamente precedente e compose concatena il resto attraverso store.
Modalità con sorgente
Il source: del provider compose nomina un file YAML di docker-compose che il provider può leggere e analizzare, e accetta entrambe le forme che il campo source: assume: una semplice stringa con un percorso del filesystem, e un oggetto strutturato il cui url: porta la posizione. Ovunque quella posizione sia un percorso del filesystem, è ancorata alla directory che contiene il recipe.yaml che la dichiara, non alla directory da cui viene invocata la build, e deve restare all’interno di quella directory: un percorso che ne esce, o uno assoluto, viene rifiutato, perché ogni file che una pubblicazione della Recipe porta con sé è preso dalla sua directory — vedi entities/recipe.md «Content paths stay inside the Recipe’s own directory (I percorsi dei contenuti restano nella directory della Recipe stessa)». Il file nominato in questo modo viene pubblicato con la Recipe, mentre un file accanto alla Recipe che nulla di ciò che essa dichiara nomina non lo è.
spec: capability: compose source: ./docker-compose.base.yaml # filesystem path to the base compose file valuesMapping: | services: api: image: "{{ .values.image }}"Nella forma strutturata, ciò che url: porta decide se qualcosa viene recuperato. Un frammento pubblicato su https:// viene recuperato e fissato con kind: compose-https-fragment; aggrega pull lo acquisisce e la build lo legge dalla cache. Un url: che nomina un percorso del filesystem non viene recuperato — viene letto dal disco, ancorato esattamente come la forma a stringa semplice qui sopra, e aggrega pin registra il digest del file che nomina nel file entity.lock accanto alla Recipe, che una build poi confronta prima che il frammento venga letto. Copiare in locale un frammento remoto (vendoring) e puntare source: alla copia locale è supportato come alternativa al recupero, e non è obbligatorio. Lo schema accetta un oggetto strutturato aperto.
Una Recipe con source: <path-to-compose-file> e valuesMapping: esegue la seguente pipeline:
- Il file compose di base in
<path>viene letto e analizzato come YAML. - Il template
valuesMappingviene valutato rispetto al contesto di template della Recipe. Il suo output viene trattato come un documento di overlay compose — un file compose parziale che integra o sovrascrive campi della base. - Base e overlay vengono uniti in profondità secondo la semantica di overlay nativa di docker-compose.
Le regole dell’unione in profondità:
- Scalari: vince l’overlay. Quando sia la base sia l’overlay impostano lo stesso campo scalare, il valore dell’overlay sostituisce il valore della base.
- Mappe: unione ricorsiva. Quando sia la base sia l’overlay impostano lo stesso campo mappa, l’unione procede ricorsivamente all’interno della mappa. Le chiavi presenti in entrambe seguono le stesse regole; le chiavi presenti in una sola vengono preservate così come sono.
- Liste: sostituzione. Quando sia la base sia l’overlay impostano lo stesso campo lista, la lista dell’overlay sostituisce interamente la lista della base (nessuna unione elemento per elemento né aggiunta in coda). Questo corrisponde al comportamento di
docker compose -f base.yaml -f overlay.yaml config. null: sostituisce, e resta. Una chiave che l’overlay imposta anullsu un servizio — una delle chiavi proprie del servizio, comeuser,commandohealthcheck, una voce dienvironment, un’etichetta, o una chiave direttamente sottohealthcheckodeploy— sostituisce il valore della base come qualsiasi scalare e viene scritta nel file compose comekey: null; non rimuove la chiave. Dove il provider scrive un valore proprio in quella chiave, il file porta invece il valore del provider:labels: nulllascia le etichette di provenienza che il provider appone, enetworks: nullla rete che collega. Unnullscritto in qualsiasi altro punto dell’overlay è al di fuori di questa regola. Ciò che unnullsignifica poi è la lettura che Compose dà di quell’attributo — una voce dienvironmentsenza valore, per esempio, prende il proprio valore dall’ambiente in cui viene eseguitodocker compose.
Ogni etichetta scritta dall’autore di un servizio resta. I labels: di un servizio nel file di base o nell’overlay possono essere scritti come mappa o come lista di voci key=value di Compose, e ogni etichetta raggiunge il file compose accanto alle etichette di provenienza che il provider appone. Una voce di lista viene letta come la legge Compose: il testo prima del suo primo = nomina l’etichetta e il testo dopo di esso è il valore, e una voce senza = è un’etichetta con valore vuoto. Un numero o un valore true/false viene scritto come il suo testo, così replicas-hint: 2 raggiunge il file come replicas-hint: "2", e un’etichetta scritta come null resta null. Dove un’etichetta scritta dall’autore e un’etichetta di provenienza condividono una chiave, il file porta il valore di provenienza. Un valore labels: che non è né una mappa né una lista, e una voce di lista che non è testo, arrestano la build, nominando il file sorgente e il servizio. Le etichette di servizio del corpo di un artifacts: assumono la forma a mappa: una lista lì arresta la build, nominando l’artefatto e il servizio.
Il documento unito confluisce poi nell’unione a livello di Release insieme a eventuali contributi in modalità sintetizzata, con la stessa rete per confine e la stessa inferenza di depends_on.
Lasciare fuori servizi, volumi e config. L’overlay non può rimuovere nulla dal file di base — un valore dell’overlay sostituisce, non elimina mai — quindi un file recuperato che include un servizio che la Release non deve eseguire è ciò a cui servono le voci omits: di una Recipe o di una FeatureRecipe. Questo provider le rispetta in questa modalità e in nessun’altra: un Workload sintetizzato e il corpo di un artifacts: vengono renderizzati senza di esse. Una voce nomina un’unità di primo livello del file tramite il suo kind — service, volume o config — e il suo name, la chiave dell’unità sotto services:, volumes: o configs:, confrontata esattamente. Un file compose non ha namespace, quindi una voce che porta un namespace, come una che nomina qualsiasi altro tipo, arresta la build quando il componente esegue il rendering, nominando la voce e i tipi che questo provider accetta; ogni voce viene controllata prima che qualcosa venga lasciato fuori. Le voci vengono confrontate con il file una volta che l’overlay di cui sopra vi è stato unito, così un’unità aggiunta dall’overlay viene lasciata fuori esattamente come una dichiarata dalla base, e prima che il provider aggiunga qualcosa di proprio, così una voce non nomina mai quello. Un’unità che una voce nomina viene rimossa, e una sezione di cui ogni unità viene lasciata fuori viene rimossa con esse; ogni altra unità viene scritta esattamente come lo sarebbe senza le voci. Le voci raggiungono il file della Recipe o della FeatureRecipe che le dichiara e nient’altro: ciò che un altro componente o una Feature associata contribuisce allo stesso docker-compose.yaml resta intatto, compresa un’unità con la stessa chiave. Il provider riporta quante unità ha lasciato fuori ciascuna voce, e una voce che non ne ha lasciata fuori alcuna arresta la build; vedi An omits entry left out nothing the source rendered (Una voce omits non ha lasciato fuori nulla di ciò che la sorgente ha renderizzato).
Un’unità lasciata fuori non deve restare nominata da ciò che rimane, perché compose rifiuta un file che nomina un servizio, un volume o una config che non dichiara. Una volta rimosse le unità, ogni riferimento che il file fa ancora a una di esse arresta la build, e il messaggio nomina ciascun servizio o job che fa riferimento, l’unità che nomina e il campo in cui si trova il riferimento. Un riferimento è ciò che la Compose Specification definisce come una voce di un file che ne nomina un’altra:
- un servizio, nominato da
depends_onin una delle due forme, dalinks(SERVICEoSERVICE:ALIAS), davolumes_from(SERVICEoSERVICE:MODE), danetwork_mode,ipc,pidoutsimpostato aservice:<name>, daextendsche nomina un servizio dello stesso file, o da un valoreservice:<name>dibuild.additional_contexts; - un volume, nominato come sorgente di una voce
volumes:— la forma breveSOURCE:TARGETin cui la sorgente è un nome anziché un percorso, e la forma lunga ditype: volume; - una config, nominata da una voce
configs:, in una delle due forme.
Vengono letti anche gli hook pre_start di un servizio e ogni voce jobs: di primo livello, per i riferimenti che la specifica consente a ciascuno di essi di portare. Alcuni valori sembrano soltanto riferimenti e non vengono letti come tali: una voce volumes_from o network_mode che inizia con container: nomina un container, external_links nomina un container che questo file non dichiara, un extends con un file: nomina un servizio di un altro file, e un credential_spec.config può nominare una config detenuta dalla piattaforma anziché dal file. Ogni valore viene confrontato così come è scritto, quindi un riferimento scritto tramite un ${VARIABLE} non è uno che questo controllo vede, e un riferimento a un’unità che il file non ha mai dichiarato viene lasciato com’è.
Il controllo legge solo il file proprio della Recipe o della FeatureRecipe che dichiara, quindi un riferimento a un servizio lasciato fuori arresta la build anche dove un altro contributore nello stesso percorso di assemblaggio dichiara un servizio con quel nome. Per mantenere il riferimento, mantieni l’unità. Per eliminarlo, modifica la voce che fa riferimento tramite valuesMapping: — una lista lì sostituisce la lista del file di base, quindi depends_on: [] ne svuota una — oppure lascia fuori anche il servizio che fa riferimento.
Output per (path, provider)
Ogni percorso di assemblaggio compose produce un docker-compose.yaml. I confini che si valutano in percorsi distinti producono file compose distinti; i confini che condividono un percorso valutato producono un unico file compose unito che contiene ogni contributore in quel percorso. Il percorso è la directory: del confine unita al subDirectory: per componente (il cui valore predefinito è {{ .capability }}, così i contributori compose finiscono per impostazione predefinita in una sottocartella compose/).
Le collisioni tra nomi di servizio all’interno di un singolo percorso di assemblaggio arrestano la build. Quando due nodi diversi contribuiscono con servizi con lo stesso ID di istanza nella stessa tupla (path, provider), il compilatore si arresta e la diagnostica nomina ogni tupla (boundary, node) contributrice in ordine alfabetico. L’autore risolve la collisione rinominando uno dei contributori (tipicamente modificando l’identificatore del nodo affinché il sintetizzatore produca un nome di servizio diverso), oppure instradando i contributori verso percorsi distinti tramite dichiarazioni directory: diverse.
I volumi di primo livello si uniscono all’interno di un percorso di assemblaggio, e due contributori possono dichiarare uno stesso nome purché concordino su di esso. Un contributore è un frammento, quindi due frammenti di uno stesso componente — il suo file compose proprio e una voce artifacts:, oppure due voci artifacts: — sono due contributori esattamente come lo sono due componenti. Un volume con nome è un solo volume fisico, quindi due dichiarazioni identiche descrivono entrambe esattamente la voce con cui il file assemblato finisce, e il file mantiene un’unica voce con quel nome. Un volume che il provider ha derivato non porta alcun corpo, quindi due di essi concordano banalmente, e in ogni caso non possono incontrarsi (vedi Come viene derivato il nome di un volume).
Una voce volumes: scritta dall’autore è quella a cui prestare attenzione, perché può portare un corpo proprio — un driver, driver_opts o labels. Dove due contributori dichiarano uno stesso nome con corpi diversi, la build si arresta con TRANSLATION_ERROR, nominando il volume e ogni tupla (boundary, node, fragment) contributrice. Quando due autori sono in disaccordo su un singolo volume, l’assemblatore non ha alcuna risposta tra cui scegliere: mantenere l’uno o l’altro corpo scarta ciò che l’altro autore ha scritto, da una build che altrimenti riuscirebbe. Risolvilo rendendo identiche le due dichiarazioni, dove entrambi gli autori intendevano lo stesso volume, oppure rinominandone una, dove ne intendevano due. Le reti di primo livello sono una per ogni annotazione aggrega.ai/namespace distinta, più una chiamata come il percorso del file compose per i nodi che non ne portano alcuna, nominate secondo Come viene derivato il nome di una rete; due confini contributori con la stessa annotazione aggrega.ai/namespace confluiscono in un’unica rete condivisa da entrambi, così come due confini senza annotazione che condividono il file.
Ogni chiave che un frammento scrive viene portata o rifiutata
Un frammento — un file compose da sorgente una volta unito il suo overlay, oppure un corpo artifacts: che si valuta in YAML compose — raggiunge il docker-compose.yaml assemblato solo attraverso le chiavi che il provider porta, e quell’insieme è fisso. Ogni chiave che un frammento scrive viene portata nel file assemblato così come è scritta oppure rifiutata per nome; nessuna viene lasciata fuori senza una parola. Un frammento è un solo file compose, quindi è un solo documento YAML.
- Portate. Al primo livello:
services,volumes,configsemodels. Su un servizio: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_hostseprofiles. All’interno dei blocchi che il provider descrive:deploy.resourcescon i suoilimits(cpus,memory) ereservations(cpus,memory,devices, e di ogni voce di dispositivodriver,count,device_ids,capabilitieseoptions);test,interval,timeout,retriesestart_perioddi unhealthcheck;type,source,target,read_onlyevolume.subpathdi una vocevolumes:in forma lunga;sourceetargetdi una voceconfigs:in forma lunga;conditiondi una vocedepends_on:in forma lunga;driver,driver_optselabelsdi un volume di primo livello;contentdi una config di primo livello. Il corpo di un modello e la vocemodels:in forma lunga di un servizio portano ogni membro, come descrive Modelli. Un membro di estensione — una chiave che inizia conx-— viene portato al primo livello e su un servizio, come descrive Membri di estensione. - Rifiutate. Qualsiasi altra chiave —
stdin_opensu un servizio, unsecrets:o unname:di primo livello,deploy.replicas, unrestart:o unrequired:all’interno di una vocedepends_on:in forma lunga, una chiavex-all’interno del corpo di un volume di primo livello o di unhealthcheck— arresta la build conTRANSLATION_ERROR, nominando ciascuna di tali chiavi, il suo percorso nel frammento (services.migrate.stdin_open), il frammento e il componente, e nomina i due punti da cui una tale chiave proviene. Uno è il frammento stesso, e la correzione consiste nel rimuovere la chiave da esso. L’altro è una Recipe da sorgente che non dichiara alcunvaluesMapping:: i valori del nodo vengono allora sovrapposti al file compose così come sono, quindi ogni chiave di valore arriva come chiave di primo livello del frammento, e la correzione consiste nel dichiarare unvaluesMapping:che collochi ciascun valore sotto una chiave che il provider porta. Una chiave che una chiave di merge YAML (<<: *anchor) introduce in un blocco viene giudicata dove arriva, come se fosse scritta lì. Un frammento renderizzato dalla sorgente si chiama<component>.compose-fragment.yaml; un frammentoartifacts:porta il nome che gli dà la sua Recipe. - Rifiutata per intero: una rete propria del frammento. Una voce sotto i
networks:di primo livello di un frammento arresta la build conTRANSLATION_ERRORqualunque cosa contenga il suo corpo — una voce vuota, undriver, qualsiasi altra cosa — nominando la voce (networks.back), il frammento e il componente, perché il file assemblato contiene solo le reti che il provider deriva (vedi A quale rete si unisce un servizio). Rimuovi la voce: un servizio si unisce alla rete del proprio componente senza dichiarare nulla, l’annotazioneaggrega.ai/namespacesceglie a quale rete si unisce un componente, un servizio nomina i componenti alle cui reti si unisce anche sottox-aggrega-networks-of, e la Featurecompose-bridgeinstrada tra servizi su reti diverse. Unnetworks: {}vuoto non dichiara nulla e non viene rifiutato, e la listanetworks:propria di un servizio viene portata come sopra. - Rifiutato per intero: un frammento di più di un documento. Un corpo
artifacts:che contiene due o più documenti YAML separati da---arresta la build conTRANSLATION_ERROR, nominando il frammento, il componente e quanti documenti contiene, perché l’unione legge un frammento come un solo file compose e ogni documento dopo il primo mancherebbe altrimenti dal file assemblato. Scrivi il frammento come un solo documento, oppure dai a ogni documento una voceartifacts:propria. Un documento che non contiene nulla — quello vuoto che apre un---finale — non viene contato. Un file compose da sorgente di più documenti non diventa mai un frammento di questo tipo: viene rifiutato quando il file viene letto.
Il provider non legge il significato di alcuna chiave: una chiave viene portata perché è nell’insieme sopra e rifiutata perché non lo è.
I membri di estensione vengono portati così come sono scritti
La Compose Specification riserva le chiavi che iniziano con x- alle estensioni: dati che uno strumento che legge il file può usare e che Compose stesso ignora. I membri di estensione di un frammento al primo livello e su un servizio raggiungono il file assemblato così come sono scritti, dopo ogni chiave che il provider modella a quel livello, nell’ordine in cui il frammento li contiene; il provider non legge nulla al loro interno, tranne l’x-aggrega-networks-of di un servizio, che risolve nelle reti a cui il servizio si unisce e lascia fuori dal file assemblato (vedi Unirsi alle reti di altri componenti). Un corpo artifacts: li contiene nell’ordine in cui li scrive. Le chiavi di un file compose da sorgente raggiungono il suo frammento in ordine di nome una volta unito il suo overlay, quindi i suoi membri di estensione vengono scritti in ordine di nome.
# an artifacts: bodyx-owner: team-bservices: migrate: image: example/migrate:1 x-schedule: manualUn membro raggiunto tramite un alias YAML viene scritto per intero, e nessuna ancora viene portata, così il file assemblato non contiene mai un alias di cui manca l’ancora; è questo che permette a un membro di primo livello di contenere un’ancora che la chiave di merge di un servizio (<<: *base) richiama. I membri di un servizio viaggiano con il loro servizio. I membri di primo livello si uniscono all’interno di un percorso di assemblaggio secondo la regola che seguono i volumi: due frammenti che scrivono uno stesso membro con lo stesso contenuto lasciano un’unica voce, che lo scrivano in stile a blocchi o di flusso, e due che lo scrivono con contenuto diverso arrestano la build con TRANSLATION_ERROR, nominando il membro e ogni tupla (boundary, node, fragment) contributrice — compresi due frammenti di uno stesso componente. Rendi identiche le due dichiarazioni, oppure dai a una di esse un nome diverso.
profiles vincola un servizio a un profilo di Compose. Un servizio che elenca profiles: è uno che docker compose up lascia stare a meno che uno dei suoi profili sia abilitato, e che docker compose run --rm <service> avvia su richiesta — la forma compose di un’attività eseguita su richiesta. La lista viene portata come il frammento la scrive, nel suo ordine:
# a sourced compose fileservices: migrate: image: example/migrate:1 profiles: [manual]Modelli
La sezione models: di primo livello di un file compose dichiara i modelli di IA che i servizi del file usano, e a un servizio viene concesso un modello tramite la propria voce models:. Il provider porta entrambi da un frammento nel docker-compose.yaml assemblato, nella grafia propria di Compose, che il frammento sia un file compose da sorgente o un corpo artifacts: che si valuta in YAML compose. Un Workload non dichiara alcun modello, quindi una Recipe in modalità Workload non ne contribuisce alcuno.
- Il corpo di un modello viene scritto come il frammento lo ha scritto.
model— l’identificatore dell’artefatto OCI per il modello —context_sizeeruntime_flagsmantengono i propri nomi, e ogni altro membro, tra cui un’estensionex-, viene portato accanto a essi. All’interno di un modello i tre membri nominati vengono per primi e il resto segue in ordine di chiave, e i modelli vengono scritti in ordine di nome, così un input identico produce un file identico byte per byte. Il provider non legge nulla nel corpo: non controlla l’identificatore, e non sa nulla di ciò che servirà il modello. - Il riferimento di un servizio mantiene la propria forma. La forma breve elenca i nomi dei modelli (
models: [llm]); la forma lunga mappa ciascun modello suendpoint_varemodel_var, i nomi delle variabili che ricevono l’indirizzo del model runner e l’identificatore del modello. L’una e l’altra vengono scritte nella forma e nell’ordine usati dal frammento, e viaggiano con il loro servizio. Dove la forma lunga lascia una variabile senza nome, Compose la nomina quando esegue il file. - I modelli si uniscono all’interno di un percorso di assemblaggio, secondo la regola che seguono i volumi. Due contributori che dichiarano uno stesso nome di modello con corpi che vengono emessi in modo identico lasciano un’unica voce con quel nome; due che lo dichiarano con corpi diversi arrestano la build con
TRANSLATION_ERROR, nominando il modello e ogni tupla(boundary, node, fragment)contributrice. Anche qui due frammenti di uno stesso componente sono due contributori. Rendi identiche le dichiarazioni dove entrambi i contributori intendono un solo modello, oppure dai a una di esse un nome diverso. - Ogni riferimento nomina un modello dichiarato. Una volta uniti i frammenti del percorso di assemblaggio, un servizio a cui è concesso un modello che nessun contributore in quel percorso dichiara arresta la build con
TRANSLATION_ERROR, nominando il servizio e il modello. Il controllo viene eseguito sull’unione completa, così un componente può concedere al proprio servizio un modello che un altro componente nello stesso percorso di assemblaggio dichiara. - Una voce
omits:non può lasciare fuori un modello.service,volumeeconfigsono i tipi che questo provider accetta, e una voce che nomina un modello arresta la build come una che nomina qualsiasi altro tipo.
I modelli vengono serviti quando il file viene eseguito, non durante la build. Docker Compose 2.38 o successivo, su una piattaforma che supporta i modelli Compose come Docker Model Runner, scarica ed esegue ogni modello concesso a un servizio, tralasciando qualsiasi altro a meno che non venga avviato con --all-resources, e imposta, in ciascun servizio a cui è concesso, le variabili che il suo riferimento nomina sull’indirizzo del model runner e sull’identificatore del modello. La build non può vedere l’host che eseguirà il file, quindi non controlla né la versione di Compose né la piattaforma: un file che porta modelli viene assemblato allo stesso modo qualunque cosa lo esegua.
Una Feature associata a un componente contribuisce allo stesso file
Una Feature associata a un componente apporta i propri servizi al docker-compose.yaml in cui viene assemblato il suo componente ospitante, alle stesse condizioni della Recipe propria dell’ospitante. Non c’è alcun secondo file accanto: un percorso di assemblaggio produce un solo documento, quindi i servizi di una Feature associata o si trovano in quel documento o non vengono distribuiti affatto. Dissociare la Feature rimuove esattamente quei servizi e lascia intatti quelli propri del componente ospitante.
Sono contributori in quel percorso di assemblaggio come qualsiasi altro, quindi tutto ciò che è descritto sopra si applica a essi senza modifiche — la regola sui nomi dei servizi, e il requisito che due contributori che dichiarano uno stesso nome di volume o di config di primo livello concordino su ciò che è. Si uniscono inoltre alla stessa rete del resto del confine, così un componente e una Feature associata a esso si raggiungono a vicenda tramite il nome di servizio senza nient’altro da dichiarare.
Ogni servizio che una Feature contribuisce porta l’identità composta per quell’associazione anziché quella del componente ospitante, così i due restano distinguibili all’interno di un documento a cui entrambi hanno contribuito. Etichette e annotazioni spiega come viene costruita quell’identità.
Questo è un meccanismo diverso dal blocco attachments: a livello di container di un Workload, e i due si leggono facilmente come uno solo perché condividono una parola. Associare una Feature a un componente aggiunge servizi al documento assemblato; la voce attachments: di un container legge una credenziale che uno slot ha pubblicato in quel solo container, ed è trattata in Campi del container.
Frammenti compose emessi come artefatti
Quando il blocco artifacts: di una Recipe si valuta in YAML compose — un frammento che porta i propri blocchi services:, volumes:, configs:, models: o networks: (ogni voce inline o caricata per voce con $import:) — l’unione nell’assemblaggio per (path, provider) segue regole specifiche per ciascuna forma:
- I
services:provenienti dagli artefatti si uniscono nel file compose assemblato accanto ai servizi per componente. Un nome di servizio fornito da due componenti diversi nello stesso percorso di assemblaggio arresta la build, e la diagnostica nomina ogni contributore. Una collisione all’interno di un singolo componente — tra il frammento di artefatto proprio di quel componente e i servizi sintetizzati per esso — non viene rilevata, e il contributo successivo sostituisce quello precedente, quindi mantieni il nome di un servizio scritto in un artefatto distinto dai nomi<component>e<component>--<container-name>che il sintetizzatore produce (vedi Come viene denominato un servizio sidecar o di init). - I
volumes:provenienti dagli artefatti si uniscono nel bloccovolumes:di primo livello. Due voci che arrivano a uno stesso nome lasciano una sola voce sotto di esso dove lo dichiarano in modo identico, secondo la stessa regola dei volumi per componente; due che lo dichiarano in modo diverso arrestano la build, sia che provengano da due componenti sia da due frammenti di uno stesso componente — due delle sue vociartifacts:, oppure una di esse e il file compose proprio del componente. Poiché un frammento di artefatto scrive i propri corpi, è su questa via che due contributori hanno più probabilità di essere in disaccordo. Mantieni il nome di un volume scritto in un artefatto distinto dagli altri nel suo percorso di assemblaggio, compresa la forma<component>--<volume-name>prodotta dalla derivazione — a meno che due contributori non debbano descrivere un unico volume condiviso, nel qual caso le loro dichiarazioni devono coincidere. - I
configs:provenienti dagli artefatti si uniscono nel bloccoconfigs:di primo livello. È così che il file dietro un volumeconfigmapraggiunge l’assemblaggio: il volume diventa un riferimentoconfigs:a livello di servizio che nomina la configmap, e il frammento di artefatto dichiara una voce con quel nome concontent:inline. Una volta uniti i frammenti del percorso di assemblaggio, ogni riferimento a livello di servizio deve risolversi in una voce dichiarata, altrimenti la build si arresta conTRANSLATION_ERRORnominando ogni riferimento non risolto — il servizio, il nome della config e il percorso di montaggio. Il controllo viene eseguito sull’unione completa anziché per componente, quindi un componente può fare riferimento a una config che un altro componente nello stesso percorso di assemblaggio dichiara. L’unione si riconcilia per nome dove i contributori concordano: due che dichiarano uno stesso nome di config concontent:identico lasciano l’unica voce che entrambi hanno descritto. Due che dichiarano uno stesso nome concontent:diverso arrestano la build conTRANSLATION_ERROR, nominando la config e ogni tupla(boundary, node, fragment)che contribuisce, compresi due frammenti di uno stesso componente — una voce di config porta sempre un contenuto, quindi mantenere l’una o l’altra dichiarazione scarterebbe un file scritto da un autore. Mantieni un nome di config distinto tra tutti i contributori nel suo percorso di assemblaggio, oppure rendi identiche le dichiarazioni dove due contributori devono fornire un unico file condiviso. - I
models:provenienti dagli artefatti si uniscono nel bloccomodels:di primo livello, e il riferimentomodels:di un servizio viaggia con il suo servizio, secondo le regole in Modelli: due contributori che dichiarano uno stesso nome di modello devono dichiararlo in modo identico, e ogni riferimento deve nominare un modello che qualche contributore nel percorso di assemblaggio dichiara. - I
networks:provenienti dagli artefatti vengono rifiutati. Il provider compose deriva le reti dalle annotazioni del confine (una rete per ogni annotazioneaggrega.ai/namespacedistinta, più una chiamata come il percorso del file compose, a cui si unisce ogni nodo che non ne porta alcuna, ciascuna nominata secondo Come viene derivato il nome di una rete), quindi una dichiarazione di rete fornita da un artefatto non ha posto nel file assemblato: qualsiasi voce arresta la build, nominando la voce e il frammento, secondo le regole in Ogni chiave che un frammento scrive viene portata o rifiutata. Rimuovi la voce e modella le reti tramite l’annotazioneaggrega.ai/namespace, oppure fai in modo che un servizio si unisca alle reti di componenti nominati tramitex-aggrega-networks-of; gli autori che hanno bisogno di routing tra reti all’interno di un singolo file compose usano la Featurecompose-bridge. - I membri di estensione provenienti dagli artefatti vengono portati. Una chiave
x-di primo livello viene scritta dopo le altre sezioni del file assemblato, nell’ordine in cui è scritta, secondo le regole in I membri di estensione vengono portati così come sono scritti. - Qualsiasi altra chiave di primo livello proveniente dagli artefatti arresta la build.
services:,volumes:,configs:,models:e i membri di estensione sono tutto ciò che l’assemblatore porta da un frammento. Un bloccosecrets:e unname:di primo livello arrestano ciascuno la build nominando la chiave e il frammento, secondo le regole in Ogni chiave che un frammento scrive viene portata o rifiutata. - Il corpo di un
artifacts:è un solo documento. Un corpo che contiene più documenti YAML arresta la build nominando il frammento e quanti documenti contiene; assegna a ciascun documento una propria voceartifacts:.
L’asimmetria tra i primi quattro e networks: è strutturale: services:, volumes:, configs: e models: portano contenuto per Recipe che l’assemblatore accumula nel file assemblato; networks: è infrastruttura per confine che l’assemblatore deriva dallo stato del confine. Gli artefatti possono estendere i primi; solo le annotazioni del confine possono modellare la seconda, ed è per questo che la voce di rete propria di un artefatto viene rifiutata. I membri di estensione sono dati che la Compose Specification definisce per altri strumenti, quindi vengono portati così come sono scritti. Tutto il resto è una forma per cui il documento assemblato non ha posto, ed è per questo che viene rifiutato anziché unito.
Cosa non fornisce il provider compose
- Routing L4 tra reti all’interno di un unico file compose. Il provider colloca ogni nodo sulla propria rete e unisce un servizio alle reti che
x-aggrega-networks-ofnomina, e di per sé non instrada nulla tra le reti. Un servizio nella rete A che raggiunge un servizio nella rete B con qualcosa di diverso dal DNS predefinito di docker-compose richiede la Featurecompose-bridge, la cui FeatureRecipe scrive il gateway e la riscrittura. - Instradamento tra file compose. I confini che si valutano in percorsi di assemblaggio distinti producono file
docker-compose.yamldistinti; il runtime di compose li tratta come progetti indipendenti, e la Featurecompose-bridgelascia una connessione tra due file così come è scritta. La comunicazione tra file è compito dell’operatore (pubblicare porte dell’host, condividere reti esterne o far confluire i confini in un unico percorso tramite unadirectory:condivisa). - Ricavare una variabile d’ambiente da un’associazione. Compose non ha una primitiva per farlo, quindi una voce
attachmentsdi un Workload conas: envemette il nome della variabile con un valore vuoto anziché un riferimento risolto a runtime. Il segnaposto è voluto — una variabile presente ma vuota è visibile a chiunque esegua il debug del container, mentre una assente non lascia nulla da esaminare — e la build lo dice anziché lasciare che lo si scopra: ogni voce di questo tipo genera un avvisounsupported-fieldche nomina la voce alla sua coordinata di authoring (containers.<name>.attachments.<KEY>, oppureinitContainers[<i>].attachments.<KEY>), così l’autore sa quale variabile arriva vuota e a quale container appartiene. L’avviso è consultivo: la build riesce, e il file renderizzato è byte per byte ciò che sarebbe senza di esso.--no-unsupported-field-warningssilenzia la classe. Una voceattachmentsconas: filenon è interessata — compose la monta con un bind mount, e non viene generato alcun avviso. - Contenuto
deploy:della modalità swarm. Repliche, vincoli di collocazione e strategia di aggiornamento sottodeploy:sono funzionalità della modalità swarm, e il provider compose punta solo a compose su un singolo host, quindi non ne emette nessuna. Emette invecedeploy.resources— le riserve e i limiti a cui corrispondono leresourcesdi un container, che docker compose rispetta in modalità non swarm (vedi Risorse dei container). depends_onvincolato alla condizione di salute da un arcouses. Una dipendenza derivata da un arcousesviene emessa senza vincolo, con la semanticaservice_started; non è vincolata al fatto che l’healthcheck della destinazione segnali di essere integro. Questo riguarda ciò che un arcousessignifica, non una forma che il provider non può produrre: la forma lunga viene emessa per l’attesa di un init container, e un’ondata di distribuzione vincola effettivamente l’attesa alla salute della destinazione dove la destinazione dichiara un healthcheck.
Esempio di authoring
Una distribuzione compose a due servizi con un arco depends_on derivato da uses:
# release.yaml fragmentspec: boundaries: production: annotations: aggrega.ai/namespace: prod components: api: {} db: {}# api RecipeapiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: api version: 1.0.0spec: capability: compose implements: example/compute/api:1.0.0 workload: | apiVersion: aggrega.ai/v1beta1 kind: Workload containers: main: image: api:1.0 ports: http: 8080 health: live: http: /healthz services: public: type: NodePort ports: http: 8080# Aggregate fragment — api uses db, on a socket api's Component declaresapiVersion: aggrega.ai/v1beta1kind: Aggregatespec: components: api: type: example/compute/api:1.0.0 uses: backend: db: target: db db: type: example/datastore/db:1.0.0Il provider compose produce un unico docker-compose.yaml nel percorso valutato del confine (per impostazione predefinita dist/boundaries/production/compose/docker-compose.yaml, perché la directory: di un confine ha come valore predefinito dist/boundaries/<name> e subDirectory: ha {{ .capability }}) che contiene:
services.api(il servizio api principale, reteprod, porte8080:8080, healthcheck tramitecurl,depends_on: [db])services.db(il servizio db principale, reteprod)networks.prod(la rete docker del confine)
Riferimenti correlati
- Entità Workload — il tipo Workload di proprietà della piattaforma che il provider compose traduce.
- Architettura dei Provider — come i provider si inseriscono nella pipeline di compilazione.
- Annotazioni ben note — le annotazioni
aggrega.ai/*che il provider compose utilizza. - Indice di riferimento dei Provider — cosa produce ciascun provider della libreria standard, e quale pagina risponde a quale domanda.
- Composizione degli input delle Recipe — la Matrice delle capacità per Provider canonica.