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

Provider Compose

O provedor compose renderiza Recipes do Aggrega em um arquivo Docker Compose. O provedor monta por (path, provider): os contribuidores compose de cada fronteira são roteados para o montador indexado pelo directory: avaliado da fronteira unido ao subDirectory: de cada componente, e esse montador emite um único docker-compose.yaml contendo todos os contribuidores naquele caminho. Duas fronteiras irmãs que são avaliadas para o mesmo caminho se fundem em um único arquivo compose mesclado — o exemplo canônico é uma fronteira pai mais duas fronteiras filhas com directory: "{{ .parent_boundary.directory }}" (o padrão compose-bridge).

Tipos de entrada suportados

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

  • Modo proveniente de uma fonte. Uma Recipe com source: apontando para um arquivo compose existente mais valuesMapping: produzindo um documento de sobreposição. O arquivo compose base é carregado, a sobreposição é avaliada, e os dois são mesclados em profundidade conforme a semântica de sobreposição nativa do docker-compose.
  • Modo Workload. Uma Recipe com workload: (inline ou carregado via $import:) declara um documento Workload. O provedor sintetiza um ou mais serviços compose a partir da especificação do Workload.
  • Modo de artefatos. As entradas artifacts: de uma Recipe são avaliadas como fragmentos compose, que se mesclam ao arquivo montado segundo as regras em Fragmentos compose emitidos como artefatos. Artefatos podem acompanhar uma fonte ou um Workload, e também podem ser a saída inteira de uma Recipe: uma Recipe que declara artifacts: e nem source: nem workload: é renderizada aqui, contribuindo com o que quer que seus fragmentos declarem. É assim que um componente composto apenas de recursos — um conjunto compartilhado de rede e volumes, uma config pré-carregada — chega a uma implantação compose sem um Workload de fachada fazendo as vezes de uma capacidade de computação que ele não tem.

Os três tipos se combinam 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 provedor que ela nomeia: não há nada a que aplicar a sobreposição, e o diagnóstico pede que você declare o ponteiro source: ou remova o valuesMapping:.

Mapeamento de funcionalidades do Workload

Quando uma Recipe declara workload:, o provedor traduz a forma de Workload controlada 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 são degradadas para o equivalente compose mais próximo, com perda documentada.

Campos do contêiner

Campo do WorkloadCampo do Compose
imageimage
imagePullPolicy: Always / IfNotPresent / Neverpull_policy: always / if_not_present / never
commandentrypoint (forma de lista) — sobrescreve 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 sobrescreve
variablesenvironment (forma de mapa)
attachments[as: env]entrada de environment com valor vazio, e um aviso que nomeia a entrada (veja O que o provedor compose não entrega)
attachments[as: file]bind-mount de volumes na forma longa, somente leitura
volumeMountsa primitiva compose para a qual a variante de volume referenciada é mapeada — uma entrada volumes na forma longa, uma entrada tmpfs: no nível do serviço ou uma referência configs: no nível do serviço (veja Volumes)
portsimplícito (os contêineres 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 para o único mapa environment, primeiro as entradas das vinculações e depois as variables, cada uma na ordem em que é escrita — a ordem que o provedor helm escreve, de modo 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, então no compose essa ordem não tem nenhum significado em tempo de execução. Como o mapa contém cada nome uma única vez, um contêiner que dá um mesmo nome tanto como entrada de variables quanto como entrada de attachments entregue as: env interrompe o build em vez de manter um dos dois valores (veja A container gives one environment variable two values (Um contêiner dá dois valores a uma mesma variável de ambiente)).

Recursos de contêiner

Os resources de um contêiner chegam ao bloco deploy.resources do compose, que o docker compose respeita no modo não swarm. As requests do Kubernetes expressam um mínimo garantido, então se tornam reservations do compose; os limits expressam um teto rígido, então continuam 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 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.cpusMesma conversão
resources.requests.memorydeploy.resources.reservations.memoryUma contagem exata de bytes, convertida a partir do valor em qualquer forma em que ele esteja escrito — 8Gi se torna 8589934592, 1.5Gi se torna 1610612736, 1e3 se torna 1000
resources.limits.memorydeploy.resources.limits.memoryMesma conversão
nvidia.com/gpu, sob resources.limits, resources.requests ou ambosdeploy.resources.reservations.devicesUma entrada de dispositivo NVIDIA no serviço do contêiner — driver: nvidia, count: a contagem de GPUs, capabilities: [gpu]. A contagem é a do limite onde um limite é escrito — a contagem que o Kubernetes agenda para um recurso estendido — e a da solicitação 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 todo outro <domain>/<name>—Sem análogo compose em um único host. A chave é descartada e o build gera um aviso unsupported-field que a nomeia, um por chave distinta, independentemente de quantas das requests e dos limits a traziam. Seu valor não é emitido, então 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 coisas interrompem o build com um TRANSLATION_ERROR, e o erro diz qual das duas encontrou, nomeando o caminho do contêiner, se o valor é uma solicitação 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 que 9223372036854775807 bytes (8Ei); um valor de cpu mais fino que nove casas decimais de um núcleo, a precisão mais fina que a própria quantidade do Kubernetes mantém, ou maior que 9223372036.854775807 núcleos; uma contagem de GPUs que não é um número inteiro de dispositivos (0.5, 500m).

Um contêiner cuja solicitação e cujo limite de nvidia.com/gpu pedem contagens diferentes interrompe o build da mesma forma, nomeando os dois caminhos: o compose reserva uma única contagem para um serviço, então a tradução teria de escolher uma. Escreva a mesma contagem nos dois, ou apenas o limite.

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

Uma solicitação de GPU reserva GPUs NVIDIA. Um contêiner de Workload que pede nvidia.com/gpu: "1" é renderizado como um serviço que traz esta reserva, ao lado de quaisquer cpus e memory que suas solicitações reservem:

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

O Docker Compose entrega as GPUs reservadas ao contêiner quando o host Docker tem essa quantidade de GPUs NVIDIA e está configurado para fornecê-las aos contêineres; o build não consegue ver o host, então um arquivo que reserva GPUs é montado da mesma forma onde quer que vá ser executado. A entrada sempre informa sua contagem, porque o Compose lê uma entrada de dispositivo sem contagem como todas as GPUs do host. Apenas a chave NVIDIA é traduzida: amd.com/gpu e a chave de qualquer outro fabricante mantêm o aviso da linha de chaves descartadas. A linha runtimeClassName em Campos no nível do pod não muda — o compose não tem análogo de runtime class, então um Workload que nomeia um runtime com suporte a GPU é informado de que o runtime foi omitido, enquanto sua contagem de GPUs é reservada.

Probes

Os três slots de probe de um Workload (live, ready, startup) se reduzem ao único healthcheck por serviço do compose, com prioridade live > ready > startup (vence o sinal de liveness mais canônico). Onde essa redução descarta um slot que o autor declarou, o build gera 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 é relatada em vez de perdida. Um bloco health que declara um único slot é traduzido sem perda e não gera nada, a menos que o slot defina successThreshold: um healthcheck do compose não tem campo para isso, então um valor escrito pelo autor — 1 incluído — é omitido com um aviso unsupported-field que o nomeia (containers.<name>.health.<slot>.successThreshold), e o restante 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 contêiner declare pelo menos uma porta nomeada; o sintetizador escolhe o primeiro nome de porta em ordem alfabética e usa seu número para construir a URL do curl. Contêineres sem portas declaradas não podem usar probes HTTP — o compilador é interrompido com um TRANSLATION_ERROR que nomeia a probe em questão.

Os campos de timeout das probes são mapeados para strings de duração no estilo 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. Ele não tem um equivalente do Kubernetes para Secret nem para templates de volume por réplica, então essas variantes são degradadas para a primitiva do compose mais próxima:

Variante de volume do WorkloadTradução do ComposeNotas sobre perdas
ephemeralentrada de lista tmpfs: no 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 nomeia na sua coordenada de autoria (volumes.<name>.ephemeral.sizeLimit), quer um contêiner monte o volume, quer não; omitir o campo não gera nada
configmapreferência configs: no nível do serviço que nomeia o configmap, montado no caminho da montagem do volume🔴 O caminho de montagem é o caminho de um único arquivo, não de um diretório. O Compose escreve o conteúdo da config exatamente no caminho de destino, enquanto um destino Kubernetes que monta um ConfigMap em um caminho produz um diretório contendo um arquivo por chave. Assim, o mesmo path: escrito denota aqui um arquivo e lá um diretório: aponte a montagem de um volume configmap para o nome do arquivo que o contêiner deve ler (/seed/config.json), não para o diretório que o conteria, e uma Recipe escrita para os dois destinos leva um caminho diferente para cada destino. Nada no build consegue detectar um caminho escrito para a forma do outro destino — o caminho é uma string opaca que o compilador repassa sem interpretar, e a saída emitida é válida nos dois casos. A referência é 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 do compose a declara com content: inline; uma referência sem essa entrada interrompe o build (veja Fragmentos compose emitidos como artefatos). Uma referência configs: leva o nome da config e o caminho de montagem e nada mais, então o readOnly da montagem não tem expressão própria
secretbind-mount de volumes na forma longa, somente leituraUm volume de secret deliberadamente não segue a tradução configmap: uma entrada configs: inline escreveria o valor do secret em texto puro no arquivo compose emitido, e o compilador nunca resolve um secret em texto puro — um secret continua sendo um ponteiro em todas as etapas do build. A origem do bind é o nome source do secret, resolvido como um caminho que o operador torna acessível no host do compose independentemente do build
persistentvolume nomeado + declaração volumes: { <volume-name>: {} } de nível superior, nomeado conforme Como um nome de volume é derivadoStorage class, modos de acesso e 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 nomeia 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 — veja abaixo
persistentTemplatevolume nomeado + declaração de nível superior, nomeado da mesma forma (igual a persistent)Complemento de form: stateful; o compose não tem primitiva de templates de volume por réplica, então o comportamento por réplica se perde, e um aviso unsupported-field informa que o volume se tornou um único volume que todas as réplicas compartilham. Storage class, modos de acesso e 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 nomeia um volume persistent ou persistentTemplate com subPath se torna uma entrada volumes em forma longa que leva volume.subpath, de modo que a montagem vê o diretório ou arquivo nomeado 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 leva nenhum bloco volume:. Um subPath em uma montagem de um volume ephemeral, configmap ou secret interrompe o build com um erro TRANSLATION_ERROR que nomeia o componente, o contêiner, 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 do que entrega, então, de outra forma, a montagem veria o volume inteiro. Remova subPath de uma montagem assim, ou monte um volume persistent. O Docker Compose lê volume.subpath a partir da versão 2.26.0, no Docker Engine 26.0 ou posterior; o build não consegue ver o host que vai executar o arquivo, então um arquivo que leve um é composto da mesma forma onde quer que vá ser executado.

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

Três variantes levam um tamanho de armazenamento, e só uma delas avisa que o tamanho foi descartado. A diferença está em se você teve escolha. O sizeLimit de um volume ephemeral é opcional, então escrevê-lo foi uma decisão, e o aviso diz que o valor não molda nada neste destino e pode ser removido — ele é consultivo e fora de banda, o arquivo emitido é byte a byte o que seria sem ele, e --no-unsupported-field-warnings o silencia junto com o resto da classe. O size de um volume persistent ou persistentTemplate é obrigatório, então nenhuma versão do documento o omite: um aviso a cada build dispararia ali em toda carga de trabalho com estado sem nomear nada que você pudesse mudar, por isso a diferença é explicada aqui em vez de relatada a cada build. Tendo o compose como destino, size, class e accessModes de um volume persistente não moldam nada no arquivo emitido — o que você obtém é um volume nomeado simples, dimensionado e sustentado pelo que o driver de volume do host do compose fizer por padrão. class e accessModes são opcionais, então cada um que você escrever é relatado como o sizeLimit de um volume ephemeral: um aviso unsupported-field por campo, consultivo e fora de banda, silenciado pela mesma flag. Dimensione o armazenamento subjacente no host, ou no destino Kubernetes, onde os campos de fato chegam à saída.

Um volume que nenhum contêiner monta gera um aviso unsupported-field que o nomeia na sua coordenada de autoria (volumes.<name>), porque o que chega ao arquivo emitido difere então bastante conforme a variante. persistent e persistentTemplate ainda produzem a sua declaração de nível superior, então o volume é criado e nada o usa. ephemeral, configmap e secret não têm expressão fora da própria montagem — cada um se traduz em algo escrito no caminho de montagem, respectivamente uma entrada tmpfs, uma referência configs ou uma montagem bind —, então, sem nada montando um deles, o volume que você declarou não deixa nenhum rastro na saída. Esse segundo caso é a razão de o aviso existir: sem ele, um volume configmap cuja montagem você esqueceu estaria simplesmente ausente, sem nada no arquivo emitido para notar. Todo contêiner da carga de trabalho conta como contêiner que monta o volume, incluindo os contêineres de inicialização, então um volume montado só por um contêiner de inicialização está conectado e não gera nada. O aviso é consultivo e fora de banda — o arquivo emitido é byte a byte o que seria sem ele — e --no-unsupported-field-warnings silencia a classe.

Como um nome de volume é derivado

Um volume persistent ou persistentTemplate se torna um volume nomeado do compose: uma entrada volumes: de nível superior, referenciada por todo contêiner que o monta. Um volume do compose é armazenamento compartilhado, e o bloco volumes: de nível superior une as suas entradas pelo nome — então dois volumes escritos que chegam a um mesmo nome se tornam um só volume no qual os dois contêineres escrevem, sem nada no arquivo emitido que mostre que eram pretendidos dois. Por isso o nome é construído a partir das duas identidades que juntas dizem de qual volume se trata: o <component> ao qual o volume pertence, e o nome que o Workload deu ao volume em volumes:.

Um nome de volume do compose aceita um conjunto de caracteres mais restrito do que qualquer uma das identidades pode conter: letras, dígitos, pontos, sublinhados e hifens. Em vez de substituir um caractere que o compose não aceita, a derivação o escreve por extenso, de modo que dois volumes que diferem em qualquer coisa 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 como foi escrito sempre que o caractere depois dele é mantido diretamente e não é um z minúsculo. Um hífen seguido de um z minúsculo abre uma sequência de escape, então um hífen escrito nessa posição é ele próprio escrito por extenso — api-zone se torna api-zhzone, que é o que permite ler qualquer nome de volta sem adivinhar. Um hífen sem nada depois dele é escrito por extenso pelo mesmo motivo, então db- dá db-zh.
  • Todo outro caractere é escrito como -z seguido de uma letra que o nomeia: s para um separador de caminho, h para um hífen que a regra acima não mantém. Qualquer outra coisa — incluindo um espaço e uma letra não ASCII — é escrita como x seguido do ponto de código hexadecimal de seis dígitos do caractere, e um byte que não inicia nenhum caractere como b seguido do seu próprio valor de dois dígitos, de modo que um nome que não é texto válido ainda é escrito por extenso de forma distinta em vez de ser confundido 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, então o nome unido diz sem ambiguidade onde uma identidade termina e a outra começa.

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

A junção dupla é o que torna o par inequívoco, e uma junção de um só caractere não consegue isso. Qualquer uma das identidades pode ela própria conter um hífen, então 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 resultariam ambos em db-data-cache, e como o bloco de nível superior une pelo nome, os dois componentes compartilhariam um só volume sem nada no arquivo emitido que o mostrasse. Uma identidade codificada nunca contém um par de hifens, então a junção dupla não admite uma segunda leitura: os dois chegam a db--data-cache e db-data--cache.

Mudar qualquer uma das identidades renomeia o volume do compose, e o compose não renomeia um volume no lugar. O volume é criado do zero com o novo nome enquanto o antigo fica para trás com os dados dentro, então o contêiner sobe com um armazenamento vazio e o conteúdo fica em um volume que nada monta. Renomeie qualquer uma das identidades apenas como uma substituição a ser planejada — com backup, cópia dos dados ou agendamento — e não como uma mudança a ser simplesmente implantada.

Forma de controlador

O form do Workload seleciona uma forma abstrata de controlador (veja entities/workload.md). O Compose renderiza stateless e stateful (e o padrão vazio, tratado como stateless) como serviços de longa duração; a forma stateful adiciona o volume nomeado para um complemento persistentTemplate. As formas daemon, scheduled e task não têm um mapeamento limpo para compose em um único host, então um Workload que declara uma delas tendo como destino uma fronteira compose interrompe o build com um erro TRANSLATION_ERROR que nomeia a forma e o conjunto suportado — o compose não degrada uma forma não suportada em um serviço simples que deturpa a intenção. Um Workload reference declara um endpoint externo e nenhum contêiner, então 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 vinculada a esse componente — entregue no seu pipe por dotenv-secret, ou pelo próprio bloco inject: de uma vinculação — não chegaria a nenhum arquivo emitido. Por isso, toda Recipe de Compose da biblioteca padrão que realiza dessa forma um serviço externo, e cujo Component declara um slot de credencial, recusa uma credencial que preencha esse slot: o build é interrompido nomeando o slot e o componente, em vez de ter sucesso sem a credencial. No compose, uma credencial para um serviço externo é vinculada 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 que este provedor renderize qualquer coisa. Este provedor também recusa no próprio nó, seja qual for o catálogo de onde vem a Recipe: uma vinculação em um nó reference cujo material é declarado sensível — a sua Feature declara um campo sensitive: true, ou o slot que ela preenche o faz — interrompe o build com TRANSLATION_ERROR (E0288), nomeando o nó e cada vinculação desse tipo, quer algum slot declare ou não o nome sob o qual ela está vinculada. Uma vinculação que não leva nada declarado sensível não é recusada aqui. Esses Components declaram opcionais os seus slots de credencial, então, no compose, um slot deixado vazio não interrompe nada. Onde a realização do Kubernetes precisa da credencial — as Recipes helm de twilio, vonage, telnyx, bland, letta, retell e vapi —, essa Recipe exige o slot em vez disso, e interrompe o build nomeando-o quando ele está vazio.

Exposição de serviços

O campo type de uma entrada services do Workload decide se o compose publica portas, e em qual 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 balanceador de carga gerenciado; a publicação em uma 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:

Qual número vai em qual lado. Uma entrada de serviço nomeia uma porta de contêiner e lhe dá um número, assim como um Service do 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 contêiner para a qual o nome é resolvido é o lado <container>. Assim, um contêiner que declara http: 8080 e uma entrada NodePort que escreve http: 8081 publicam 8081:8080: a porta 8081 do host alcança a porta em que o contêiner atende. Uma entrada que leva o próprio número da porta de contêiner publica esse número dos dois lados, 8080:8080. Um par na rede do compose alcança o serviço pelo seu nome de serviço na porta do contêiner, nunca na publicada — a porta publicada pertence ao host —, então uma Recipe que publica uma porta de sua escolha ainda entrega aos seus consumidores a porta do contêiner.

Uma entrada Loopback se vincula apenas ao endereço de loopback IPv4. O endereço de loopback IPv6 ::1 não é vinculado: a sintaxe de portas do compose leva um único endereço de host por entrada, e um host cuja interface de loopback não tem endereço IPv6 não conseguiria vinculá-lo, então o serviço não iniciaria ali. Os clientes no host alcançam a porta em 127.0.0.1.

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

Transporte das portas. Uma entrada publicada leva o transporte declarado na porta de contêiner que ela nomeia, 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 declara nenhum transporte é publicada como <host>:<container> sem sufixo, deixando em vigor o padrão do próprio compose. O Compose grafa o transporte de uma porta publicada como tcp ou udp; uma porta que declara SCTP não tem grafia no compose, então interrompe o build com um erro TRANSLATION_ERROR em vez de publicar uma porta que levaria um transporte diferente. Uma porta de contêiner que nenhum serviço publica não chega a nenhuma parte do arquivo compose, então um transporte declarado em uma porta assim não tem onde ser escrito e não interrompe o build.

Workloads com vários contêineres

Um Workload com vários contêineres se torna um serviço principal mais um serviço sidecar para cada contêiner não principal. O contêiner principal é o chamado main (quando presente) ou o primeiro contêiner na ordem de declaração. Os sidecars compartilham o namespace de rede do serviço principal via network_mode: "service:<main>" — a primitiva do compose mais próxima do modelo de rede compartilhada de um pod do Kubernetes.

Como um serviço sidecar ou de init é nomeado

O serviço principal carrega o nome <component> tal como é. Todos os outros serviços que o Workload produz — um por sidecar e um por contêiner de init — são nomeados a partir de duas identidades juntas: o <component> e o nome do contêiner, que é sua chave em containers: para um sidecar e seu name para um contêiner de init, ou o init-<index> posicional que uma entrada de init sem nome recebe. O bloco services: montado contém um serviço por nome, então o nome é construído de forma que dois contêineres que diferem em qualquer uma das identidades sempre cheguem a dois nomes.

Cada identidade é escrita exatamente como as duas partes de um nome de volume são — uma letra, um dígito, um ponto e um sublinhado como foram escritos, um hífen mantido onde as regras de lá 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 o executa como api--logger, o contêiner 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 contêiner com um caractere que um nome de serviço não admite é reescrito em vez de emitido como foi escrito: um contêiner de init chamado warm cache/x de api é executado como api--warm-zx000020cache-zsx.

A junção dupla mantém separados os contêineres de dois componentes. api com um contêiner warm-cache e api-warm com um contêiner 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.

Sidecars e contêineres de init compartilham esta única nomeação, então uma entrada de containers e uma entrada de initContainers com o mesmo nome chegam ao mesmo nome de serviço, e o build é interrompido diante do par em vez de executar um contêiner no lugar do outro (veja Contêineres de inicialização).

O serviço do próprio componente não recebe um desses nomes. O serviço principal recebe o nome do componente, e um hífen duplo escrito no nome de um componente é ele próprio reescrito ali — um componente chamado api--prep é executado como api-zh-prep — de modo que ele nunca carrega a junção --. Onde serviços de dois componentes diferentes ainda coincidem em um nome em um mesmo arquivo compose — por meio de um serviço que um artefato nomeia para si, por exemplo — o build é interrompido nomeando ambos, como descreve Saída por (path, provider).

Alterar o nome do componente ou o nome do contêiner renomeia o serviço. O Compose trata um serviço com um novo nome como um novo serviço, então seu contêiner é criado do zero com o novo nome.

Campos no nível do pod

Os campos do Workload no nível do pod se aplicam apenas ao serviço principal — os sidecars compartilham o namespace de rede do serviço principal — e um serviço de inicialização segue a mesma regra. A única exceção é o usuário do pod: um pod executa cada um dos seus contêineres como podSecurityContext.runAsUser e runAsGroup, então eles chegam a todo serviço que o Workload produz, incluindo os serviços sidecar e de inicialização.

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

Campo do WorkloadCampo do Compose
podSecurityContext.runAsUser / runAsGroupuser ("1000", ou 1000:3000 com um grupo) em todo serviço do Workload. Um contêiner que define o seu próprio securityContext.runAsUser é executado, em vez disso, como esse usuário no seu próprio serviço, com o seu próprio runAsGroup onde define um
terminationGracePeriodSecondsstop_grace_period: <n>s
dnsConfig.nameservers / dnsConfig.searchesdns / dns_search
hostAliasesuma entrada extra_hosts por nome de host, na ordem do autor
hostNetwork: truenetwork_mode: host

Execução na rede do nó. Uma carga de trabalho que declara 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 declara tanto networks: quanto network_mode:, então os dois são alternativas e não adições. A consequência prática é a que a rede do host sempre traz — os pares não alcançam mais o serviço pelo seu nome de serviço do compose nessa rede, porque ele não está mais nela; eles o alcançam nos próprios endereços do host, que é o que a declaração pediu. Nenhum outro serviço da fronteira é afetado.

Duas formas se combinam com isso. Um sidecar continua nomeando o serviço principal (network_mode: "service:<main>"), então segue o serviço principal para a rede do host sem declarar nada ele mesmo — da mesma forma que os contêineres de um pod do Kubernetes compartilham um único namespace. Um serviço de inicialização não: ele entra na rede da fronteira por direito próprio, porque compartilhar 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 ao mesmo tempo executa o seu próprio serviço na rede do host enquanto os seus serviços de inicialização ficam na rede da fronteira, o que é mais restrito do que a forma de pod que ela modela; um aviso unsupported-field nomeia essa diferença em vez de deixar que ela seja descoberta em tempo de execução.

O restante não tem equivalente em um único host. Nenhum é descartado em silêncio: cada um que é escrito gera um aviso unsupported-field que nomeia o campo, para que um autor saiba qual configuração o destino não conseguiu respeitar em vez de descobrir isso pelo stack em execução.

Campo do WorkloadPor que o compose não consegue respeitá-lo
schedulingO posicionamento — nodeSelector, affinity, tolerations, topologySpreadConstraints — pressupõe um escalonador que escolhe entre nós. O Compose é executado em um único host
replicasA contagem de réplicas própria do compose fica em deploy: e é uma funcionalidade do modo swarm
runtimeClassNameSelecionar um runtime de contêiner alternativo — um habilitado para GPU, por exemplo — não tem expressão no compose
priorityClassNameA ordenação por preempção pressupõe um escalonador
serviceAccountA identidade de Workload é um conceito de cluster
imagePullSecretsAs credenciais de registro em um host do compose são o estado de login próprio do host, não um campo do arquivo
dnsPolicy, dnsConfig.optionsO Compose expõe dns e dns_search e nada mais refinado
podSecurityContext.fsGroup, podSecurityContext.supplementalGroupsuser leva um usuário 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, onde o pod não define nenhum runAsUser, ou onde um contêiner — principal, sidecar ou de inicialização — define o seu próprio runAsUser e nenhum runAsGroupuser nomeia um grupo apenas ao lado de um usuário, e o usuário próprio de um contêiner toma o lugar do usuário do pod, então o grupo do pod não chega a nenhum serviço escrito dessa forma

O securityContext no nível do contêiner é traduzido parcialmente: readOnlyRootFilesystem → read_only, capabilities.add / drop → cap_add / cap_drop, runAsUser / runAsGroup → user. runAsNonRoot e allowPrivilegeEscalation não têm expressão no compose e geram o mesmo aviso unsupported-field, assim como um runAsGroup de contêiner escrito sem um runAsUser ao lado: o serviço é então executado como o usuário do pod onde o pod define um, sem esse grupo.

Todo aviso desta seção é consultivo e fora de banda: o build é bem-sucedido, e o arquivo emitido é byte a byte o que seria sem ele. --no-unsupported-field-warnings silencia a classe.

Contêineres de inicialização

As entradas initContainers de um Workload se tornam serviços próprios, usando a expressão idiomática de execução até a conclusão do compose. Cada entrada adiciona 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 omite 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 contêineres de inicialização são executados até a conclusão na ordem em que foram escritos, e todo outro contêiner só inicia depois que todos eles terminaram — é expressa com a forma longa de depends_on:

  • Cada serviço de inicialização depois do 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 leva restart: "no". Um serviço de inicialização é executado uma vez; um serviço que voltasse a subir nunca chegaria ao estado concluído pelo qual os seus dependentes esperam, então uma restartPolicy escrita em um contêiner de inicialização não muda isso.
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 contêiner de inicialização é traduzido exatamente como qualquer outro contêiner: o seu image (incluindo a reescrita de registro 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 a configuração que um contêiner de inicialização leva — na maioria das vezes um arquivo que ele monta e escreve em um volume que o contêiner principal também monta — sobreviver no destino compose em vez de se perder com o contêiner. Uma forma que o compose não consegue expressar falha da mesma maneira para um contêiner de inicialização e para um comum: um lifecycle ou envFrom declarado interrompe o build com um erro TRANSLATION_ERROR que nomeia o contêiner 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 no nível do pod não são aplicados, a mesma regra que os sidecars seguem — exceto o usuário do pod, que chega a todo serviço como Campos no nível do pod descreve.
  • Um serviço de inicialização entra diretamente na rede da sua fronteira em vez de compartilhar o namespace de rede do serviço principal como um sidecar faz. Ele precisa fazer isso: o serviço principal espera pelo serviço de inicialização, e compartilhar um namespace é em si uma dependência do serviço principal, o que fecharia a espera em um ciclo que o compose se recusa a iniciar. Por isso, um contêiner de inicialização alcança outros serviços na rede da fronteira pelo nome de serviço, mas não compartilha o localhost do serviço principal.

Os serviços de inicialização e os serviços sidecar compartilham um único espaço de nomes, porque uma única nomenclatura nomeia ambos, então uma entrada initContainers e uma entrada containers não podem levar o mesmo nome. Quando levam, o compilador é interrompido com um TRANSLATION_ERROR que nomeia o nó, o nome do contêiner e o nome de serviço que ambos queriam, em vez de deixar um serviço substituir 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 base — ao contrário dos campos restart e required ao lado deles no mesmo bloco de forma longa, que a especificação associa a versões específicas do Compose. Cada versão mínima que a saída do provedor compose pede vem com a construção que precisa dela: ≥ 2.23.1 para configs.content inline, ≥ 2.26.0 para o subPath de uma montagem (veja Volumes), e 2.38 para modelos. A primeira alcança qualquer saída do compose que leve uma config com content: inline, que é como chegam tanto o arquivo por trás de um volume configmap quanto a config por trás de uma aresta entre redes com ponte — não um único caminho de autoria.

Em qual rede um serviço entra

Todo serviço entra em uma rede do Docker; os sidecars a herdam por meio 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 arquivo compose onde o nó não leva essa anotação — o diretório em que o arquivo é escrito sob o diretório de saída do build, como bridge/compose para uma fronteira cujo directory: é bridge. Assim, todo nó sem a anotação em um arquivo compose entra em uma única rede nomeada pelo caminho do arquivo, seja qual for a fronteira em que está: fronteiras sem anotação que compartilham um arquivo compose compartilham essa rede, e aggrega.ai/namespace é o que as separa. Nós que levam anotações diferentes ficam em uma rede por anotação distinta. Como um nome de rede é derivado é o nome que essa identidade produz.

Como um nome de rede é derivado

Uma rede do compose é conectividade L3 compartilhada, e o bloco networks: de nível superior une as suas entradas pelo nome — então duas identidades que chegam a um mesmo nome se tornam uma só rede na qual ficam os dois conjuntos de serviços, alcançando-se pelo nome de serviço, sem nada no arquivo emitido que mostre que eram pretendidas duas redes. Por isso o nome é construído a partir da identidade que diz de qual rede se trata: a anotação aggrega.ai/namespace do nó, ou o caminho do arquivo compose onde o nó não leva nenhuma.

Um nome de rede do compose aceita um conjunto de caracteres mais restrito do que qualquer uma das identidades pode conter: letras, dígitos, pontos, sublinhados e hifens. Em vez de substituir um caractere que o compose não aceita, a derivação o escreve por extenso, de modo que duas identidades que diferem em qualquer coisa 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, não uma.
  • Um hífen é mantido como foi escrito sempre que o caractere depois dele é mantido diretamente e não é um z minúsculo. Um hífen seguido de um z minúsculo abre uma sequência de escape, então um hífen escrito nessa posição é ele próprio escrito por extenso — api-zone se torna api-zhzone, que é o que permite ler qualquer nome de volta sem adivinhar. Um hífen sem nada depois dele é escrito por extenso pelo mesmo motivo, então db- dá db-zh.
  • Todo outro caractere é escrito como -z seguido de uma letra que o nomeia: s para um separador de caminho, h para um hífen que a regra acima não mantém. Qualquer outra coisa — incluindo um espaço e uma letra não ASCII — é escrita como x seguido do ponto de código hexadecimal de seis dígitos do caractere, e um byte que não inicia nenhum caractere como b seguido do seu próprio valor de dois dígitos, de modo que uma identidade que não é texto válido ainda é escrita por extenso de forma distinta em vez de ser confundida com outra.
  • Uma identidade totalmente ausente — um nó sem anotação aggrega.ai/namespace em um arquivo compose sem caminho — é escrita -ze, que nenhuma identidade escrita por um autor pode produzir. Uma rede sem identidade, portanto, nunca compartilha 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 arquivo compose em dist/app/compose dá dist-zsapp-zscompose. Uma entrada idêntica sempre produz o nome idêntico.

Um namespace e o caminho de um arquivo compose são escritos no mesmo espaço. São duas formas de nomear a mesma coisa — em qual rede um nó está —, então um nó cujo namespace é app/compose e um nó sem namespace no arquivo compose em app/compose ficam deliberadamente em uma só rede, exatamente como acontece com duas fronteiras que levam a mesma anotação aggrega.ai/namespace. Onde você quiser manter dois nós separados, dê a eles identidades que difiram.

Mudar a identidade de um nó renomeia a rede do compose, e o compose não renomeia uma rede no lugar. A rede é criada do zero com o novo nome e todo serviço nela é recriado para se conectar a ela, enquanto a rede antiga fica para trás até que algo a remova. Uma rede não guarda dados, então nada se perde — mas os contêineres nela de fato reiniciam, e qualquer coisa que mantenha uma conexão durante a mudança vê essa conexão cair. Trate a mudança de uma anotação de namespace, ou do diretório em que um arquivo compose é escrito, como uma reimplantação a ser planejada, e não como um valor a ajustar no lugar.

Quando duas fronteiras convergem para um único caminho de composição (directory: compartilhado), os seus nós sem uma anotação aggrega.ai/namespace compartilham a única rede do arquivo; dê a cada fronteira a sua própria anotação aggrega.ai/namespace e o docker-compose.yaml mesclado declara uma entrada networks: de nível superior por anotação. Serviços de fronteiras diferentes dentro do mesmo arquivo compose podem se comunicar pelos seus nomes de serviço dentro da resolução DNS padrão do compose, sujeitos às próprias regras de alcançabilidade entre redes do compose. O roteamento L4 entre redes dentro de um único arquivo compose é o que a Feature compose-bridge da biblioteca padrão habilita, como conteúdo de catálogo do qual este provedor não contém nenhuma lógica: vinculada à fronteira ancestral comum, a sua FeatureRecipe deriva um gateway das arestas uses da fronteira cujas duas extremidades são compostas no seu próprio arquivo compose e ficam em redes diferentes dele — um serviço aggrega-gw cuja config nginx stream faz proxy de cada aresta com ponte (um bloco server por aresta, na porta do destino com um fallback 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 onde a mesma conexão entrega ambas. Essa reescrita substitui o valor que a própria conexão do consumidor entregou; se outra Feature vinculada ao consumidor entregou a mesma variável, o build é interrompido nomeando ambas em vez de substituí-lo. O valuesMapping da FeatureRecipe escreve essa config como uma config do 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 nomeia cada endpoint com ponte sob o x-aggrega-networks-of do gateway, que este provedor resolve nas redes em que esses endpoints estão posicionados (abaixo). Uma aresta cujas duas extremidades são compostas em dois arquivos compose não recebe ponte e mantém o nome próprio do destino; uma fronteira sem nada para conectar por ponte ainda leva o gateway ocioso, sem config e sem nenhuma rede além da sua; e uma ponte vinculada a uma fronteira cujo arquivo compose não contém nenhum componente interrompe o build em vez de escrever o gateway em lugar nenhum. A config stream leva uma diretiva resolver e faz proxy por meio 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 na inicialização — caso contrário, um proxy_pass simples para um destino ainda não em execução faria o gateway falhar na inicialização. (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. Veja o padrão compose-bridge.

Entrar nas redes de outros componentes — x-aggrega-networks-of

Um serviço que um fragmento escreve — um arquivo compose proveniente de uma fonte depois que a sua sobreposição é mesclada, ou um corpo artifacts: — pode entrar nas redes de outros componentes compostos no mesmo arquivo compose nomeando-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 escopo de fronteira lê como as chaves de .boundary.components e como o source e o target das suas listas de arestas .boundary. O provedor resolve cada ID para a rede em que esse componente está posicionado neste arquivo, pelo mesmo posicionamento que todo nó recebe, e adiciona essas redes ao serviço, cada uma uma única vez e em ordem de nome, antes da rede própria do serviço, na qual ele continua entrando. A própria chave é deixada de fora do arquivo composto. O provedor lê os IDs como referências a resolver e nada sobre o que o serviço faz, então qualquer Recipe ou FeatureRecipe pode usar a chave; o gateway da ponte do compose entra dessa forma nas redes dos endpoints entre os quais faz o repasse.

# 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 o build com TRANSLATION_ERROR quando o arquivo é composto, cada uma nomeando o serviço:

  • Um ID que nenhum componente composto neste arquivo leva — um composto em outro arquivo compose, por exemplo. Uma rede pertence a um único arquivo, então a mensagem nomeia o ID e o arquivo em que o serviço está. Nomeie apenas componentes compostos no mesmo arquivo, ou remova o ID.
  • Um valor que não é uma lista de strings. A chave recebe uma lista de IDs de componentes, mesmo para um único ID.
  • A chave em um serviço que escreve network_mode. O Compose não permite que um serviço com um network_mode entre em redes; remova um dos dois.

Inferência de depends_on

O provedor 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 arquivo compose mesclado, o provedor adiciona 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 também declara contêineres de inicialização contribui com um serviço executado até a conclusão por 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 contêiner de inicialização que precisa alcançar o destino da aresta, como uma migração de esquema contra um banco de dados para o qual o componente aponta com uses, não carrega nenhuma ordenação em relação a esse destino e pode ser executado antes que ele esteja acessível, enquanto o próprio serviço do componente espera tanto que a cadeia de inicialização termine quanto 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 a inicialização até que o healthcheck do destino informe que está saudável — é expressável, e uma aresta uses não pede isso. Uma onda que nomeia o mesmo par é a única coisa que muda a condição de uma entrada derivada de uma aresta, e ela faz isso porque a onda pede, e não porque a aresta pede.

As entradas derivadas de arestas são emitidas em ordem alfabética de destino para a estabilidade da saída. Arestas cuja origem ou cujo destino é servido por outro provedor (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 em uma das duas formas do compose, nunca em uma 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 carrega uma condição. É o caso de todo serviço cujas únicas dependências vêm de arestas uses.
  • Mapeamento em forma longa quando qualquer entrada carrega uma — o que acontece quando o serviço também espera por um contêiner de inicialização, ou quando uma onda de implantação o ordena. Nesse caso, as entradas derivadas de arestas emitem a condition: service_started explícita, que a Compose Specification define como o equivalente da forma curta, de modo que o significado delas não muda.

Dentro de um serviço, as origens mantêm 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 em ordem alfabética, depois as derivadas de ondas em ordem alfabética.

Ordem por ondas de implantação

O valor syncWave: de uma fronteira de uma Release ordena os serviços do arquivo compose no qual essa fronteira é renderizada. Cada componente da fronteira herda a onda da fronteira e, onde várias fronteiras compartilham um mesmo directory: — de modo que suas contribuições se fundem em um único docker-compose.yaml —, o arquivo mesclado contém mais de uma onda e o provedor expressa a ordenação entre elas como depends_on.

Cada serviço espera por todos os serviços da onda imediatamente anterior que tenha serviços, e por nenhuma onda anterior a essa. O compose resolve o resto de forma transitiva: um serviço na onda 2 espera pela onda 1, que espera pela onda 0, então toda a sequência fica ordenada enquanto a lista própria de cada serviço permanece do tamanho de uma onda, e não do arquivo inteiro. As ondas não precisam ser contíguas, e valores negativos são comuns — -1 é uma escolha frequente para uma migração que é executada antes de todo o resto.

A condição depende do que o destino consegue satisfazer. Uma onda significa que o grupo anterior está ativo antes que o seguinte comece, o que é prontidão, e não início do processo, então:

  • onde o serviço de destino declara um healthcheck, a espera é condition: service_healthy;
  • onde não declara, a espera é condition: service_started, porque um serviço sem healthcheck nunca consegue informar que está saudável e uma espera condicionada à saúde dele nunca seria satisfeita — o arquivo nunca subiria.

A condição mais fraca fica visível no arquivo emitido ao lado da mais forte, e o build também nomeia cada um desses serviços em um aviso, de modo que um autor que esperava uma ordenação por prontidão fica sabendo qual parte da onda que declarou chega apenas como ordenação de início. O aviso é consultivo: o build é bem-sucedido e os bytes renderizados são exatamente o que seriam sem ele. Adicionar um bloco health: a esse contêiner é o que reforça a espera. --no-unsupported-field-warnings silencia a classe.

A onda continua registrada como rótulo. A ordenação é adicionada ao lado do rótulo aggrega.ai/sync-wave, não no lugar dele: o rótulo é onde quem inspeciona o arquivo emitido vê de qual onda um serviço veio, o que as entradas depends_on não informam.

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

Uma fronteira cujos componentes estão todos em uma mesma onda não emite nada por isso. O mesmo vale para uma Release que não declara nenhum syncWave: cada contribuidor carrega o valor padrão do campo, 0, o arquivo mesclado contém uma única onda, e a saída é exatamente a que seria se o provedor não expressasse nenhuma ordem de ondas.

A ordenação entre dois arquivos compose não é expressável, e não é aproximada. depends_on nomeia um serviço dentro do mesmo arquivo, e fronteiras que são avaliadas para caminhos de montagem distintos produzem arquivos docker-compose.yaml distintos que o runtime do compose trata como projetos independentes. Assim, uma onda ordena cada serviço do arquivo no qual é renderizada e nada fora dele. Sequenciar dois projetos compose é responsabilidade do operador, da mesma forma que o roteamento entre arquivos; declarar um directory: compartilhado é o que leva duas fronteiras a um único arquivo, e é uma decisão sobre a forma da saída a ser tomada por razões próprias, e não para obter ordenação.

Uma aresta uses que aponta para uma onda posterior é emitida como foi escrita, e reportada. O depends_on emitido reflete o que foi declarado — tanto as arestas uses quanto as ondas. Uma aresta cujo consumidor está em uma onda anterior à do destino que usa afirma o oposto do que as ondas afirmam: a aresta faz o consumidor esperar pelo destino, enquanto as ondas fazem o destino esperar, através de cada onda entre eles, pelo consumidor. O arquivo mesclado expressa ambos, o que forma um conjunto de dependências circulares que o Docker Compose se recusa a iniciar. O build nomeia cada uma dessas arestas em um aviso que indica ambos os serviços e ambas as ondas, de modo que o ciclo aparece quando você executa o build, e não no docker compose up. O aviso é consultivo — o build é bem-sucedido 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 iniciar. Ele cobre apenas o par direto: nomeia os dois serviços que uma aresta conecta em vez de rastrear o ciclo inteiro. Qualquer ciclo construído a partir de arestas uses e ondas juntas passa por pelo menos uma dessas arestas, então é sempre reportado; um ciclo formado apenas por arestas uses, sem nenhuma onda envolvida, e um fechado por uma entrada depends_on escrita em um arquivo compose que a Recipe fornece são emitidos como foram escritos e não são reportados. Mantenha coerentes a direção das arestas e a ordem das ondas: coloque o consumidor na onda do destino ou em uma posterior, ou o destino na onda do consumidor ou em uma 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 onda imediatamente anterior e o compose encadeia o resto por meio de store.

Modo com fonte

O source: do provedor compose nomeia um arquivo YAML do docker-compose que o provedor consegue ler e analisar, e aceita as duas formas que o campo source: assume: uma string simples com um caminho do sistema de arquivos, e um objeto estruturado cujo url: carrega a localização. Sempre que essa localização for um caminho do sistema de arquivos, ela é ancorada ao diretório que contém o recipe.yaml que a declara, e não ao diretório a partir do qual o build é invocado, e deve permanecer dentro desse diretório: um caminho que sai dele, ou um absoluto, é recusado, porque todo arquivo que uma publicação da Recipe carrega é tirado do diretório dela — veja entities/recipe.md “Content paths stay inside the Recipe’s own directory (Caminhos de conteúdo permanecem dentro do próprio diretório da Recipe)”. O arquivo nomeado dessa forma é publicado com a Recipe, enquanto um arquivo ao lado da Recipe que nada do que ela declara nomeia nã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: carrega decide se algo é buscado. Um fragmento publicado por https:// é buscado e fixado com kind: compose-https-fragment; aggrega pull o obtém e o build o lê do cache. Um url: que nomeia um caminho do sistema de arquivos não é buscado — é lido do disco, ancorado exatamente como a forma de string simples acima, e aggrega pin registra o digest do arquivo que ele nomeia no arquivo entity.lock ao lado da Recipe, que um build então compara antes de o fragmento ser lido. Copiar localmente um fragmento remoto (vendoring) e apontar source: para a cópia local é suportado como alternativa à busca, 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 arquivo compose base em <path> é lido e analisado como YAML.
  2. O template valuesMapping é avaliado em relação ao contexto de template da Recipe. A saída dele é tratada como um documento de sobreposição compose — um arquivo compose parcial que complementa ou sobrescreve campos da base.
  3. Base e sobreposição são mescladas em profundidade usando a semântica de sobreposição nativa do docker-compose.

As regras da mesclagem em profundidade:

  • Escalares: a sobreposição vence. Quando a base e a sobreposição definem o mesmo campo escalar, o valor da sobreposição substitui o valor da base.
  • Mapas: mesclagem recursiva. Quando a base e a sobreposição definem o mesmo campo de mapa, a mesclagem desce recursivamente no mapa. Chaves presentes em ambas seguem as mesmas regras; chaves presentes em apenas uma são preservadas 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 inteiramente a lista da base (sem mesclagem elemento a elemento nem acréscimo). Isso 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 em um serviço — uma das chaves próprias do serviço, como user, command ou healthcheck, uma entrada de environment, um rótulo, ou uma chave diretamente sob healthcheck ou deploy — substitui o valor da base como qualquer escalar e é escrita no arquivo compose como key: null; ela não remove a chave. Onde o provedor escreve um valor próprio nessa chave, o arquivo carrega em vez disso o valor do provedor: labels: null mantém os rótulos de proveniência que o provedor aplica, e networks: null a rede que ele conecta. Um null escrito em qualquer outro lugar 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 seu valor do ambiente em que docker compose é executado.

Todo rótulo que o autor de um serviço escreveu permanece. Os labels: de um serviço no arquivo base ou na sobreposição podem ser escritos como um mapa ou como a lista de entradas key=value do Compose, e cada rótulo chega ao arquivo compose ao lado dos rótulos de proveniência que o provedor aplica. Uma entrada de lista é lida como o Compose a lê: o texto antes do seu primeiro = nomeia o rótulo e o texto depois dele é o valor, e uma entrada sem = é um rótulo com valor vazio. Um número ou um valor true/false é escrito como seu texto, de modo que replicas-hint: 2 chega ao arquivo como replicas-hint: "2", e um rótulo escrito como null continua null. Onde um rótulo escrito pelo autor e um rótulo de proveniência compartilham uma chave, o arquivo carrega o valor de proveniência. Um valor de labels: que não é nem um mapa nem uma lista, e uma entrada de lista que não é texto, interrompem o build, nomeando o arquivo de origem e o serviço. Os rótulos de serviço do corpo de um artifacts: assumem a forma de mapa: uma lista ali interrompe o build, nomeando o artefato e o serviço.

O documento mesclado segue então para a mesclagem no nível da Release junto 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 configs. A sobreposição não pode remover nada do arquivo base — um valor da sobreposição substitui, nunca exclui —, então um arquivo buscado que inclui um serviço que a Release não deve executar é justamente o caso para o qual servem as entradas omits: de uma Recipe ou de uma FeatureRecipe. Este provedor as respeita 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 arquivo pelo seu kind — service, volume ou config — e pelo seu name, a chave da unidade sob services:, volumes: ou configs:, comparada exatamente. Um arquivo compose não tem namespaces, então uma entrada que carrega um namespace, assim como uma que nomeia qualquer outro tipo, interrompe o build quando o componente é renderizado, nomeando a entrada e os tipos que este provedor aceita; cada entrada é verificada antes que qualquer coisa seja deixada de fora. As entradas são comparadas com o arquivo depois que a sobreposição acima é mesclada a ele, de modo que uma unidade que a sobreposição adicionou é deixada de fora exatamente como uma que a base declarou, e antes que o provedor adicione qualquer coisa própria, de modo que uma entrada nunca nomeia isso. Uma unidade que uma entrada nomeia é removida, e uma seção cujas unidades são todas deixadas de fora é removida com elas; toda outra unidade é escrita exatamente como seria sem as entradas. As entradas alcançam o arquivo da Recipe ou da FeatureRecipe que as declara e nada mais: o que outro componente ou uma Feature vinculada contribui para o mesmo docker-compose.yaml fica intocado, incluindo uma unidade com a mesma chave. O provedor informa quantas unidades cada entrada deixou de fora, e uma entrada que não deixou nenhuma de fora interrompe o build; veja 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 nomeada pelo que resta, porque o compose recusa um arquivo que nomeia um serviço, um volume ou uma config que ele não declara. Depois que as unidades são removidas, toda referência que o arquivo ainda faz a uma delas interrompe o build, e a mensagem nomeia cada serviço ou job que faz a referência, a unidade que ele nomeia e o campo em que a referência está. Uma referência é o que a Compose Specification define como uma entrada de um arquivo que nomeia outra:

  • um serviço, nomeado por depends_on em qualquer uma 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 nomeando um serviço do mesmo arquivo, 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 config, nomeada por uma entrada configs:, em qualquer uma 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 carregue. Alguns valores apenas parecem referências e não são lidos como tal: uma entrada volumes_from ou network_mode que começa com container: nomeia um contêiner, external_links nomeia um contêiner que este arquivo não declara, um extends com um file: nomeia um serviço de outro arquivo, e um credential_spec.config pode nomear uma config mantida pela plataforma, e não pelo arquivo. Cada valor é comparado como está escrito, de modo que uma referência escrita por meio de um ${VARIABLE} não é uma que esta verificação veja, e uma referência a uma unidade que o arquivo nunca declarou é deixada como está.

A verificação lê apenas o próprio arquivo da Recipe ou FeatureRecipe que declara, de modo que uma referência a um serviço deixado de fora interrompe o build mesmo onde outro contribuidor no mesmo caminho de montagem declara um serviço com esse nome. Para manter a referência, mantenha a unidade. Para removê-la, altere a entrada que faz a referência por meio de valuesMapping: — uma lista ali substitui a lista do arquivo base, então depends_on: [] esvazia uma — ou deixe de fora também o serviço que faz a referência.

Saída por (path, provider)

Cada caminho de composição do compose produz um docker-compose.yaml. Fronteiras que são avaliadas para caminhos distintos produzem arquivos compose distintos; fronteiras que compartilham um caminho avaliado produzem um único arquivo compose mesclado contendo todos os contribuidores nesse caminho. O caminho é o directory: da fronteira unido ao subDirectory: por componente (cujo padrão é {{ .capability }}, de modo que os contribuidores compose ficam por padrão em uma subpasta compose/).

Colisões de nomes de serviço dentro de um único caminho de composição interrompem o build. Quando dois nós diferentes contribuem com serviços com o mesmo ID de instância na mesma tupla (path, provider), o compilador é interrompido e o diagnóstico nomeia cada tupla (boundary, node) contribuinte em ordem alfabética. O autor resolve a colisão renomeando um dos contribuidores (normalmente ajustando o identificador do nó para que o sintetizador produza um nome de serviço diferente), ou direcionando os contribuidores para caminhos distintos por meio de declarações directory: diferentes.

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

Uma entrada volumes: escrita pelo autor é a que merece atenção, porque pode carregar um corpo próprio — um driver, driver_opts ou labels. Quando dois contribuidores declaram um mesmo nome com corpos diferentes, o build é interrompido com TRANSLATION_ERROR, nomeando 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, de um build que de outra forma teria sucesso. Resolva isso tornando idênticas as duas declarações, quando ambos os autores queriam o mesmo volume, ou renomeando uma delas, quando queriam dois. As redes de nível superior são uma por anotação aggrega.ai/namespace distinta, mais uma nomeada pelo caminho do arquivo compose para os nós que não carregam nenhuma, nomeadas conforme Como um nome de rede é derivado; duas fronteiras contribuintes com a mesma anotação aggrega.ai/namespace se fundem em uma única rede compartilhada por ambas, assim como duas fronteiras sem anotação que compartilham o arquivo.

Toda chave que um fragmento escreve é carregada ou recusada

Um fragmento — um arquivo compose proveniente de uma fonte depois que a sua sobreposição é mesclada, ou um corpo artifacts: que é avaliado como YAML do compose — chega ao docker-compose.yaml composto apenas pelas chaves que o provedor carrega, e esse conjunto é fixo. Toda chave que um fragmento escreve é carregada para o arquivo composto como foi escrita ou recusada pelo nome; nenhuma é deixada de fora sem uma palavra. Um fragmento é um único arquivo compose, então é um único documento YAML.

  • Carregadas. No nível superior: services, volumes, configs e models. Em um 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 provedor 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 config de nível superior. O corpo de um modelo e a entrada models: em forma longa de um serviço carregam todos os membros, como Modelos descreve. Um membro de extensão — uma chave que começa com x- — é carregado no nível superior e em um serviço, como Membros de extensão descreve.
  • Recusadas. Qualquer outra chave — stdin_open em um 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 o build com TRANSLATION_ERROR, nomeando cada uma dessas chaves, o seu caminho no fragmento (services.migrate.stdin_open), o fragmento e o componente, e nomeia os dois lugares de onde uma chave assim vem. Um é o próprio fragmento, e a correção é remover a chave dele. O outro é uma Recipe proveniente de uma fonte que não declara nenhum valuesMapping:: os valores do nó são então sobrepostos ao arquivo compose como estão, de modo que cada chave de valor chega como uma chave de nível superior do fragmento, e a correção é declarar um valuesMapping: que coloque cada valor sob uma chave que o provedor carrega. Uma chave que uma chave de mesclagem YAML (<<: *anchor) traz para um bloco é julgada onde chega, como se tivesse sido escrita ali. Um fragmento renderizado a partir da fonte se chama <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 o build com TRANSLATION_ERROR seja qual for o conteúdo do seu corpo — uma entrada vazia, um driver, qualquer outra coisa — nomeando a entrada (networks.back), o fragmento e o componente, porque o arquivo composto contém apenas as redes que o provedor deriva (veja Em qual rede um serviço entra). Remova a entrada: um serviço entra na rede do seu próprio componente sem nada declarado, a anotação aggrega.ai/namespace escolhe em qual rede um componente entra, um serviço nomeia os componentes em cujas redes também entra sob x-aggrega-networks-of, e a Feature compose-bridge faz o roteamento 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 é carregada 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 o build com TRANSLATION_ERROR, nomeando o fragmento, o componente e quantos documentos ele contém, porque a mesclagem lê um fragmento como um único arquivo compose e todo documento após o primeiro estaria de outra forma ausente do arquivo 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 arquivo compose proveniente de uma fonte com vários documentos nunca se torna um fragmento assim: ele é recusado quando o arquivo é lido.

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

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

A Compose Specification reserva as chaves que começam com x- para extensões: dados que uma ferramenta que lê o arquivo pode usar e que o próprio Compose ignora. Os membros de extensão de um fragmento no nível superior e em um serviço chegam ao arquivo composto como foram escritos, depois de todas as chaves que o provedor modela nesse nível, na ordem em que o fragmento os contém; o provedor não lê nada dentro deles, exceto o x-aggrega-networks-of de um serviço, que ele resolve nas redes em que o serviço entra e deixa de fora do arquivo composto (veja Entrar nas redes de outros componentes). Um corpo artifacts: os contém na ordem em que os escreve. As chaves de um arquivo compose proveniente de uma fonte chegam ao seu fragmento em ordem de nome depois que a sua sobreposição é mesclada, então os seus membros de extensão são escritos em ordem de nome.

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

Um membro alcançado por meio de um alias YAML é escrito por completo, e nenhuma âncora é carregada, de modo que o arquivo composto nunca contém um alias cuja âncora lhe falte; é isso que permite que um membro de nível superior contenha uma âncora que a chave de mesclagem de um serviço (<<: *base) traz. Os membros de um serviço viajam com o seu serviço. Os membros de nível superior se unem dentro de um caminho de composição pela 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 ou de fluxo, e dois que o escrevem com conteúdo diferente interrompem o build com TRANSLATION_ERROR, nomeando 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 habilitado, e que docker compose run --rm <service> inicia sob demanda — a forma compose de uma tarefa executada sob demanda. A lista é carregada como o fragmento a escreve, na sua ordem:

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

Modelos

A seção models: de nível superior de um arquivo compose declara os modelos de IA que os serviços do arquivo usam, e a um serviço é concedido um modelo por meio da sua própria entrada models:. O provedor carrega ambos de um fragmento para o docker-compose.yaml composto, na grafia própria do Compose, seja o fragmento um arquivo compose proveniente de uma fonte ou um corpo artifacts: que é avaliado como YAML do compose. Um Workload não declara nenhum modelo, então uma Recipe no modo Workload não contribui com nenhum.

  • O corpo de um modelo é escrito como o fragmento o escreveu. model — o identificador do artefato 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 carregados ao lado deles. Dentro de um modelo, os três membros nomeados vêm primeiro e o restante segue em ordem de chave, e os modelos são escritos em ordem de nome, de modo que uma entrada idêntica produz um arquivo idêntico byte a byte. O provedor não lê nada no corpo: não verifica o identificador e não sabe nada sobre o que vai 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 na ordem que o fragmento usou, e viaja com o seu serviço. Quando a forma longa deixa uma variável sem nome, o Compose a nomeia ao executar o arquivo.
  • Os modelos se unem dentro de um caminho de composição, pela 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 o build com TRANSLATION_ERROR, nomeando o modelo e cada tupla (boundary, node, fragment) contribuinte. Dois fragmentos de um mesmo componente também são dois contribuidores aqui. Torne idênticas as declarações quando ambos os contribuidores se referem a um único modelo, ou dê a uma delas um nome diferente.
  • Toda referência nomeia um modelo declarado. Depois que os fragmentos do caminho de composição são unidos, um serviço ao qual é concedido um modelo que nenhum contribuidor nesse caminho declara interrompe o build com TRANSLATION_ERROR, nomeando o serviço e o modelo. A verificação é executada sobre a união completa, então 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 provedor aceita, e uma entrada que nomeia um modelo interrompe o build como uma que nomeia qualquer outro tipo.

Os modelos são servidos quando o arquivo é executado, não quando é feito o build. O Docker Compose 2.38 ou posterior, em uma plataforma que suporta modelos do Compose como o Docker Model Runner, baixa 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 ele é concedido, as variáveis que a sua referência nomeia com o endereço do model runner e o identificador do modelo. O build não consegue ver o host que vai executar o arquivo, então não verifica nem a versão do Compose nem a plataforma: um arquivo que carrega modelos é composto da mesma forma, seja o que for que o execute.

Uma Feature vinculada a um componente contribui para o mesmo arquivo

Uma Feature vinculada a um componente contribui com os seus serviços para o docker-compose.yaml no qual o seu componente hospedeiro é composto, nos mesmos termos que a própria Recipe do hospedeiro. Não há um segundo arquivo ao lado dele: um caminho de composição produz um único documento, então os serviços de uma Feature vinculada ou estão nesse documento ou não são implantados de forma alguma. Desvincular a Feature remove exatamente esses serviços e deixa intactos os do próprio componente hospedeiro.

Eles são contribuidores nesse caminho de composição como qualquer outro, então 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 declaram um mesmo nome de volume ou de config de nível superior concordem sobre o que ele é. Eles também entram na mesma rede que o resto da fronteira, de modo que um componente e uma Feature vinculada a ele se alcançam pelo nome de serviço sem mais nada a declarar.

Cada serviço com que uma Feature contribui carrega a identidade composta para essa vinculação em vez da do componente hospedeiro, de modo que os dois continuam distinguíveis dentro de um documento para o qual ambos contribuíram. Rótulos e anotações explica como essa identidade é construída.

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

Fragmentos compose emitidos como artefatos

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

  • Os services: de artefatos são mesclados no arquivo 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 o build, e o diagnóstico nomeia cada contribuidor. Uma colisão dentro de um único componente — entre o próprio fragmento de artefato desse componente e os serviços sintetizados para ele — não é detectada, e a contribuição posterior substitui a anterior; por isso, mantenha o nome de um serviço escrito em um artefato distinto dos nomes <component> e <component>--<container-name> que o sintetizador produz (consulte Como um serviço sidecar ou de inicialização é nomeado).
  • Os volumes: de artefatos são mesclados 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 o build, venham elas de dois componentes ou de dois fragmentos de um mesmo componente — duas das suas entradas artifacts:, ou uma delas e o próprio arquivo compose do componente. Como um fragmento de artefato escreve os seus próprios corpos, esta é a via em que dois contribuidores têm mais chance de discordar. Mantenha o nome de um volume escrito em um artefato distinto dos demais no seu caminho de composição, inclusive da forma <component>--<volume-name> que a derivação produz — a menos que dois contribuidores devam descrever um único volume compartilhado, caso em que as suas declarações precisam coincidir.
  • Os configs: de artefatos são mesclados no bloco configs: de nível superior. É assim que o arquivo por trás de um volume configmap chega à composição: o volume se torna uma referência configs: no nível do serviço que nomeia o configmap, e o fragmento de artefato declara uma entrada com esse nome com content: inline. Depois que os fragmentos do caminho de composição são unidos, cada referência no nível do serviço precisa ser resolvida para uma entrada declarada, ou o build é interrompido com TRANSLATION_ERROR nomeando cada referência não resolvida — o serviço, o nome da config e o caminho de montagem. A verificação é executada sobre a união completa e não por componente, de modo que um componente pode referenciar uma config que outro componente no mesmo caminho de composição declara. A união se concilia por nome quando os contribuidores concordam: dois que declaram um mesmo nome de config com content: idêntico deixam a única entrada que ambos descreveram. Dois que declaram um mesmo nome com content: diferente interrompem o build com TRANSLATION_ERROR, nomeando a config e cada tupla (boundary, node, fragment) contribuinte, incluídos dois fragmentos de um mesmo componente — uma entrada de config sempre leva conteúdo, então manter qualquer uma das declarações descartaria um arquivo que um autor escreveu. Mantenha um nome de config distinto entre todos os contribuidores do seu caminho de composição, ou torne as declarações idênticas quando dois contribuidores devem entregar um único arquivo compartilhado.
  • Os models: de artefatos são mesclados no bloco models: de nível superior, e a referência models: de um serviço viaja com o seu serviço, segundo as regras em Modelos: dois contribuidores que declaram um mesmo nome de modelo precisam declará-lo de forma idêntica, e cada referência precisa nomear um modelo que algum contribuidor no caminho de composição declare.
  • Os networks: de artefatos são recusados. O provedor compose deriva as redes das anotações da fronteira (uma rede por anotação aggrega.ai/namespace distinta, mais uma com o nome do caminho do arquivo compose, na qual entra todo nó que não tem nenhuma, cada uma nomeada conforme Como um nome de rede é derivado), então uma declaração de rede fornecida por um artefato não tem lugar no arquivo composto: qualquer entrada interrompe o build, nomeando a entrada e o fragmento, segundo as regras em Toda chave que um fragmento escreve é carregada ou recusada. Remova a entrada e molde as redes por meio da anotação aggrega.ai/namespace, ou faça um serviço entrar nas redes de componentes nomeados por meio de x-aggrega-networks-of; autores que precisam de roteamento entre redes dentro de um único arquivo compose usam a Feature compose-bridge.
  • Os membros de extensão de artefatos são carregados. Uma chave x- de nível superior é escrita depois das outras seções do arquivo composto, na ordem em que foi escrita, segundo as regras em Os membros de extensão são carregados tal como foram escritos.
  • Qualquer outra chave de nível superior de artefatos interrompe o build. services:, volumes:, configs:, models: e os membros de extensão são tudo o que o montador carrega de um fragmento. Um bloco secrets: e um name: de nível superior interrompem cada um o build nomeando a chave e o fragmento, segundo as regras em Toda chave que um fragmento escreve é carregada ou recusada.
  • Um corpo artifacts: é um único documento. Um corpo que contém vários documentos YAML interrompe o build nomeando 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: levam conteúdo por Recipe que o montador acumula no arquivo composto; networks: é infraestrutura por fronteira que o montador deriva do estado da fronteira. Os artefatos 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 artefato é recusada. Os membros de extensão são dados que a Compose Specification define para outras ferramentas, então são carregados tal como foram escritos. Todo o resto é uma forma para a qual o documento composto não tem lugar, e é por isso que é recusado em vez de mesclado.

O que o provedor compose não entrega

  • Roteamento L4 entre redes dentro de um arquivo compose. O provedor posiciona cada nó na sua rede e faz um serviço entrar nas redes que x-aggrega-networks-of nomeia, e não roteia nada entre redes por conta própria. Um serviço na rede A que alcança um serviço na rede B por qualquer meio diferente do DNS padrão do docker-compose requer a Feature compose-bridge, cuja FeatureRecipe escreve o gateway e a reescrita.
  • Roteamento entre arquivos compose. Fronteiras que são avaliadas para caminhos de composição distintos produzem arquivos docker-compose.yaml distintos; o runtime do compose os trata como projetos independentes, e a Feature compose-bridge deixa uma conexão entre dois arquivos como foi escrita. A comunicação entre arquivos é assunto do operador (publicar portas do host, compartilhar redes externas ou fazer as fronteiras convergirem para um único caminho via um directory: compartilhado).
  • Obter uma variável de ambiente de uma vinculação. O Compose não tem uma primitiva para isso, então 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 espaço reservado é proposital — uma variável presente, mas vazia, é visível para quem depura o contêiner, enquanto uma ausente não deixa nada para examinar — e o build avisa isso em vez de deixar que seja descoberto: cada entrada desse tipo gera um aviso unsupported-field que nomeia a entrada na sua coordenada de autoria (containers.<name>.attachments.<KEY>, ou initContainers[<i>].attachments.<KEY>), para que o autor saiba qual variável chega vazia e a qual contêiner ela pertence. O aviso é consultivo: o build é bem-sucedido, e o arquivo renderizado é byte por byte o que seria sem ele. --no-unsupported-field-warnings silencia a classe. Uma entrada attachments com as: file não é afetada — o compose a monta como bind mount, e nenhum aviso é gerado.
  • Conteúdo deploy: do modo swarm. Réplicas, restrições de posicionamento e estratégia de atualização sob deploy: são funcionalidades do modo swarm, e o provedor compose visa apenas o compose em um único host, então não emite nenhuma delas. Ele emite, sim, deploy.resources — as reservas e os limites aos quais os resources de um contêiner correspondem, que o docker compose respeita fora do modo swarm (veja Recursos de contêiner).
  • 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; ela não é condicionada a que o healthcheck do destino reporte estar saudável. Isso diz respeito ao que uma aresta uses significa, não a uma forma que o provedor não consegue produzir: a forma longa é emitida para a espera de um contêiner de inicialização, e uma onda de implantação condiciona, sim, a espera à saúde do destino quando o destino declara um healthcheck.

Exemplo de autoria

Uma implantaçã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 provedor compose produz um único docker-compose.yaml no caminho avaliado da fronteira (por padrão dist/boundaries/production/compose/docker-compose.yaml, porque o directory: de uma fronteira tem como padrão dist/boundaries/<name> e subDirectory:, {{ .capability }}) contendo:

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