Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Portugal)
Esta página foi traduzida automaticamente. Ler o original em inglês.

Provider Compose

O fornecedor compose renderiza Recipes do Aggrega num ficheiro Docker Compose. O fornecedor monta por (path, provider): os contribuidores compose de cada fronteira são encaminhados para o montador indexado pelo directory: avaliado da fronteira unido ao subDirectory: de cada componente, e esse montador emite um único docker-compose.yaml que contém todos os contribuidores nesse caminho. Duas fronteiras irmãs que são avaliadas para o mesmo caminho fundem-se num único ficheiro compose combinado — o exemplo canónico é uma fronteira-mãe mais duas fronteiras-filhas com directory: "{{ .parent_boundary.directory }}" (o padrão compose-bridge).

Tipos de entrada suportados

O fornecedor compose aceita os três tipos de entrada de Recipe:

  • Modo proveniente de uma fonte. Uma Recipe com source: a apontar para um ficheiro compose existente mais valuesMapping: a produzir um documento de sobreposição. O ficheiro compose de base é carregado, a sobreposição é avaliada, e os dois são combinados em profundidade segundo a semântica de sobreposição nativa do docker-compose.
  • Modo Workload. Uma Recipe com workload: (inline ou carregado através de $import:) declara um documento Workload. O fornecedor sintetiza um ou mais serviços compose a partir da especificação do Workload.
  • Modo de artefactos. As entradas artifacts: de uma Recipe são avaliadas como fragmentos compose, que se combinam no ficheiro montado segundo as regras em Fragmentos compose emitidos como artefactos. Os artefactos podem acompanhar uma fonte ou um Workload, e podem também ser a saída inteira de uma Recipe: uma Recipe que declara artifacts: e nem source: nem workload: é renderizada aqui, contribuindo com aquilo que os seus fragmentos declararem. É assim que um componente feito apenas de recursos — um conjunto partilhado de rede e volumes, uma configuração pré-carregada — chega a uma implementação compose sem um Workload de substituição a ocupar o lugar de uma capacidade de computação que não tem.

Os três tipos combinam-se por adição, e uma Recipe que não declara nenhum deles é recusada ao ser carregada. Um valuesMapping: sem um source: ao lado também é recusado quando a Recipe é carregada, seja qual for o fornecedor que nomeia: não há nada a que aplicar a sobreposição, e o diagnóstico pede que se declare o ponteiro source: ou se retire o valuesMapping:.

Mapeamento de funcionalidades do Workload

Quando uma Recipe declara workload:, o fornecedor traduz a forma de Workload detida pela plataforma em primitivas compose. O mapeamento é intencionalmente restrito — a superfície do Compose é mais pobre em formas do que a do Kubernetes, e várias funcionalidades do Workload degradam-se para o equivalente compose mais próximo, com perda documentada.

Campos do contentor

Campo do WorkloadCampo do Compose
imageimage
imagePullPolicy: Always / IfNotPresent / Neverpull_policy: always / if_not_present / never
commandentrypoint (forma de lista) — substitui o ponto de entrada da imagem, que é o que essa chave do compose faz
argscommand (forma de lista) — fornece os argumentos que o ponto de entrada recebe, que é o que o command do compose substitui
variablesenvironment (forma de mapa)
attachments[as: env]entrada de environment com valor vazio, e um aviso que nomeia a entrada (consulte O que o fornecedor compose não entrega)
attachments[as: file]bind-mount de volumes na forma longa, só de leitura
volumeMountsa primitiva compose para a qual a variante de volume referenciada é mapeada — uma entrada volumes na forma longa, uma entrada tmpfs: ao nível do serviço ou uma referência configs: ao nível do serviço (consulte Volumes)
portsimplícito (os contentores compose expõem as portas em que a imagem escuta)
restartPolicy: Alwaysrestart: unless-stopped
restartPolicy: OnFailurerestart: on-failure
restartPolicy: Neverrestart: "no"

variables e attachments[as: env] vão parar ao único mapa environment, primeiro as entradas lidas de anexos e depois as variables, cada uma pela ordem em que é escrita — a ordem que o fornecedor helm escreve, pelo que um Workload renderiza uma única sequência de ambiente em todos os destinos. O Compose não expande nenhuma referência $(NAME) entre as entradas de ambiente de um serviço, pelo que, no compose, essa ordem não tem nenhum significado em runtime. Como o mapa contém cada nome uma única vez, um contentor que dê um nome tanto como entrada de variables como como entrada de attachments entregue as: env interrompe a compilação em vez de manter um dos dois valores (consulte A container gives one environment variable two values (Um contentor dá dois valores a uma mesma variável de ambiente)).

Recursos dos contentores

Os resources de um contentor chegam ao bloco deploy.resources do compose, que o docker compose respeita no modo não swarm. As requests do Kubernetes exprimem um mínimo garantido, pelo que se tornam reservations do compose; os limits exprimem um limite máximo rígido, pelo que se mantêm limits.

Campo do WorkloadCampo do ComposeTradução
resources.requests.cpudeploy.resources.reservations.cpusUma contagem decimal de núcleos. Uma contagem de núcleos escrita como número simples (2, 0.5) é emitida tal como está escrita; qualquer outra forma é convertida a partir do seu valor (500m → 0.5, 1500m → 1.5, 5n → 0.000000005, 1e1 → 10)
resources.limits.cpudeploy.resources.limits.cpusA mesma conversão
resources.requests.memorydeploy.resources.reservations.memoryUma contagem exata de bytes, convertida a partir do valor em qualquer forma em que esteja escrito — 8Gi torna-se 8589934592, 1.5Gi torna-se 1610612736, 1e3 torna-se 1000
resources.limits.memorydeploy.resources.limits.memoryA mesma conversão
nvidia.com/gpu, sob resources.limits, resources.requests ou ambosdeploy.resources.reservations.devicesUma entrada de dispositivo NVIDIA no serviço do contentor — driver: nvidia, count: a contagem de GPUs, capabilities: [gpu]. A contagem é a do limite onde um limite está escrito — a contagem que o Kubernetes agenda para um recurso estendido — e a do pedido caso contrário. Uma contagem de 0 não pede nenhuma GPU e não escreve nenhuma entrada
qualquer outra chave de recurso estendido — amd.com/gpu e qualquer outro <domain>/<name>—Sem análogo compose num único anfitrião. A chave é descartada e a compilação emite um aviso unsupported-field que a nomeia, um por chave distinta, independentemente de quantas das requests e dos limits a tinham. O seu valor não é emitido, pelo que não é verificado

Cada valor de cpu, memory e nvidia.com/gpu é lido como uma quantidade, na forma descrita em Workload → Quantidades de recursos, no Workload tal como os templates da Recipe o avaliaram. Duas situações interrompem a compilação com um TRANSLATION_ERROR, e o erro diz qual das duas encontrou, nomeando o caminho do contentor, se o valor é um pedido ou um limite, o recurso e o valor:

  • um valor que não é uma quantidade — lots, 1.5 cores, ou o m que um template vazio deixa em "{{ .infra.cpu }}m";
  • uma quantidade que o compose não consegue representar exatamente — um valor negativo; um valor de memória que não é um número inteiro de bytes (1500m, 4u) ou que é maior do que 9223372036854775807 bytes (8Ei); um valor de cpu mais fino do que nove casas decimais de um núcleo, a precisão mais fina que a própria quantidade do Kubernetes conserva, ou maior do que 9223372036.854775807 núcleos; uma contagem de GPUs que não é um número inteiro de dispositivos (0.5, 500m).

Um contentor cujo pedido e cujo limite de nvidia.com/gpu pedem contagens diferentes interrompe a compilação da mesma forma, nomeando os dois caminhos: o compose reserva uma única contagem por serviço, pelo que, de outro modo, a tradução teria de escolher uma. Deve escrever-se a mesma contagem em ambos, ou apenas o limite.

Nada é arredondado, e não é emitido nenhum valor que signifique outra coisa.

Um pedido de GPU reserva GPUs NVIDIA. Um contentor de Workload que peça nvidia.com/gpu: "1" é renderizado como um serviço que tem esta reserva, ao lado de quaisquer cpus e memory que os seus pedidos reservem:

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

O Docker Compose entrega as GPUs reservadas ao contentor quando o anfitrião Docker tem esse número de GPUs NVIDIA e está configurado para as dar aos contentores; a compilação não consegue ver o anfitrião, pelo que um ficheiro que reserva GPUs é montado da mesma forma onde quer que venha a ser executado. A entrada indica sempre a sua contagem, porque o Compose lê uma entrada de dispositivo sem contagem como todas as GPUs do anfitrião. Só a chave NVIDIA é traduzida: amd.com/gpu e a chave de qualquer outro fabricante mantêm o aviso da linha das chaves descartadas. A linha runtimeClassName em Campos ao nível do pod mantém-se inalterada — o compose não tem análogo da runtime class, pelo que um Workload que nomeia um runtime com suporte para GPU é informado de que o runtime foi omitido, enquanto a sua contagem de GPUs é reservada.

Probes

Os três slots de probe de um Workload (live, ready, startup) reduzem-se ao único healthcheck por serviço do compose, com a prioridade live > ready > startup (vence o sinal de liveness mais canónico). Onde essa redução descarta um slot que o autor declarou, a compilação emite um aviso unsupported-field que nomeia o slot traduzido e os slots descartados, de modo que uma intenção que não chega a nenhuma parte da saída é comunicada em vez de perdida. Um bloco health que declara um único slot é traduzido sem perda e não emite nada, a menos que o slot defina successThreshold: um healthcheck do compose não tem campo para isso, pelo que um valor escrito pelo autor — 1 incluído — é omitido com um aviso unsupported-field que o nomeia (containers.<name>.health.<slot>.successThreshold), e o resto do slot é traduzido como mostra a tabela abaixo.

Forma de probe do Workloadhealthcheck.test do 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, ...]

A forma HTTP exige que o contentor declare pelo menos uma porta com nome; o sintetizador escolhe o primeiro nome de porta por ordem alfabética e usa o seu número para construir o URL do curl. Os contentores sem portas declaradas não podem usar probes HTTP — o compilador é interrompido com um TRANSLATION_ERROR que nomeia a probe em causa.

Os campos de timeout das probes são mapeados para cadeias de duração ao estilo do compose:

Campo do WorkloadCampo healthcheck do Compose
periodSecondsinterval: <n>s
timeoutSecondstimeout: <n>s
failureThresholdretries: <n>
initialDelaySecondsstart_period: <n>s

Volumes

O Compose tem uma primitiva de config própria, que é aquilo em que um volume configmap se traduz. Não tem um equivalente Kubernetes para Secret nem para templates de volume por réplica, pelo que essas variantes se degradam para a primitiva compose mais próxima:

Variante de volume do WorkloadTradução do ComposeNotas sobre perdas
ephemeralentrada de lista tmpfs: ao nível do serviçosizeLimit não é preservado (a forma curta de tmpfs do compose não tem tamanho). Um sizeLimit escrito pelo autor gera um aviso unsupported-field que o indica na sua coordenada de autoria (volumes.<name>.ephemeral.sizeLimit), quer um contentor monte o volume, quer não; omitir o campo não gera nada
configmapreferência configs: ao nível do serviço que indica o configmap, montado no caminho da montagem do volume🔴 O caminho de montagem é o caminho de um único ficheiro, não de um diretório. O Compose escreve o conteúdo da config exatamente no caminho de destino, ao passo que um destino Kubernetes que monta um ConfigMap num caminho produz um diretório com um ficheiro por chave. Assim, o mesmo path: escrito designa aqui um ficheiro e ali um diretório: a montagem de um volume configmap deve apontar para o nome do ficheiro que o contentor deve ler (/seed/config.json), e não para o diretório que o conteria, e uma Recipe escrita para ambos os destinos tem um caminho diferente para cada destino. Nada na compilação consegue detetar um caminho escrito para a forma do outro destino — o caminho é uma cadeia de caracteres opaca que o compilador passa tal como está, e a saída emitida é válida em ambos os casos. A referência é feita pelo nome, exatamente como um destino Kubernetes referencia um recurso ConfigMap — nada lê o conteúdo da config. A entrada configs: de nível superior correspondente vem da entrada artifacts: da Recipe, cujo fragmento compose a declara com content: inline; uma referência sem essa entrada interrompe a compilação (consulte Fragmentos compose emitidos como artefactos). Uma referência configs: contém o nome da config e o caminho de montagem e nada mais, pelo que o readOnly da montagem não tem expressão própria
secretbind-mount de volumes na forma longa, só de leituraUm volume de secret deliberadamente não segue a tradução configmap: uma entrada configs: inline escreveria o valor do secret em texto simples no ficheiro compose emitido, e o compilador nunca resolve um secret em texto simples — um secret continua a ser um ponteiro em todas as fases da compilação. A origem do bind é o nome source do secret, resolvido como um caminho que o operador torna acessível no host compose independentemente da compilação
persistentvolume com nome + declaração volumes: { <volume-name>: {} } de nível superior, nomeado conforme Como é derivado um nome de volumeA classe de armazenamento, os modos de acesso e o tamanho não são preservados (o compose não tem forma equivalente). Um class ou accessModes escrito pelo autor gera um aviso unsupported-field que o indica na sua coordenada de autoria (volumes.<name>.persistent.class, volumes.<name>.persistent.accessModes); omitir qualquer um deles não gera nada. O size obrigatório não gera nenhum aviso — ver abaixo
persistentTemplatevolume com nome + declaração de nível superior, nomeado da mesma forma (tal como persistent)Complemento de form: stateful; o compose não tem primitiva de templates de volume por réplica, pelo que o comportamento por réplica se perde, e um aviso unsupported-field indica que o volume se tornou um único volume partilhado por todas as réplicas. A classe de armazenamento, os modos de acesso e o tamanho não são preservados, exatamente como em persistent: um class ou accessModes escrito pelo autor gera um aviso unsupported-field em volumes.<name>.persistentTemplate.class ou volumes.<name>.persistentTemplate.accessModes, e o size obrigatório não gera nenhum

O subPath de uma montagem monta parte de um volume onde o compose tem uma forma para isso. Uma entrada volumeMounts que indique um volume persistent ou persistentTemplate com subPath torna-se uma entrada volumes em forma longa com volume.subpath, pelo que a montagem vê o diretório ou ficheiro indicado dentro do volume em vez da sua raiz, e duas montagens de um mesmo volume com dois valores subPath diferentes veem duas partes diferentes dele:

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

Uma montagem escrita sem subPath não tem nenhum bloco volume:. Um subPath numa montagem de um volume ephemeral, configmap ou secret interrompe a compilação com um erro TRANSLATION_ERROR que indica o componente, o contentor, o caminho escrito da montagem (containers.<name>.volumeMounts[<i>]), o volume e o subPath: essas variantes chegam ao compose como uma entrada tmpfs, uma referência configs: e uma montagem bind, nenhuma das quais monta parte daquilo que entrega, pelo que, de outro modo, a montagem veria o volume inteiro. Deve remover-se subPath de uma montagem assim, ou montar-se um volume persistent. O Docker Compose lê volume.subpath a partir da versão 2.26.0, no Docker Engine 26.0 ou posterior; a compilação não consegue ver o host que vai executar o ficheiro, pelo que um ficheiro que contenha um é composto da mesma forma onde quer que venha a ser executado.

Um volume diz qual é a sua variante e nada mais. Um volume secret tem exatamente uma tradução — a montagem bind só de leitura acima — e um volume não tem nenhum campo as: para selecionar outra. Entregar o que um slot publicou como variável de ambiente cabe a uma entrada attachments do contentor (as: env), e não a um volume; o que o compose faz com uma entrada assim está em O que o fornecedor compose não entrega.

Três variantes têm um tamanho de armazenamento, e só uma delas avisa que o tamanho foi descartado. A diferença está em ter havido ou não escolha. O sizeLimit de um volume ephemeral é opcional, pelo que escrevê-lo foi uma decisão, e o aviso indica que o valor não molda nada neste destino e pode ser removido — é consultivo e fora de banda, o ficheiro emitido é byte a byte o que seria sem ele, e --no-unsupported-field-warnings silencia-o juntamente com o resto da classe. O size de um volume persistent ou persistentTemplate é obrigatório, pelo que nenhuma versão do documento o omite: um aviso a cada compilação dispararia aí em todas as cargas de trabalho com estado sem indicar nada que se pudesse alterar, por isso a diferença é explicada aqui em vez de comunicada a cada compilação. Tendo o compose como destino, size, class e accessModes de um volume persistente não moldam nada no ficheiro emitido — o que se obtém é um volume com nome simples, dimensionado e suportado pelo que o driver de volumes do host compose fizer por predefinição. class e accessModes são opcionais, pelo que cada um que se escreva é comunicado tal como o sizeLimit de um volume ephemeral: um aviso unsupported-field por campo, consultivo e fora de banda, silenciado pelo mesmo indicador. O armazenamento subjacente dimensiona-se no host, ou no destino Kubernetes, onde os campos chegam de facto à saída.

Um volume que nenhum contentor monta gera um aviso unsupported-field que o indica na sua coordenada de autoria (volumes.<name>), porque o que chega ao ficheiro emitido difere então muito consoante a variante. persistent e persistentTemplate continuam a produzir a sua declaração de nível superior, pelo que o volume é criado e nada o usa. ephemeral, configmap e secret não têm expressão fora da própria montagem — cada um traduz-se em algo escrito no caminho de montagem, respetivamente uma entrada tmpfs, uma referência configs ou uma montagem bind —, pelo que, sem nada que monte um deles, o volume declarado não deixa qualquer rasto na saída. Esse segundo caso é a razão de ser do aviso: sem ele, um volume configmap cuja montagem foi esquecida estaria simplesmente ausente, sem nada no ficheiro emitido que o assinalasse. Todos os contentores da carga de trabalho contam como contentores que montam o volume, incluindo os contentores de inicialização, pelo que um volume montado apenas por um contentor de inicialização está ligado e não gera nada. O aviso é consultivo e fora de banda — o ficheiro emitido é byte a byte o que seria sem ele — e --no-unsupported-field-warnings silencia a classe.

Como é derivado um nome de volume

Um volume persistent ou persistentTemplate torna-se um volume com nome do compose: uma entrada volumes: de nível superior, referenciada por todos os contentores que o montam. Um volume compose é armazenamento partilhado, e o bloco volumes: de nível superior une as suas entradas pelo nome — pelo que dois volumes escritos que cheguem a um mesmo nome se tornam um só volume no qual ambos os contentores escrevem, sem nada no ficheiro emitido que mostre que se pretendiam dois. Por isso, o nome é construído a partir das duas identidades que, em conjunto, dizem de que volume se trata: o <component> a que o volume pertence, e o nome que o Workload deu ao volume em volumes:.

Um nome de volume compose aceita um conjunto de caracteres mais restrito do que aquele que qualquer uma das identidades pode conter: letras, dígitos, pontos, sublinhados e hífenes. Em vez de substituir um carácter que o compose não aceita, a derivação escreve-o por extenso, pelo que dois volumes que difiram em algo chegam a dois nomes — e um nome composto pode ser lido de volta nas duas identidades a partir das quais foi construído.

  • Uma letra, um dígito, um ponto e um sublinhado são mantidos exatamente como foram escritos.
  • Um hífen é mantido tal como foi escrito sempre que o carácter que o segue é mantido diretamente e não é um z minúsculo. Um hífen seguido de um z minúsculo abre uma sequência de escape, pelo que um hífen escrito nessa posição é ele próprio escrito por extenso — api-zone torna-se api-zhzone, e é isso que permite ler de volta qualquer nome sem adivinhar. Um hífen sem nada a seguir é escrito por extenso pela mesma razão, pelo que db- dá db-zh.
  • Qualquer outro carácter é escrito como -z seguido de uma letra que o identifica: s para um separador de caminho, h para um hífen que a regra acima não mantém. Tudo o resto — incluindo um espaço e uma letra não ASCII — é escrito como x seguido do ponto de código hexadecimal de seis dígitos do carácter, e um byte que não inicia nenhum carácter como b seguido do seu próprio valor de dois dígitos, pelo que um nome que não é texto válido continua a ser escrito por extenso de forma distinta em vez de se confundir com outro.
  • Um valor vazio é escrito -ze, que nenhum valor não vazio pode produzir.
  • As duas identidades são unidas por --. Uma única identidade codificada nunca contém esse par, pelo que o nome unido diz sem ambiguidade onde uma identidade termina e a outra começa.

Assim, o componente store com um volume a que o Workload chama data dá o nome de volume store--data, e db-server com data dá db-server--data. Uma entrada idêntica produz sempre o nome idêntico.

É a junção dupla que torna o par inequívoco, e uma junção de um só carácter não o consegue. Qualquer uma das identidades pode conter ela própria um hífen, pelo que uma junção com um único hífen deixa um nome que se divide em mais de um ponto: db com um volume chamado data-cache e db-data com um volume chamado cache dariam ambos db-data-cache, e como o bloco de nível superior une pelo nome, os dois componentes partilhariam um só volume sem nada no ficheiro emitido que o mostrasse. Uma identidade codificada nunca contém um par de hífenes, pelo que a junção dupla não admite uma segunda leitura: os dois chegam a db--data-cache e db-data--cache.

Alterar qualquer uma das identidades muda o nome do volume compose, e o compose não muda o nome de um volume no local. O volume é criado de novo com o novo nome enquanto o antigo fica para trás com os dados lá dentro, pelo que o contentor arranca com armazenamento vazio e o conteúdo fica num volume que nada monta. Qualquer uma das identidades só deve ser renomeada como uma substituição a planear — com cópia de segurança, cópia dos dados ou agendamento — e não como uma alteração a simplesmente implementar.

Forma de controlador

O form do Workload seleciona uma forma abstrata de controlador (consulte entities/workload.md). O Compose renderiza stateless e stateful (e o valor predefinido vazio, tratado como stateless) como serviços de longa duração; a forma stateful acrescenta o volume com nome para um complemento persistentTemplate. As formas daemon, scheduled e task não têm um mapeamento compose limpo num único host, pelo que um Workload que declare uma delas tendo como destino uma fronteira compose interrompe a compilação com um erro TRANSLATION_ERROR que indica a forma e o conjunto suportado — o compose não degrada uma forma não suportada num serviço simples que deturpe a intenção. Um Workload reference declara um endpoint externo e nenhum contentor, pelo que o compose não emite nenhum serviço para ele.

Como nenhum serviço é emitido para um Workload reference, nada lê o pipe de entrega do componente que ele realiza: uma credencial anexada a esse componente — entregue no seu pipe por dotenv-secret, ou pelo próprio bloco inject: de um anexo — não chegaria a nenhum ficheiro emitido. Por isso, cada Recipe Compose da biblioteca padrão que realize desta forma um serviço externo, e cujo Component declare um slot de credencial, recusa uma credencial que preencha esse slot: a compilação é interrompida indicando o slot e o componente, em vez de ser bem-sucedida sem a credencial. No compose, uma credencial para um serviço externo é anexada ao componente que o chama, sob a variável de ambiente que esse componente lê. Essa recusa é uma asserção própria de cada Recipe, e é executada antes de este fornecedor renderizar o que quer que seja. Este fornecedor também recusa no próprio nó, seja qual for o catálogo de onde vem a Recipe: um anexo num nó reference cujo material é declarado sensível — a sua Feature declara um campo sensitive: true, ou o slot que preenche declara-o — interrompe a compilação com TRANSLATION_ERROR (E0288), indicando o nó e cada um desses anexos, quer algum slot declare ou não o nome sob o qual está anexado. Um anexo que não contenha nada declarado sensível não é recusado aqui. Esses Components declaram os seus slots de credencial como opcionais, pelo que, no compose, um slot deixado vazio não interrompe nada. Onde a realização Kubernetes precisa da credencial — as Recipes helm de twilio, vonage, telnyx, bland, letta, retell e vapi —, essa Recipe exige antes o slot, e interrompe a compilação indicando-o quando está vazio.

Exposição de serviços

O campo type de uma entrada services do Workload decide se o compose publica portas, e em que endereço do host:

Tipo de serviço do WorkloadComportamento do Compose
ClusterIPNenhuma publicação ports: — o serviço só é acessível na rede do compose
NodePortPublicação ports: [<host>:<container>], em todas as interfaces do host
LoadBalancerPublicação ports: [<host>:<container>], em todas as interfaces do host (o compose não tem equivalente a um load balancer gerido; a publicação numa porta do host é o análogo mais próximo)
LoopbackPublicação ports: [127.0.0.1:<host>:<container>] — acessível a partir do próprio host e de nenhum outro lugar
HeadlessNenhuma publicação ports:

Que número vai para que lado. Uma entrada de serviço indica uma porta de contentor e dá-lhe um número, tal como um Service Kubernetes mapeia o seu port para um targetPort. O número da entrada é o lado <host> do par publicado, e o número da porta de contentor para a qual o nome é resolvido é o lado <container>. Assim, um contentor que declare http: 8080 e uma entrada NodePort que escreva http: 8081 publicam 8081:8080: a porta 8081 do host chega à porta em que o contentor serve. Uma entrada que tenha o próprio número da porta de contentor publica esse número em ambos os lados, 8080:8080. Um par na rede do compose chega ao serviço pelo seu nome de serviço na porta do contentor, nunca na publicada — a porta publicada pertence ao host —, pelo que uma Recipe que publique uma porta à sua escolha continua a entregar aos seus consumidores a porta do contentor.

Uma entrada Loopback associa-se apenas ao endereço de loopback IPv4. O endereço de loopback IPv6 ::1 não é associado: a sintaxe de portas do compose tem um único endereço de host por entrada, e um host cuja interface de loopback não tenha endereço IPv6 não o conseguiria associar, pelo que o serviço não arrancaria aí. Os clientes no host chegam à porta em 127.0.0.1.

Quando vários serviços de um único Workload publicam a mesma porta de contentor sob o mesmo número, ela é publicada uma vez, e vence o alcance mais amplo: qualquer referência NodePort ou LoadBalancer publica-a em todas as interfaces do host, mesmo quando uma entrada Loopback também a indica e independentemente de qual entrada é declarada primeiro; uma porta que apenas entradas Loopback indicam é publicada em 127.0.0.1. Uma porta de contentor publicada sob dois números é publicada duas vezes, uma sob cada um. As portas publicadas são listadas pela ordem das portas de contentor, e por porta publicada dentro de uma mesma porta de contentor.

Transporte das portas. Uma entrada publicada tem o transporte declarado na porta de contentor que indica, como o sufixo /protocol do compose: 53:53/udp, ou 127.0.0.1:53:53/udp para uma entrada Loopback. Uma porta que não declare nenhum transporte é publicada como <host>:<container> sem sufixo, deixando em vigor a predefinição do próprio compose. O Compose escreve o transporte de uma porta publicada como tcp ou udp; uma porta que declare SCTP não tem grafia compose, pelo que interrompe a compilação com um erro TRANSLATION_ERROR em vez de publicar uma porta que teria um transporte diferente. Uma porta de contentor que nenhum serviço publica não chega a nenhuma parte do ficheiro compose, pelo que um transporte declarado numa porta assim não tem onde ser escrito e não interrompe a compilação.

Workloads com vários contentores

Um Workload com vários contentores torna-se um serviço principal mais um serviço sidecar por cada contentor não principal. O contentor principal é o que se chama main (quando existe) ou o primeiro contentor pela ordem de declaração. Os sidecars partilham o namespace de rede do serviço principal através de network_mode: "service:<main>" — a primitiva compose mais próxima do modelo de rede partilhada de um pod Kubernetes.

Como é nomeado um serviço sidecar ou de init

O serviço principal tem o nome <component> tal como está. Todos os outros serviços que o Workload produz — um por sidecar e um por contentor de init — são nomeados a partir de duas identidades em conjunto: o <component> e o nome do contentor, que é a sua chave em containers: para um sidecar e o seu name para um contentor de init, ou o init-<index> posicional que uma entrada de init sem nome assume. O bloco services: montado contém um serviço por nome, pelo que o nome é construído de forma a que dois contentores que difiram em qualquer uma das identidades cheguem sempre a dois nomes.

Cada identidade é escrita exatamente como as duas partes de um nome de volume — uma letra, um dígito, um ponto e um sublinhado tal como foram escritos, um hífen mantido onde as regras daí o mantêm, e todos os outros caracteres reescritos — e as duas são unidas por --, que nenhuma identidade reescrita contém. Assim, o componente api com um sidecar logger executa-o como api--logger, o contentor de init import-seed de platform é executado como platform--import-seed, e uma primeira entrada de init sem nome de api é executada como api--init-0. Um nome de contentor com um carácter que um nome de serviço não admite é reescrito em vez de emitido tal como foi escrito: um contentor de init chamado warm cache/x de api é executado como api--warm-zx000020cache-zsx.

A junção dupla mantém separados os contentores de dois componentes. api com um contentor warm-cache e api-warm com um contentor cache são executados como api--warm-cache e api-warm--cache, dois serviços, onde uma junção com um só hífen escreveria ambos como api-warm-cache.

Os sidecars e os contentores de init partilham esta única nomenclatura, pelo que uma entrada de containers e uma entrada de initContainers com o mesmo nome chegam ao mesmo nome de serviço, e a compilação para perante o par em vez de executar um contentor no lugar do outro (consulte Contentores de inicialização).

O serviço do próprio componente não recebe um destes nomes. O serviço principal tem o nome do componente, e um hífen duplo escrito no nome de um componente é ele próprio reescrito aí — um componente chamado api--prep é executado como api-zh-prep — pelo que nunca contém a junção --. Quando serviços de dois componentes diferentes ainda coincidem num nome no mesmo ficheiro compose — através de um serviço que um artefacto nomeia para si próprio, por exemplo — a compilação para, nomeando ambos, como descreve Saída por (path, provider).

Alterar o nome do componente ou o nome do contentor muda o nome do serviço. O Compose trata um serviço com um novo nome como um serviço novo, pelo que o seu contentor é criado de raiz com o novo nome.

Campos ao nível do pod

Os campos do Workload ao nível do pod aplicam-se apenas ao serviço principal — os sidecars partilham o namespace de rede do serviço principal — e um serviço de inicialização segue a mesma regra. A única exceção é o utilizador do pod: um pod executa cada um dos seus contentores como podSecurityContext.runAsUser e runAsGroup, pelo que estes chegam a todos os serviços que o Workload produz, incluindo os serviços sidecar e de inicialização.

Vários correspondem a um campo de serviço compose:

Campo do WorkloadCampo do Compose
podSecurityContext.runAsUser / runAsGroupuser ("1000", ou 1000:3000 com um grupo) em todos os serviços do Workload. Um contentor que defina o seu próprio securityContext.runAsUser é executado, em vez disso, como esse utilizador no seu próprio serviço, com o seu próprio runAsGroup quando define um
terminationGracePeriodSecondsstop_grace_period: <n>s
dnsConfig.nameservers / dnsConfig.searchesdns / dns_search
hostAliasesuma entrada extra_hosts por nome de host, pela ordem do autor
hostNetwork: truenetwork_mode: host

Execução na rede do nó. Uma carga de trabalho que declare hostNetwork: true recebe network_mode: host no seu próprio serviço, e esse serviço fica então fora da rede da fronteira em vez de ser conectado a ela: o compose recusa um serviço que declare simultaneamente networks: e network_mode:, pelo que os dois são alternativas e não adições. A consequência prática é a que a rede do host traz sempre — os pares deixam de chegar ao serviço pelo seu nome de serviço compose nessa rede, porque ele já não está nela; chegam-lhe nos endereços próprios do host, que é o que a declaração pediu. Nenhum outro serviço da fronteira é afetado.

Duas formas combinam-se com isto. Um sidecar continua a indicar o serviço principal (network_mode: "service:<main>"), pelo que segue o serviço principal para a rede do host sem declarar nada ele próprio — da mesma forma que os contentores de um pod Kubernetes partilham um único namespace. Um serviço de inicialização não: junta-se à rede da fronteira por direito próprio, porque partilhar o namespace do serviço principal tornaria circular a espera do serviço principal por ele. Assim, uma carga de trabalho com hostNetwork e initContainers em simultâneo executa o seu próprio serviço na rede do host enquanto os seus serviços de inicialização permanecem na rede da fronteira, o que é mais restrito do que a forma de pod que modela; um aviso unsupported-field indica essa diferença em vez de a deixar ser descoberta em tempo de execução.

Os restantes não têm equivalente num único host. Nenhum é descartado em silêncio: cada um que seja escrito gera um aviso unsupported-field que indica o campo, pelo que um autor fica a saber que definição o destino não conseguiu respeitar em vez de o descobrir pela stack em execução.

Campo do WorkloadPorque é que o compose não o consegue respeitar
schedulingO posicionamento — nodeSelector, affinity, tolerations, topologySpreadConstraints — pressupõe um escalonador que escolhe entre nós. O Compose é executado num único host
replicasA contagem de réplicas própria do compose fica sob deploy: e é uma funcionalidade do modo swarm
runtimeClassNameSelecionar um runtime de contentores alternativo — um com suporte para GPU, por exemplo — não tem expressão compose
priorityClassNameA ordenação por preempção pressupõe um escalonador
serviceAccountA identidade de Workload é um conceito de cluster
imagePullSecretsAs credenciais de registo num host compose são o estado de autenticação próprio do host, e não um campo do ficheiro
dnsPolicy, dnsConfig.optionsO Compose expõe dns e dns_search e nada mais fino
podSecurityContext.fsGroup, podSecurityContext.supplementalGroupsuser contém um utilizador e um grupo; o grupo a que pertencem os volumes de um pod, e os grupos adicionais para os seus processos, não são traduzidos
podSecurityContext.runAsGroup, quando o pod não define nenhum runAsUser, ou quando um contentor — principal, sidecar ou de inicialização — define o seu próprio runAsUser e nenhum runAsGroupuser só indica um grupo ao lado de um utilizador, e o utilizador próprio de um contentor toma o lugar do utilizador do pod, pelo que o grupo do pod não chega a nenhum serviço escrito dessa forma

O securityContext ao nível do contentor traduz-se parcialmente: readOnlyRootFilesystem → read_only, capabilities.add / drop → cap_add / cap_drop, runAsUser / runAsGroup → user. runAsNonRoot e allowPrivilegeEscalation não têm expressão compose e geram o mesmo aviso unsupported-field, tal como um runAsGroup de contentor escrito sem um runAsUser ao lado: o serviço é então executado como o utilizador do pod quando o pod define um, sem esse grupo.

Todos os avisos desta secção são consultivos e fora de banda: a compilação é bem-sucedida, e o ficheiro emitido é byte a byte o que seria sem eles. --no-unsupported-field-warnings silencia a classe.

Contentores de inicialização

As entradas initContainers de um Workload tornam-se serviços próprios, usando o idioma de execução até à conclusão do compose. Cada entrada acrescenta um serviço, nomeado a partir do <component> e do name da entrada pela mesma nomenclatura que os sidecars usam — <component>--<container-name> para um nome comum; uma entrada que omita name recebe o nome posicional init-<index> que a referência do Workload documenta, e é nomeada a partir dele.

A ordem que o contrato de autoria promete — os contentores de inicialização são executados até à conclusão pela ordem em que estão escritos, e todos os outros contentores só arrancam depois de todos eles terem terminado — é expressa com a forma longa de depends_on:

  • Cada serviço de inicialização a seguir ao primeiro espera pelo seu predecessor com condition: service_completed_successfully.
  • O serviço principal, e cada serviço sidecar, espera pelo último serviço de inicialização com a mesma condição. Esperar pelo último é suficiente porque os serviços de inicialização formam uma cadeia.
  • Cada serviço de inicialização tem restart: "no". Um serviço de inicialização é executado uma vez; um serviço que voltasse a arrancar nunca chegaria ao estado concluído pelo qual os seus dependentes esperam, pelo que uma restartPolicy escrita num contentor de inicialização não altera isto.
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"

Um contentor de inicialização é traduzido exatamente como qualquer outro contentor: o seu image (incluindo a reescrita de registo que uma anotação aggrega.ai/image-registry aplica), command, args, variables, attachments, volumeMounts e securityContext chegam todos ao serviço de inicialização. É isso que faz com que a configuração que um contentor de inicialização transporta — na maioria das vezes um ficheiro que monta e escreve num volume que o contentor principal também monta — sobreviva no destino compose em vez de se perder com o contentor. Uma forma que o compose não consegue expressar falha da mesma maneira para um contentor de inicialização e para um comum: um lifecycle ou envFrom declarado interrompe a compilação com um erro TRANSLATION_ERROR que indica o contentor de inicialização de onde veio.

Duas diferenças em relação ao serviço principal decorrem de um serviço de inicialização ser um serviço não principal:

  • Os campos do Workload ao nível do pod não são aplicados, a mesma regra que os sidecars seguem — exceto o utilizador do pod, que chega a todos os serviços como Campos ao nível do pod descreve.
  • Um serviço de inicialização junta-se diretamente à rede da sua fronteira em vez de partilhar o namespace de rede do serviço principal como faz um sidecar. Tem de o fazer: o serviço principal espera pelo serviço de inicialização, e partilhar um namespace é, em si, uma dependência do serviço principal, o que fecharia a espera num ciclo que o compose se recusa a iniciar. Por isso, um contentor de inicialização chega a outros serviços na rede da fronteira pelo nome de serviço, mas não partilha o localhost do serviço principal.

Os serviços de inicialização e os serviços sidecar partilham um único espaço de nomes, porque uma única nomenclatura dá nome a ambos, pelo que uma entrada initContainers e uma entrada containers não podem ter o mesmo nome. Quando têm, o compilador é interrompido com um TRANSLATION_ERROR que indica o nó, o nome do contentor e o nome de serviço que ambos queriam, em vez de deixar que um serviço substitua silenciosamente o outro.

Emitir a condição de conclusão não eleva nenhuma versão mínima do Compose. condition e os seus valores pertencem à Compose Specification de base — ao contrário dos campos restart e required ao lado deles no mesmo bloco em forma longa, que a especificação associa a versões específicas do Compose. Cada versão mínima que a saída do fornecedor compose pede vem com a construção que dela precisa: ≥ 2.23.1 para configs.content inline, ≥ 2.26.0 para o subPath de uma montagem (consulte Volumes), e 2.38 para modelos. A primeira chega a qualquer saída compose que tenha uma config com content: inline, que é como chegam tanto o ficheiro por trás de um volume configmap como a config por trás de uma aresta entre redes com ponte — e não um único caminho de autoria.

A que rede um serviço se junta

Cada serviço junta-se a uma rede Docker; os sidecars herdam-na através da sua referência network_mode ao serviço principal. A rede em que um nó fica é lida da anotação aggrega.ai/namespace nesse nó, recorrendo ao caminho do ficheiro compose quando o nó não tem essa anotação — o diretório no qual o ficheiro é escrito sob o diretório de saída da compilação, como bridge/compose para uma fronteira cujo directory: é bridge. Assim, todos os nós sem a anotação num ficheiro compose juntam-se a uma única rede com o nome do caminho do ficheiro, seja qual for a fronteira em que se encontram: as fronteiras sem anotação que partilham um ficheiro compose partilham essa rede, e é aggrega.ai/namespace que as separa. Os nós com anotações diferentes ficam numa rede por cada anotação distinta. Como é derivado um nome de rede é o nome que essa identidade produz.

Como é derivado um nome de rede

Uma rede compose é conectividade L3 partilhada, e o bloco networks: de nível superior une as suas entradas pelo nome — pelo que duas identidades que cheguem a um mesmo nome se tornam uma só rede na qual ficam ambos os conjuntos de serviços, que chegam uns aos outros pelo nome de serviço, sem nada no ficheiro emitido que mostre que se pretendiam duas redes. Por isso, o nome é construído a partir da identidade que diz de que rede se trata: a anotação aggrega.ai/namespace do nó, ou o caminho do ficheiro compose quando o nó não tem nenhuma.

Um nome de rede compose aceita um conjunto de caracteres mais restrito do que aquele que qualquer uma das identidades pode conter: letras, dígitos, pontos, sublinhados e hífenes. Em vez de substituir um carácter que o compose não aceita, a derivação escreve-o por extenso, pelo que duas identidades que difiram em algo chegam a duas redes — e um nome pode ser lido de volta na identidade a partir da qual foi construído.

  • Uma letra, um dígito, um ponto e um sublinhado são mantidos exatamente como foram escritos, com as maiúsculas e minúsculas com que foram escritos. Assim, prod e Prod são duas redes, e não uma.
  • Um hífen é mantido tal como foi escrito sempre que o carácter que o segue é mantido diretamente e não é um z minúsculo. Um hífen seguido de um z minúsculo abre uma sequência de escape, pelo que um hífen escrito nessa posição é ele próprio escrito por extenso — api-zone torna-se api-zhzone, e é isso que permite ler de volta qualquer nome sem adivinhar. Um hífen sem nada a seguir é escrito por extenso pela mesma razão, pelo que db- dá db-zh.
  • Qualquer outro carácter é escrito como -z seguido de uma letra que o identifica: s para um separador de caminho, h para um hífen que a regra acima não mantém. Tudo o resto — incluindo um espaço e uma letra não ASCII — é escrito como x seguido do ponto de código hexadecimal de seis dígitos do carácter, e um byte que não inicia nenhum carácter como b seguido do seu próprio valor de dois dígitos, pelo que uma identidade que não é texto válido continua a ser escrita por extenso de forma distinta em vez de se confundir com outra.
  • Uma identidade totalmente ausente — um nó sem anotação aggrega.ai/namespace num ficheiro compose sem caminho — é escrita -ze, que nenhuma identidade escrita por um autor pode produzir. Por isso, uma rede sem identidade nunca partilha conectividade com uma que tenha uma identidade escrita de alguma forma específica.

Assim, um namespace prod dá a rede prod, core-net dá core-net, e um ficheiro compose em dist/app/compose dá dist-zsapp-zscompose. Uma entrada idêntica produz sempre o nome idêntico.

Um namespace e o caminho de um ficheiro compose são escritos no mesmo espaço. São duas formas de nomear a mesma coisa — em que rede está um nó —, pelo que um nó cujo namespace é app/compose e um nó sem namespace no ficheiro compose em app/compose ficam deliberadamente numa só rede, exatamente como acontece com duas fronteiras que tenham a mesma anotação aggrega.ai/namespace. Para manter dois nós separados, dê-lhes identidades que difiram.

Alterar a identidade de um nó muda o nome da rede compose, e o compose não muda o nome de uma rede no local. A rede é criada de novo com o novo nome e todos os serviços nela são recriados para se conectarem a ela, enquanto a rede antiga fica para trás até que algo a remova. Uma rede não contém dados, pelo que nada se perde — mas os contentores nela reiniciam de facto, e tudo o que mantenha uma conexão durante a alteração vê-a cair. Uma alteração de uma anotação de namespace, ou do diretório no qual um ficheiro compose é escrito, deve ser tratada como uma nova implementação a planear, e não como um valor a ajustar no local.

Quando duas fronteiras convergem num único caminho de composição (directory: partilhado), os seus nós sem uma anotação aggrega.ai/namespace partilham a única rede do ficheiro; dê a cada fronteira a sua própria anotação aggrega.ai/namespace e o docker-compose.yaml fundido declara uma entrada networks: de nível superior por anotação. Os serviços de fronteiras diferentes dentro do mesmo ficheiro compose podem comunicar pelos seus nomes de serviço dentro da resolução DNS predefinida do compose, sujeitos às próprias regras de alcançabilidade entre redes do compose. O encaminhamento L4 entre redes dentro de um único ficheiro compose é o que a Feature compose-bridge da biblioteca padrão permite, como conteúdo de catálogo do qual este fornecedor não contém nenhuma lógica: anexada à fronteira ancestral comum, a sua FeatureRecipe deriva um gateway das arestas uses da fronteira cujas duas extremidades são compostas no seu próprio ficheiro compose e ficam em redes diferentes dele — um serviço aggrega-gw cuja config nginx stream faz de proxy a cada aresta com ponte (um bloco server por aresta, na porta do destino com uma alternativa portBase em caso de colisão) — e o seu próprio injectMapping reescreve a variável de ambiente de host de cada consumidor para aggrega-gw:<port>, ou para aggrega-gw com a variável de porta reescrita para a porta de escuta quando a mesma conexão entrega ambas. Essa reescrita substitui o valor que a própria conexão do consumidor entregou; se outra Feature anexada ao consumidor tiver entregado a mesma variável, a compilação é interrompida indicando ambas em vez de o substituir. O valuesMapping da FeatureRecipe escreve essa config como uma config compose montada — uma entrada configs: de nível superior com content: inline, referenciada a partir do gateway e montada em /etc/nginx/nginx.conf; não é uma montagem a cargo do operador — e indica cada endpoint com ponte sob o x-aggrega-networks-of do gateway, que este fornecedor resolve nas redes em que esses endpoints estão posicionados (abaixo). Uma aresta cujas duas extremidades são compostas em dois ficheiros compose não recebe ponte e mantém o nome próprio do destino; uma fronteira sem nada para fazer ponte continua a ter o gateway inativo, sem config e sem nenhuma rede além da sua; e uma ponte anexada a uma fronteira cujo ficheiro compose não contém nenhum componente interrompe a compilação em vez de escrever o gateway em lado nenhum. A config stream tem uma diretiva resolver e faz de proxy através de uma variável por aresta (set $uN <host>; proxy_pass $uN), para que cada upstream seja resolvido no momento da conexão e não uma única vez no arranque — caso contrário, um proxy_pass simples para um destino que ainda não está em execução faria o gateway falhar no arranque. (O $ nessas variáveis é escapado como $$ dentro de configs.content para que a interpolação $ própria do Docker Compose deixe um $ literal para o nginx.) configs.content inline requer o Docker Compose ≥ 2.23.1. Consulte o padrão compose-bridge.

Juntar-se às redes de outros componentes — x-aggrega-networks-of

Um serviço que um fragmento escreve — um ficheiro compose proveniente de uma fonte depois de a sua sobreposição ser fundida, ou um corpo artifacts: — pode juntar-se às redes de outros componentes compostos no mesmo ficheiro compose indicando-os sob a chave de extensão x-aggrega-networks-of: uma lista de IDs de componentes, os IDs que o Aggregate dá aos seus componentes, que uma FeatureRecipe de âmbito de fronteira lê como as chaves de .boundary.components e como o source e o target das suas listas de arestas .boundary. O fornecedor resolve cada ID na rede em que esse componente está posicionado neste ficheiro, pelo mesmo posicionamento que todos os nós recebem, e acrescenta essas redes ao serviço, cada uma uma única vez e por ordem de nome, antes da rede própria do serviço, à qual continua a juntar-se. A própria chave é deixada de fora do ficheiro composto. O fornecedor lê os IDs como referências a resolver e nada sobre o que o serviço faz, pelo que qualquer Recipe ou FeatureRecipe pode usar a chave; o gateway da ponte compose junta-se desta forma às redes dos endpoints entre os quais faz o reencaminhamento.

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

Três coisas interrompem a compilação com TRANSLATION_ERROR quando o ficheiro é composto, cada uma indicando o serviço:

  • Um ID que nenhum componente composto neste ficheiro tem — um composto noutro ficheiro compose, por exemplo. Uma rede pertence a um único ficheiro, pelo que a mensagem indica o ID e o ficheiro em que o serviço se encontra. Indique apenas componentes compostos no mesmo ficheiro, ou remova o ID.
  • Um valor que não é uma lista de cadeias de caracteres. A chave aceita uma lista de IDs de componentes, mesmo para um único ID.
  • A chave num serviço que escreve network_mode. O Compose não permite que um serviço com um network_mode se junte a redes; remova um dos dois.

Inferência de depends_on

O fornecedor compose deriva depends_on automaticamente das arestas uses do IR. Para cada aresta cuja origem e cujo destino contribuem ambos com serviços para o ficheiro compose combinado, o fornecedor acrescenta depends_on: [<target>] ao serviço de origem.

A dependência recai sobre o próprio serviço do componente de origem, e sobre nenhum outro serviço com que esse componente contribui. Um componente que declare também contentores de inicialização contribui com um serviço executado até à conclusão por cada entrada, e nenhum deles recebe a dependência derivada da aresta — uma aresta nomeia o componente, e um serviço de inicialização tem um nome próprio. Assim, um contentor de inicialização que tenha de alcançar o destino da aresta, como uma migração de esquema contra uma base de dados para a qual o componente aponta com uses, não transporta qualquer ordenação em relação a esse destino e pode ser executado antes de este estar acessível, enquanto o próprio serviço do componente espera tanto que a cadeia de inicialização termine como que o destino tenha sido iniciado.

As entradas derivadas de arestas são emitidas sem condição: têm a semântica service_started independentemente de o destino declarar um healthcheck. Condicioná-las à saúde do destino — o que permitiria ao runtime do compose bloquear o arranque até que o healthcheck do destino comunique que está saudável — é exprimível, e uma aresta uses não o pede. Uma wave que nomeie o mesmo par é a única coisa que altera a condição de uma entrada derivada de uma aresta, e fá-lo porque é a wave que o pede, e não a aresta.

As entradas derivadas de arestas são emitidas por ordem alfabética de destino, para estabilidade da saída. As arestas cuja origem ou cujo destino é servido por outro fornecedor (helm ou helm-chart) são ignoradas — depends_on só se aplica dentro do subconjunto da Release servido pelo compose.

O depends_on de um serviço é emitido numa das duas formas do compose, nunca numa mistura das duas, porque o compose exige uma condição em cada entrada da forma longa:

  • Lista em forma curta (depends_on: [<service-name>]) quando nenhuma entrada desse serviço tem uma condição. É o caso de todos os serviços cujas únicas dependências vêm de arestas uses.
  • Mapeamento em forma longa quando alguma entrada tem uma — o que acontece quando o serviço também espera por um contentor de inicialização, ou quando uma wave de implementação o ordena. Aí, as entradas derivadas de arestas emitem a condition: service_started explícita, que a Compose Specification define como o equivalente da forma curta, pelo que o seu significado não se altera.

Dentro de um serviço, as origens mantêm a sua própria ordem e não se intercalam: a espera pela cadeia de inicialização, cuja ordem é aquela em que o autor escreveu a lista, é emitida primeiro, depois as entradas derivadas de arestas por ordem alfabética, depois as derivadas de waves por ordem alfabética.

Ordem por waves de implementação

O valor syncWave: de uma fronteira de uma Release ordena os serviços do ficheiro compose no qual essa fronteira é renderizada. Cada componente da fronteira herda a wave da fronteira e, onde várias fronteiras partilham um mesmo directory: — de modo que as suas contribuições se fundem num único docker-compose.yaml —, o ficheiro combinado contém mais de uma wave e o fornecedor exprime a ordenação entre elas como depends_on.

Cada serviço espera por todos os serviços da wave imediatamente anterior que tenha serviços, e por nenhuma wave anterior a essa. O compose resolve o resto de forma transitiva: um serviço na wave 2 espera pela wave 1, que espera pela wave 0, pelo que toda a sequência fica ordenada enquanto a lista própria de cada serviço mantém o tamanho de uma wave e não o do ficheiro inteiro. As waves não têm de ser contíguas, e os valores negativos são normais — -1 é uma escolha comum para uma migração que é executada antes de tudo o resto.

A condição depende do que o destino consegue satisfazer. Uma wave significa que o grupo anterior está ativo antes de o seguinte arrancar, o que é prontidão e não arranque do processo, pelo que:

  • onde o serviço de destino declara um healthcheck, a espera é condition: service_healthy;
  • onde não o declara, a espera é condition: service_started, porque um serviço sem healthcheck nunca pode comunicar que está saudável e uma espera condicionada à sua saúde nunca seria satisfeita — o ficheiro nunca chegaria a arrancar.

A condição mais fraca é visível no ficheiro emitido ao lado da mais forte, e a compilação nomeia ainda cada um desses serviços num aviso, para que um autor que esperava uma ordenação por prontidão fique a saber que parte da wave que declarou chega apenas como ordenação de arranque. O aviso é consultivo: a compilação é bem-sucedida e os bytes renderizados são exatamente o que seriam sem ele. Acrescentar um bloco health: a esse contentor é o que reforça a espera. --no-unsupported-field-warnings silencia a classe.

A wave continua a ser registada como etiqueta. A ordenação é acrescentada ao lado da etiqueta aggrega.ai/sync-wave, e não em vez dela: a etiqueta é onde quem inspeciona o ficheiro emitido vê de que wave veio um serviço, o que as entradas depends_on não indicam.

Onde uma wave e uma aresta uses nomeiam o mesmo par, uma única entrada transporta ambas. O Compose aceita uma entrada por dependência, pelo que um serviço que aponta para um destino com uses e fica também uma wave depois dele emite uma única entrada condicionada à condição da wave — o requisito da wave é o mais forte dos dois e é o que é expresso.

Uma fronteira cujos componentes estão todos numa mesma wave não emite nada por isto. O mesmo vale para uma Release que não declara nenhum syncWave: cada contribuidor tem o valor predefinido do campo, 0, o ficheiro combinado contém uma única wave, e a saída é exatamente a que seria se o fornecedor não exprimisse nenhuma ordem de waves.

A ordenação entre dois ficheiros compose não é exprimível, e não é aproximada. depends_on nomeia um serviço dentro do mesmo ficheiro, e as fronteiras que são avaliadas para caminhos de montagem distintos produzem ficheiros docker-compose.yaml distintos que o runtime do compose trata como projetos independentes. Assim, uma wave ordena todos os serviços do ficheiro no qual é renderizada e nada fora dele. Sequenciar dois projetos compose é assunto do operador, da mesma forma que o encaminhamento entre ficheiros; declarar um directory: partilhado é o que leva duas fronteiras a um único ficheiro, e é uma decisão sobre a forma da saída a tomar pelas suas próprias razões e não para obter ordenação.

Uma aresta uses que aponta para uma wave posterior é emitida tal como foi escrita, e reportada. O depends_on emitido reflete o que foi declarado — tanto as arestas uses como as waves. Uma aresta cujo consumidor está numa wave anterior à do destino que usa afirma o contrário do que as waves afirmam: a aresta faz o consumidor esperar pelo destino, enquanto as waves fazem o destino esperar, através de cada wave entre eles, pelo consumidor. O ficheiro combinado exprime ambos, o que constitui um conjunto de dependências circulares que o Docker Compose se recusa a iniciar. A compilação nomeia cada uma dessas arestas num aviso que indica ambos os serviços e ambas as waves, para que o ciclo surja no momento da compilação e não no docker compose up. O aviso é consultivo — a compilação é bem-sucedida e os bytes renderizados são exatamente o que seriam sem ele — e --no-unsupported-field-warnings não o silencia, porque nada foi descartado: as duas declarações são expressas cada uma, e juntas não conseguem arrancar. Cobre apenas o par direto: nomeia os dois serviços que uma aresta une em vez de seguir o ciclo inteiro. Qualquer ciclo construído a partir de arestas uses e waves em conjunto passa por pelo menos uma dessas arestas, pelo que é sempre reportado; um ciclo formado apenas por arestas uses, sem nenhuma wave envolvida, e um fechado por uma entrada depends_on escrita num ficheiro compose que a Recipe fornece são emitidos tal como foram escritos e não são reportados. Convém manter coerentes a direção das arestas e a ordem das waves: colocar o consumidor na wave do destino ou numa posterior, ou o destino na wave do consumidor ou numa anterior.

# release.yaml fragment — three boundaries collapsing onto one compose file
boundaries:
data:
directory: ./dist/cluster
syncWave: -1
components:
migrator: {} # no health: block
core:
directory: ./dist/cluster
syncWave: 0
components:
store: {} # declares health:
edge:
directory: ./dist/cluster
syncWave: 1
components:
frontend: {} # uses: store
# dist/cluster/compose/docker-compose.yaml (abridged)
services:
frontend:
labels:
aggrega.ai/sync-wave: "1"
depends_on:
store:
condition: service_healthy # store declares a healthcheck
migrator:
labels:
aggrega.ai/sync-wave: "-1" # lowest wave: waits on nothing
store:
depends_on:
migrator:
condition: service_started # migrator declares no healthcheck
healthcheck:
test: [CMD-SHELL, "nc -z localhost 5432"]

frontend não nomeia migrator: a ordenação alcança a wave imediatamente anterior e o compose encadeia o resto através de store.

Modo com fonte

O source: do fornecedor compose nomeia um ficheiro YAML do docker-compose que o fornecedor consegue ler e analisar, e aceita as duas formas que o campo source: assume: uma cadeia simples com um caminho do sistema de ficheiros, e um objeto estruturado cujo url: transporta a localização. Sempre que essa localização for um caminho do sistema de ficheiros, fica ancorada ao diretório que contém o recipe.yaml que a declara, e não ao diretório a partir do qual a compilação é invocada, e tem de permanecer dentro desse diretório: um caminho que saia dele, ou um absoluto, é recusado, porque cada ficheiro que uma publicação da Recipe transporta é retirado do seu diretório — consulte entities/recipe.md «Content paths stay inside the Recipe’s own directory (Os caminhos de conteúdo permanecem dentro do próprio diretório da Recipe)». O ficheiro assim nomeado é publicado com a Recipe, ao passo que um ficheiro ao lado da Recipe que nada do que ela declara nomeia não o é.

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

Na forma estruturada, o que url: transporta decide se algo é obtido. Um fragmento publicado através de https:// é obtido e fixado com kind: compose-https-fragment; aggrega pull adquire-o e a compilação lê-o da cache. Um url: que nomeia um caminho do sistema de ficheiros não é obtido — é lido do disco, ancorado exatamente como a forma de cadeia simples acima, e aggrega pin regista o digest do ficheiro que nomeia no ficheiro entity.lock ao lado da Recipe, que uma compilação compara depois antes de o fragmento ser lido. Copiar localmente um fragmento remoto (vendoring) e apontar source: para a cópia local é suportado como alternativa à obtenção, e não é obrigatório. O esquema aceita um objeto estruturado aberto.

Uma Recipe com source: <path-to-compose-file> e valuesMapping: executa o seguinte pipeline:

  1. O ficheiro compose de base em <path> é lido e analisado como YAML.
  2. O template valuesMapping é avaliado em relação ao contexto de template da Recipe. A sua saída é tratada como um documento de sobreposição compose — um ficheiro compose parcial que complementa ou substitui campos da base.
  3. A base e a sobreposição são combinadas em profundidade segundo a semântica de sobreposição nativa do docker-compose.

As regras da combinação em profundidade:

  • Escalares: prevalece a sobreposição. Quando a base e a sobreposição definem o mesmo campo escalar, o valor da sobreposição substitui o valor da base.
  • Mapas: combinação recursiva. Quando a base e a sobreposição definem o mesmo campo de mapa, a combinação desce recursivamente no mapa. As chaves presentes em ambas seguem as mesmas regras; as chaves presentes em apenas uma são preservadas tal como estão.
  • Listas: substituição. Quando a base e a sobreposição definem o mesmo campo de lista, a lista da sobreposição substitui por inteiro a lista da base (sem combinação elemento a elemento nem acrescento no fim). Isto corresponde ao comportamento de docker compose -f base.yaml -f overlay.yaml config.
  • null: substitui, e permanece. Uma chave que a sobreposição define como null num serviço — uma das chaves próprias do serviço, como user, command ou healthcheck, uma entrada de environment, uma etiqueta, ou uma chave diretamente sob healthcheck ou deploy — substitui o valor da base como qualquer escalar e é escrita no ficheiro compose como key: null; não remove a chave. Onde o fornecedor escreve um valor próprio nessa chave, o ficheiro tem antes o valor do fornecedor: labels: null mantém as etiquetas de proveniência que o fornecedor aplica, e networks: null a rede a que o associa. Um null escrito em qualquer outro ponto da sobreposição fica fora desta regra. O que um null significa então é a leitura que o Compose faz desse atributo — uma entrada de environment sem valor, por exemplo, recebe o seu valor do ambiente em que docker compose é executado.

Todas as etiquetas que o autor de um serviço escreveu permanecem. Os labels: de um serviço no ficheiro de base ou na sobreposição podem ser escritos como um mapa ou como a lista de entradas key=value do Compose, e cada etiqueta chega ao ficheiro compose ao lado das etiquetas de proveniência que o fornecedor aplica. Uma entrada de lista é lida como o Compose a lê: o texto antes do seu primeiro = nomeia a etiqueta e o texto depois dele é o valor, e uma entrada sem = é uma etiqueta com valor vazio. Um número ou um valor true/false é escrito como o seu texto, pelo que replicas-hint: 2 chega ao ficheiro como replicas-hint: "2", e uma etiqueta escrita como null continua null. Onde uma etiqueta escrita pelo autor e uma etiqueta de proveniência partilham uma chave, o ficheiro tem o valor de proveniência. Um valor de labels: que não seja nem um mapa nem uma lista, e uma entrada de lista que não seja texto, interrompem a compilação, nomeando o ficheiro de origem e o serviço. As etiquetas de serviço do corpo de um artifacts: assumem a forma de mapa: uma lista aí interrompe a compilação, nomeando o artefacto e o serviço.

O documento combinado segue depois para a combinação ao nível da Release juntamente com quaisquer contribuições do modo sintetizado, com a mesma rede por fronteira e a mesma inferência de depends_on.

Deixar de fora serviços, volumes e configurações. A sobreposição não pode remover nada do ficheiro de base — um valor da sobreposição substitui, nunca elimina —, pelo que um ficheiro obtido que inclua um serviço que a Release não deve executar é precisamente o caso para que servem as entradas omits: de uma Recipe ou de uma FeatureRecipe. Este fornecedor respeita-as neste modo e em nenhum outro: um Workload sintetizado e um corpo de artifacts: são renderizados sem elas. Uma entrada nomeia uma unidade de nível superior do ficheiro pelo seu kind — service, volume ou config — e pelo seu name, a chave da unidade sob services:, volumes: ou configs:, comparada exatamente. Um ficheiro compose não tem namespaces, pelo que uma entrada que tenha um namespace, tal como uma que nomeie qualquer outro tipo, interrompe a compilação quando o componente é renderizado, nomeando a entrada e os tipos que este fornecedor aceita; cada entrada é verificada antes de qualquer coisa ser deixada de fora. As entradas são comparadas com o ficheiro depois de a sobreposição acima ter sido combinada nele, pelo que uma unidade que a sobreposição acrescentou é deixada de fora exatamente como uma que a base declarou, e antes de o fornecedor acrescentar algo próprio, pelo que uma entrada nunca nomeia isso. Uma unidade que uma entrada nomeie é removida, e uma secção cujas unidades sejam todas deixadas de fora é removida com elas; todas as outras unidades são escritas exatamente como seriam sem as entradas. As entradas alcançam o ficheiro da Recipe ou da FeatureRecipe que as declara e nada mais: o que outro componente ou uma Feature anexada contribui para o mesmo docker-compose.yaml fica intacto, incluindo uma unidade com a mesma chave. O fornecedor indica quantas unidades cada entrada deixou de fora, e uma entrada que não deixou nenhuma de fora interrompe a compilação; consulte An omits entry left out nothing the source rendered (Uma entrada omits não deixou de fora nada do que a fonte renderizou).

Uma unidade deixada de fora não pode continuar a ser nomeada pelo que resta, porque o compose recusa um ficheiro que nomeie um serviço, um volume ou uma configuração que não declara. Depois de removidas as unidades, cada referência que o ficheiro ainda faça a uma delas interrompe a compilação, e a mensagem nomeia cada serviço ou job que faz a referência, a unidade que nomeia e o campo em que está a referência. Uma referência é o que a Compose Specification define como uma entrada de um ficheiro que nomeia outra:

  • um serviço, nomeado por depends_on em qualquer das formas, por links (SERVICE ou SERVICE:ALIAS), por volumes_from (SERVICE ou SERVICE:MODE), por network_mode, ipc, pid ou uts definido como service:<name>, por extends que nomeie um serviço do mesmo ficheiro, ou por um valor service:<name> de build.additional_contexts;
  • um volume, nomeado como origem de uma entrada volumes: — a forma curta SOURCE:TARGET em que a origem é um nome e não um caminho, e a forma longa de type: volume;
  • uma configuração, nomeada por uma entrada configs:, em qualquer das formas.

Os hooks pre_start de um serviço e cada entrada jobs: de nível superior também são lidos, pelas referências que a especificação permite que cada um deles transporte. Alguns valores apenas parecem referências e não são lidos como tal: uma entrada volumes_from ou network_mode que comece por container: nomeia um contentor, external_links nomeia um contentor que este ficheiro não declara, um extends com um file: nomeia um serviço de outro ficheiro, e um credential_spec.config pode nomear uma configuração detida pela plataforma e não pelo ficheiro. Cada valor é comparado tal como está escrito, pelo que uma referência escrita através de um ${VARIABLE} não é uma que esta verificação veja, e uma referência a uma unidade que o ficheiro nunca declarou é deixada como está.

A verificação lê apenas o ficheiro próprio da Recipe ou FeatureRecipe que declara, pelo que uma referência a um serviço deixado de fora interrompe a compilação mesmo onde outro contribuidor no mesmo caminho de montagem declara um serviço com esse nome. Para manter a referência, mantém-se a unidade. Para a remover, altera-se a entrada que faz a referência através de valuesMapping: — uma lista aí substitui a lista do ficheiro de base, pelo que depends_on: [] esvazia uma — ou deixa-se também de fora o serviço que faz a referência.

Saída por (path, provider)

Cada caminho de composição compose produz um docker-compose.yaml. As fronteiras que são avaliadas para caminhos distintos produzem ficheiros compose distintos; as fronteiras que partilham um caminho avaliado produzem um único ficheiro compose combinado que contém todos os contribuidores nesse caminho. O caminho é o directory: da fronteira unido ao subDirectory: por componente (cujo valor predefinido é {{ .capability }}, pelo que os contribuidores compose ficam, por predefinição, numa subpasta compose/).

As colisões de nomes de serviço dentro de um único caminho de composição interrompem a compilação. Quando dois nós diferentes contribuem com serviços com o mesmo ID de instância na mesma tupla (path, provider), o compilador interrompe-se e o diagnóstico indica cada tupla (boundary, node) contribuinte por ordem alfabética. O autor resolve a colisão mudando o nome de um dos contribuidores (tipicamente ajustando o identificador do nó para que o sintetizador produza um nome de serviço diferente), ou encaminhando os contribuidores para caminhos distintos através de declarações directory: diferentes.

Os volumes de nível superior unem-se dentro de um caminho de composição, e dois contribuidores podem declarar um mesmo nome desde que concordem quanto a ele. Um contribuidor é um fragmento, pelo que dois fragmentos de um mesmo componente — o seu próprio ficheiro compose e uma entrada artifacts:, ou duas entradas artifacts: — são dois contribuidores exatamente como o são dois componentes. Um volume com nome é um único volume físico, pelo que duas declarações idênticas descrevem ambas exatamente a entrada com que o ficheiro composto acaba, e este mantém uma única entrada sob esse nome. Um volume que o fornecedor derivou não tem corpo, pelo que dois deles concordam trivialmente, e de qualquer modo não podem encontrar-se (consulte Como é derivado um nome de volume).

Uma entrada volumes: escrita pelo autor é a que merece atenção, porque pode ter um corpo próprio — um driver, driver_opts ou labels. Quando dois contribuidores declaram um mesmo nome com corpos diferentes, a compilação é interrompida com TRANSLATION_ERROR, indicando o volume e cada tupla (boundary, node, fragment) contribuinte. Quando dois autores discordam sobre um único volume, não há resposta entre as quais o montador possa escolher: manter qualquer um dos corpos descarta o que o outro autor escreveu, numa compilação que de outra forma teria êxito. Para o resolver, tornam-se idênticas as duas declarações, quando ambos os autores queriam o mesmo volume, ou muda-se o nome de uma delas, quando queriam dois. As redes de nível superior são uma por cada anotação aggrega.ai/namespace distinta, mais uma com o nome do caminho do ficheiro compose para os nós que não têm nenhuma, com nomes atribuídos segundo Como é derivado um nome de rede; duas fronteiras contribuintes com a mesma anotação aggrega.ai/namespace fundem-se numa única rede partilhada por ambas, tal como duas fronteiras sem anotação que partilham o ficheiro.

Cada chave que um fragmento escreve é transportada ou recusada

Um fragmento — um ficheiro compose proveniente de uma fonte depois de a sua sobreposição ser fundida, ou um corpo artifacts: que é avaliado como YAML compose — chega ao docker-compose.yaml composto apenas através das chaves que o fornecedor transporta, e esse conjunto é fixo. Cada chave que um fragmento escreve é transportada para o ficheiro composto tal como foi escrita ou recusada pelo nome; nenhuma é deixada de fora sem uma palavra. Um fragmento é um único ficheiro compose, pelo que é um único documento YAML.

  • Transportadas. No nível superior: services, volumes, configs e models. Num serviço: image, pull_policy, command, entrypoint, environment, env_file, ports, labels, volumes, tmpfs, networks, network_mode, depends_on, healthcheck, restart, user, working_dir, privileged, read_only, cap_add, cap_drop, configs, models, deploy, stop_grace_period, dns, dns_search, extra_hosts e profiles. Dentro dos blocos que o fornecedor descreve: deploy.resources com os seus limits (cpus, memory) e reservations (cpus, memory, devices, e de cada entrada de dispositivo driver, count, device_ids, capabilities e options); test, interval, timeout, retries e start_period de um healthcheck; type, source, target, read_only e volume.subpath de uma entrada volumes: em forma longa; source e target de uma entrada configs: em forma longa; condition de uma entrada depends_on: em forma longa; driver, driver_opts e labels de um volume de nível superior; content de uma configuração de nível superior. O corpo de um modelo e a entrada models: em forma longa de um serviço transportam todos os membros, como descreve Modelos. Um membro de extensão — uma chave que começa por x- — é transportado no nível superior e num serviço, como descreve Membros de extensão.
  • Recusadas. Qualquer outra chave — stdin_open num serviço, um secrets: ou name: de nível superior, deploy.replicas, um restart: ou required: dentro de uma entrada depends_on: em forma longa, uma chave x- dentro do corpo de um volume de nível superior ou de um healthcheck — interrompe a compilação com TRANSLATION_ERROR, indicando cada uma dessas chaves, o seu caminho no fragmento (services.migrate.stdin_open), o fragmento e o componente, e indica os dois sítios de onde uma tal chave provém. Um é o próprio fragmento, e a correção consiste em remover-lhe a chave. O outro é uma Recipe proveniente de uma fonte que não declara nenhum valuesMapping:: os valores do nó são então sobrepostos ao ficheiro compose tal como estão, pelo que cada chave de valor chega como uma chave de nível superior do fragmento, e a correção consiste em declarar um valuesMapping: que coloque cada valor sob uma chave que o fornecedor transporta. Uma chave que uma chave de fusão YAML (<<: *anchor) traz para um bloco é avaliada onde chega, como se tivesse sido escrita aí. Um fragmento renderizado a partir da fonte chama-se <component>.compose-fragment.yaml; um fragmento artifacts:, pelo nome que a sua Recipe lhe dá.
  • Recusada por inteiro: uma rede própria do fragmento. Uma entrada sob os networks: de nível superior de um fragmento interrompe a compilação com TRANSLATION_ERROR seja qual for o conteúdo do seu corpo — uma entrada vazia, um driver, qualquer outra coisa — indicando a entrada (networks.back), o fragmento e o componente, porque o ficheiro composto contém apenas as redes que o fornecedor deriva (consulte A que rede um serviço se junta). Remova a entrada: um serviço junta-se à rede do seu próprio componente sem nada declarado, a anotação aggrega.ai/namespace escolhe a que rede um componente se junta, um serviço indica os componentes a cujas redes também se junta sob x-aggrega-networks-of, e a Feature compose-bridge faz o encaminhamento entre serviços em redes diferentes. Um networks: {} vazio não declara nada e não é recusado, e a própria lista networks: de um serviço é transportada como acima.
  • Recusado por inteiro: um fragmento de mais de um documento. Um corpo artifacts: que contém dois ou mais documentos YAML separados por --- interrompe a compilação com TRANSLATION_ERROR, indicando o fragmento, o componente e quantos documentos contém, porque a fusão lê um fragmento como um único ficheiro compose e cada documento depois do primeiro ficaria de outra forma ausente do ficheiro composto. Escreva o fragmento como um único documento, ou dê a cada documento uma entrada artifacts: própria. Um documento que não contém nada — o vazio que um --- final abre — não é contado. Um ficheiro compose proveniente de uma fonte com vários documentos nunca se torna um fragmento deste tipo: é recusado quando o ficheiro é lido.

O fornecedor não lê o significado de nenhuma chave: uma chave é transportada porque está no conjunto acima e recusada porque não está.

Os membros de extensão são transportados tal como foram escritos

A Compose Specification reserva as chaves que começam por x- para extensões: dados que uma ferramenta que lê o ficheiro pode usar e que o próprio Compose ignora. Os membros de extensão de um fragmento no nível superior e num serviço chegam ao ficheiro composto tal como foram escritos, depois de todas as chaves que o fornecedor modela nesse nível, pela ordem em que o fragmento os contém; o fornecedor não lê nada dentro deles, exceto o x-aggrega-networks-of de um serviço, que resolve nas redes a que o serviço se junta e deixa de fora do ficheiro composto (consulte Juntar-se às redes de outros componentes). Um corpo artifacts: contém-nos pela ordem em que os escreve. As chaves de um ficheiro compose proveniente de uma fonte chegam ao seu fragmento por ordem de nome depois de a sua sobreposição ser fundida, pelo que os seus membros de extensão são escritos por ordem de nome.

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

Um membro alcançado através de um alias YAML é escrito por extenso, e nenhuma âncora é transportada, pelo que o ficheiro composto nunca contém um alias cuja âncora lhe falte; é isto que permite que um membro de nível superior contenha uma âncora que a chave de fusão de um serviço (<<: *base) traz. Os membros de um serviço viajam com o seu serviço. Os membros de nível superior unem-se dentro de um caminho de composição segundo a regra que os volumes seguem: dois fragmentos que escrevem um mesmo membro com o mesmo conteúdo deixam uma única entrada, quer o escrevam em estilo de bloco quer de fluxo, e dois que o escrevem com conteúdo diferente interrompem a compilação com TRANSLATION_ERROR, indicando o membro e cada tupla (boundary, node, fragment) contribuinte — incluindo dois fragmentos de um mesmo componente. Torne idênticas as duas declarações, ou dê a uma delas um nome diferente.

profiles condiciona um serviço a um perfil do Compose. Um serviço que lista profiles: é um que docker compose up deixa de lado, a menos que um dos seus perfis esteja ativado, e que docker compose run --rm <service> inicia a pedido — a forma compose de uma tarefa executada a pedido. A lista é transportada tal como o fragmento a escreve, pela sua ordem:

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

Modelos

A secção models: de nível superior de um ficheiro compose declara os modelos de IA que os serviços do ficheiro usam, e a um serviço é concedido um modelo através da sua própria entrada models:. O fornecedor transporta ambos de um fragmento para o docker-compose.yaml composto, na grafia própria do Compose, quer o fragmento seja um ficheiro compose proveniente de uma fonte quer um corpo artifacts: que é avaliado como YAML compose. Um Workload não declara nenhum modelo, pelo que uma Recipe em modo Workload não contribui com nenhum.

  • O corpo de um modelo é escrito tal como o fragmento o escreveu. model — o identificador do artefacto OCI do modelo — context_size e runtime_flags mantêm os seus nomes, e todos os outros membros, entre eles uma extensão x-, são transportados ao lado deles. Dentro de um modelo, os três membros nomeados vêm primeiro e o resto segue por ordem de chave, e os modelos são escritos por ordem de nome, pelo que uma entrada idêntica produz um ficheiro idêntico byte a byte. O fornecedor não lê nada no corpo: não verifica o identificador e não sabe nada sobre o que irá servir o modelo.
  • A referência de um serviço mantém a sua forma. A forma curta lista nomes de modelos (models: [llm]); a forma longa mapeia cada modelo para endpoint_var e model_var, os nomes das variáveis que recebem o endereço do model runner e o identificador do modelo. Qualquer uma delas é escrita na forma e pela ordem que o fragmento usou, e viaja com o seu serviço. Quando a forma longa deixa uma variável sem nome, o Compose atribui-lhe um nome quando executa o ficheiro.
  • Os modelos unem-se dentro de um caminho de composição, segundo a regra que os volumes seguem. Dois contribuidores que declaram um mesmo nome de modelo com corpos que são emitidos de forma idêntica deixam uma única entrada sob ele; dois que o declaram com corpos diferentes interrompem a compilação com TRANSLATION_ERROR, indicando o modelo e cada tupla (boundary, node, fragment) contribuinte. Também aqui dois fragmentos de um mesmo componente são dois contribuidores. Torne idênticas as declarações quando ambos os contribuidores se referem a um único modelo, ou dê a uma delas um nome diferente.
  • Cada referência indica um modelo declarado. Depois de os fragmentos do caminho de composição serem unidos, um serviço ao qual é concedido um modelo que nenhum contribuidor nesse caminho declara interrompe a compilação com TRANSLATION_ERROR, indicando o serviço e o modelo. A verificação é executada sobre a união completa, pelo que um componente pode conceder ao seu serviço um modelo que outro componente no mesmo caminho de composição declara.
  • Uma entrada omits: não pode deixar um modelo de fora. service, volume e config são os tipos que este fornecedor aceita, e uma entrada que indique um modelo interrompe a compilação tal como uma que indique qualquer outro tipo.

Os modelos são servidos quando o ficheiro é executado, não durante a compilação. O Docker Compose 2.38 ou posterior, numa plataforma que suporte modelos do Compose como o Docker Model Runner, descarrega e executa cada modelo concedido a um serviço, deixando de fora qualquer outro, a menos que seja iniciado com --all-resources, e define, em cada serviço ao qual é concedido, as variáveis que a sua referência indica com o endereço do model runner e o identificador do modelo. A compilação não consegue ver o host que irá executar o ficheiro, pelo que não verifica nem a versão do Compose nem a plataforma: um ficheiro que transporta modelos é composto da mesma forma, seja o que for que o execute.

Uma Feature anexada a um componente contribui para o mesmo ficheiro

Uma Feature anexada a um componente contribui com os seus serviços para o docker-compose.yaml no qual o seu componente anfitrião é composto, nos mesmos termos que a própria Recipe do anfitrião. Não há um segundo ficheiro ao lado: um caminho de composição produz um único documento, pelo que os serviços de uma Feature anexada ou estão nesse documento ou não são de todo implementados. Desanexar a Feature remove exatamente esses serviços e deixa intactos os do próprio componente anfitrião.

São contribuidores nesse caminho de composição como quaisquer outros, pelo que tudo o que foi dito acima se aplica a eles sem alterações — a regra dos nomes de serviço, e a exigência de que dois contribuidores que declarem um mesmo nome de volume ou de configuração de nível superior concordem quanto ao que ele é. Também se juntam à mesma rede que o resto da fronteira, pelo que um componente e uma Feature anexada a ele se alcançam mutuamente pelo nome de serviço sem mais nada a declarar.

Cada serviço com que uma Feature contribui tem a identidade composta para esse anexo em vez da do componente anfitrião, para que os dois continuem distinguíveis dentro de um documento para o qual ambos contribuíram. Etiquetas e anotações explica como essa identidade é construída.

Este é um mecanismo diferente do bloco attachments: ao nível do contentor de um Workload, e é fácil ler os dois como um só porque partilham uma palavra. Anexar uma Feature a um componente acrescenta serviços ao documento composto; a entrada attachments: de um contentor lê uma credencial que um slot publicou nesse único contentor, e é abordada em Campos do contentor.

Fragmentos compose emitidos como artefactos

Quando o bloco artifacts: de uma Recipe é avaliado como YAML de compose — um fragmento que tem os seus próprios blocos services:, volumes:, configs:, models: ou networks: (cada entrada inline ou carregada por entrada através de $import:) —, a fusão na composição por (path, provider) segue regras específicas de cada forma:

  • Os services: de artefactos são fundidos no ficheiro compose composto ao lado dos serviços por componente. Um nome de serviço contribuído por dois componentes diferentes no mesmo caminho de composição interrompe a compilação, e o diagnóstico indica cada contribuidor. Uma colisão dentro de um único componente — entre o próprio fragmento de artefacto desse componente e os serviços sintetizados para ele — não é detetada, e a contribuição posterior substitui a anterior, pelo que convém manter o nome de um serviço escrito num artefacto distinto dos nomes <component> e <component>--<container-name> que o sintetizador produz (ver Como é nomeado um serviço sidecar ou de inicialização).
  • Os volumes: de artefactos são fundidos no bloco volumes: de nível superior. Duas entradas que chegam a um mesmo nome deixam uma única entrada sob ele quando o declaram de forma idêntica, segundo a mesma regra dos volumes por componente; duas que o declaram de forma diferente interrompem a compilação, quer venham de dois componentes quer de dois fragmentos de um mesmo componente — duas das suas entradas artifacts:, ou uma delas e o próprio ficheiro compose do componente. Como um fragmento de artefacto escreve os seus próprios corpos, esta é a via em que dois contribuidores têm mais probabilidade de discordar. Convém manter o nome de um volume escrito num artefacto distinto dos restantes no seu caminho de composição, incluindo da forma <component>--<volume-name> que a derivação produz — a menos que dois contribuidores se destinem a descrever um único volume partilhado, caso em que as suas declarações têm de coincidir.
  • Os configs: de artefactos são fundidos no bloco configs: de nível superior. É assim que o ficheiro por trás de um volume configmap chega à composição: o volume torna-se uma referência configs: ao nível do serviço que indica o configmap, e o fragmento de artefacto declara uma entrada com esse nome com content: inline. Depois de os fragmentos do caminho de composição serem unidos, cada referência ao nível do serviço tem de ser resolvida numa entrada declarada, caso contrário a compilação é interrompida com TRANSLATION_ERROR indicando cada referência não resolvida — o serviço, o nome da configuração e o caminho de montagem. A verificação é executada sobre a união completa e não por componente, pelo que um componente pode referenciar uma configuração que outro componente no mesmo caminho de composição declara. A união concilia-se por nome quando os contribuidores concordam: dois que declaram um mesmo nome de configuração com content: idêntico deixam a única entrada que ambos descreveram. Dois que declaram um mesmo nome com content: diferente interrompem a compilação com TRANSLATION_ERROR, indicando a configuração e cada tuplo (boundary, node, fragment) contribuinte, incluindo dois fragmentos de um mesmo componente — uma entrada de configuração tem sempre conteúdo, pelo que manter qualquer uma das declarações descartaria um ficheiro que um autor escreveu. Convém manter um nome de configuração distinto entre todos os contribuidores do seu caminho de composição, ou tornar as declarações idênticas quando dois contribuidores se destinam a entregar um único ficheiro partilhado.
  • Os models: de artefactos são fundidos no bloco models: de nível superior, e a referência models: de um serviço acompanha o seu serviço, segundo as regras em Modelos: dois contribuidores que declaram um mesmo nome de modelo têm de o declarar de forma idêntica, e cada referência tem de indicar um modelo que algum contribuidor no caminho de composição declare.
  • Os networks: de artefactos são recusados. O fornecedor compose deriva as redes das anotações da fronteira (uma rede por cada anotação aggrega.ai/namespace distinta, mais uma com o nome do caminho do ficheiro compose, à qual se junta cada nó que não tem nenhuma, cada uma nomeada segundo Como é derivado um nome de rede), pelo que uma declaração de rede fornecida por um artefacto não tem lugar no ficheiro composto: qualquer entrada interrompe a compilação, indicando a entrada e o fragmento, segundo as regras em Cada chave que um fragmento escreve é transportada ou recusada. Remova a entrada e molde as redes através da anotação aggrega.ai/namespace, ou faça com que um serviço se junte às redes de componentes indicados através de x-aggrega-networks-of; os autores que precisam de encaminhamento entre redes dentro de um único ficheiro compose usam a Feature compose-bridge.
  • Os membros de extensão de artefactos são transportados. Uma chave x- de nível superior é escrita depois das outras secções do ficheiro composto, pela ordem em que foi escrita, segundo as regras em Os membros de extensão são transportados tal como foram escritos.
  • Qualquer outra chave de nível superior de artefactos interrompe a compilação. services:, volumes:, configs:, models: e os membros de extensão são tudo o que o montador transporta de um fragmento. Um bloco secrets: e um name: de nível superior interrompem cada um a compilação indicando a chave e o fragmento, segundo as regras em Cada chave que um fragmento escreve é transportada ou recusada.
  • Um corpo artifacts: é um único documento. Um corpo que contém vários documentos YAML interrompe a compilação indicando o fragmento e quantos documentos contém; dê a cada documento uma entrada artifacts: própria.

A assimetria entre os quatro primeiros e networks: é estrutural: services:, volumes:, configs: e models: transportam conteúdo por Recipe que o montador acumula no ficheiro composto; networks: é infraestrutura por fronteira que o montador deriva do estado da fronteira. Os artefactos podem estender os primeiros; só as anotações da fronteira podem moldar a segunda, e é por isso que a entrada de rede própria de um artefacto é recusada. Os membros de extensão são dados que a Compose Specification define para outras ferramentas, pelo que são transportados tal como foram escritos. Tudo o resto é uma forma para a qual o documento composto não tem lugar, e é por isso que é recusado em vez de fundido.

O que o fornecedor compose não entrega

  • Encaminhamento L4 entre redes dentro de um ficheiro compose. O fornecedor posiciona cada nó na sua rede e junta um serviço às redes que x-aggrega-networks-of indica, e não encaminha nada entre redes por si próprio. Um serviço na rede A que chega a um serviço na rede B por qualquer meio que não o DNS predefinido do docker-compose requer a Feature compose-bridge, cuja FeatureRecipe escreve o gateway e a reescrita.
  • Encaminhamento entre ficheiros compose. As fronteiras que são avaliadas para caminhos de composição distintos produzem ficheiros docker-compose.yaml distintos; o runtime do compose trata-os como projetos independentes, e a Feature compose-bridge deixa uma conexão entre dois ficheiros tal como foi escrita. A comunicação entre ficheiros é assunto do operador (publicar portas do host, partilhar redes externas ou fazer convergir as fronteiras num único caminho através de um directory: partilhado).
  • Obter uma variável de ambiente a partir de um anexo. O Compose não tem uma primitiva para isso, pelo que uma entrada attachments de um Workload com as: env emite o nome da variável com um valor vazio em vez de uma referência resolvida em tempo de execução. O marcador de posição é deliberado — uma variável presente mas vazia é visível para quem depura o contentor, ao passo que uma ausente não deixa nada para examinar — e a compilação assinala-o em vez de deixar que seja descoberto: cada entrada deste tipo gera um aviso unsupported-field que indica a entrada na sua coordenada de autoria (containers.<name>.attachments.<KEY>, ou initContainers[<i>].attachments.<KEY>), para que o autor saiba que variável chega vazia e a que contentor pertence. O aviso é consultivo: a compilação é bem-sucedida, e o ficheiro renderizado é byte a byte o que seria sem ele. --no-unsupported-field-warnings silencia a classe. Uma entrada attachments com as: file não é afetada — o compose monta-a como bind mount, e nenhum aviso é gerado.
  • Conteúdo deploy: do modo swarm. As réplicas, as restrições de posicionamento e a estratégia de atualização sob deploy: são funcionalidades do modo swarm, e o fornecedor compose visa apenas o compose num único host, pelo que não emite nenhuma delas. Emite, no entanto, deploy.resources — as reservas e os limites a que correspondem os resources de um contentor, que o docker compose respeita fora do modo swarm (consulte Recursos dos contentores).
  • depends_on condicionado ao estado de saúde a partir de uma aresta uses. Uma dependência derivada de uma aresta uses é emitida sem condição, com a semântica service_started; não está condicionada a que o healthcheck do destino reporte estar saudável. Isto diz respeito ao que uma aresta uses significa, e não a uma forma que o fornecedor não consiga produzir: a forma longa é emitida para a espera de um contentor de inicialização, e uma wave de implementação condiciona de facto a espera à saúde do destino quando o destino declara um healthcheck.

Exemplo de autoria

Uma implementação compose de dois serviços com uma aresta depends_on derivada de uses:

# release.yaml fragment
spec:
boundaries:
production:
annotations:
aggrega.ai/namespace: prod
components:
api: {}
db: {}
# api Recipe
apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: api
version: 1.0.0
spec:
capability: compose
implements: example/compute/api:1.0.0
workload: |
apiVersion: aggrega.ai/v1beta1
kind: Workload
containers:
main:
image: api:1.0
ports:
http: 8080
health:
live:
http: /healthz
services:
public:
type: NodePort
ports:
http: 8080
# Aggregate fragment — api uses db, on a socket api's Component declares
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
spec:
components:
api:
type: example/compute/api:1.0.0
uses:
backend:
db:
target: db
db:
type: example/datastore/db:1.0.0

O fornecedor compose produz um único docker-compose.yaml no caminho avaliado da fronteira (por predefinição dist/boundaries/production/compose/docker-compose.yaml, porque o directory: de uma fronteira tem como predefinição dist/boundaries/<name> e subDirectory:, {{ .capability }}) que contém:

  • services.api (o serviço api principal, rede prod, portas 8080:8080, healthcheck através de curl, depends_on: [db])
  • services.db (o serviço db principal, rede prod)
  • networks.prod (a rede docker da fronteira)