Ir al contenido
AggregaAggrega
Seleccionar idioma: Español
Esta página se tradujo automáticamente. Lee el original en inglés.

Provider Compose

El proveedor compose renderiza Recipes de Aggrega en un archivo Docker Compose. El proveedor ensambla por (path, provider): los contribuidores compose de cada límite se encaminan al ensamblador indexado por el directory: evaluado del límite unido al subDirectory: de cada componente, y ese ensamblador emite un único docker-compose.yaml que contiene a todos los contribuidores de esa ruta. Dos límites hermanos que se evalúan a la misma ruta se funden en un único archivo compose combinado — el ejemplo canónico es un límite padre más dos límites hijos con directory: "{{ .parent_boundary.directory }}" (el patrón compose-bridge).

Tipos de entrada admitidos

El proveedor compose acepta los tres tipos de entrada de una Recipe:

  • Modo procedente de una fuente. Una Recipe con source: que apunta a un archivo compose existente más valuesMapping: que produce un documento de superposición. Se carga el archivo compose base, se evalúa la superposición y ambos se combinan en profundidad según la semántica de superposición nativa de docker-compose.
  • Modo Workload. Una Recipe con workload: (inline o cargado mediante $import:) declara un documento Workload. El proveedor sintetiza uno o más servicios compose a partir de la especificación del Workload.
  • Modo de artefactos. Las entradas artifacts: de una Recipe se evalúan como fragmentos compose, que se combinan en el archivo ensamblado según las reglas de Fragmentos compose emitidos como artefactos. Los artefactos pueden acompañar a una fuente o a un Workload, y también pueden ser toda la salida de una Recipe: una Recipe que declara artifacts: y ni source: ni workload: se renderiza aquí, aportando lo que declaren sus fragmentos. Así es como un componente que solo consta de recursos — un conjunto compartido de red y volúmenes, una configuración precargada — llega a un despliegue compose sin un Workload de relleno que ocupe el lugar de un cómputo que no tiene.

Los tres tipos se combinan por adición, y una Recipe que no declara ninguno se rechaza al cargarse. Un valuesMapping: sin un source: al lado también se rechaza al cargarse la Recipe, sea cual sea el proveedor que nombre: no hay nada a lo que aplicar la superposición, y el diagnóstico te pide que declares el puntero source: o que elimines el valuesMapping:.

Correspondencia de funcionalidades del Workload

Cuando una Recipe declara workload:, el proveedor traduce la forma Workload propiedad de la plataforma a primitivas compose. La correspondencia es intencionadamente estrecha — la superficie de Compose es más pobre en formas que la de Kubernetes, y varias funcionalidades del Workload se degradan al equivalente compose más cercano con una pérdida documentada.

Campos del contenedor

Campo del WorkloadCampo de Compose
imageimage
imagePullPolicy: Always / IfNotPresent / Neverpull_policy: always / if_not_present / never
commandentrypoint (forma de lista) — sobrescribe el punto de entrada de la imagen, que es lo que hace esa clave de compose
argscommand (forma de lista) — proporciona los argumentos que recibe el punto de entrada, que es lo que sobrescribe el command de compose
variablesenvironment (forma de mapa)
attachments[as: env]entrada de environment con un valor vacío, y una advertencia que nombra la entrada (consulta Lo que el proveedor compose no entrega)
attachments[as: file]bind-mount de volumes en forma larga, de solo lectura
volumeMountsla primitiva compose a la que corresponde la variante de volumen referenciada — una entrada volumes en forma larga, una entrada tmpfs: a nivel de servicio o una referencia configs: a nivel de servicio (consulta Volúmenes)
portsimplícito (los contenedores compose exponen los puertos en los que escucha la imagen)
restartPolicy: Alwaysrestart: unless-stopped
restartPolicy: OnFailurerestart: on-failure
restartPolicy: Neverrestart: "no"

variables y attachments[as: env] van a parar al único mapa environment, primero las entradas de las vinculaciones y después las variables, cada una en el orden en que se escribe — el orden que escribe el proveedor helm, de modo que un Workload renderiza una sola secuencia de entorno en todos los destinos. Compose no expande ninguna referencia $(NAME) entre las entradas de entorno de un servicio, así que en compose ese orden no tiene ningún significado en tiempo de ejecución. Como el mapa contiene cada nombre una sola vez, un contenedor que da un mismo nombre tanto como entrada de variables como entrada de attachments entregada as: env detiene la compilación en lugar de conservar uno de los dos valores (consulta A container gives one environment variable two values (Un contenedor da dos valores a una misma variable de entorno)).

Recursos de los contenedores

Los resources de un contenedor llegan al bloque deploy.resources de compose, que docker compose respeta en modo no swarm. Las requests de Kubernetes expresan un mínimo garantizado, así que se convierten en reservations de compose; los limits expresan un tope estricto, así que siguen siendo limits.

Campo del WorkloadCampo de ComposeTraducción
resources.requests.cpudeploy.resources.reservations.cpusUn número decimal de núcleos. Un número de núcleos escrito como número simple (2, 0.5) se emite tal como está escrito; cualquier otra forma se convierte a partir de su valor (500m → 0.5, 1500m → 1.5, 5n → 0.000000005, 1e1 → 10)
resources.limits.cpudeploy.resources.limits.cpusLa misma conversión
resources.requests.memorydeploy.resources.reservations.memoryUn número exacto de bytes, convertido a partir del valor sea cual sea la forma en que esté escrito — 8Gi se convierte en 8589934592, 1.5Gi se convierte en 1610612736, 1e3 se convierte en 1000
resources.limits.memorydeploy.resources.limits.memoryLa misma conversión
nvidia.com/gpu, bajo resources.limits, resources.requests o ambosdeploy.resources.reservations.devicesUna entrada de dispositivo NVIDIA en el servicio del contenedor — driver: nvidia, count: el número de GPU, capabilities: [gpu]. El número es el del límite donde hay un límite escrito — el número que Kubernetes planifica para un recurso extendido — y el de la solicitud en caso contrario. Un número de 0 no pide ninguna GPU y no escribe ninguna entrada
cualquier otra clave de recurso extendido — amd.com/gpu y cualquier otro <domain>/<name>—Sin equivalente compose en un solo host. La clave se descarta y la compilación emite una advertencia unsupported-field que la nombra, una por cada clave distinta, sin importar cuántas de las requests y los limits la llevaran. Su valor no se emite, así que no se comprueba

Cada valor de cpu, memory y nvidia.com/gpu se lee como una cantidad, en la forma expuesta en Workload → Cantidades de recursos, sobre el Workload tal como lo evaluaron las plantillas de la Recipe. Dos cosas detienen la compilación con un TRANSLATION_ERROR, y el error dice cuál de las dos encontró, nombrando la ruta del contenedor, si el valor es una solicitud o un límite, el recurso y el valor:

  • un valor que no es una cantidad — lots, 1.5 cores, o la m que una plantilla vacía deja en "{{ .infra.cpu }}m";
  • una cantidad que compose no puede representar exactamente — una cantidad negativa; una cantidad de memoria que no es un número entero de bytes (1500m, 4u) o que supera los 9223372036854775807 bytes (8Ei); una cantidad de cpu más fina que nueve decimales de un núcleo, la precisión más fina que conserva la propia cantidad de Kubernetes, o mayor que 9223372036.854775807 núcleos; un número de GPU que no es un número entero de dispositivos (0.5, 500m).

Un contenedor cuya solicitud y cuyo límite de nvidia.com/gpu piden números distintos detiene la compilación de la misma manera, nombrando ambas rutas: compose reserva un solo número para un servicio, así que de lo contrario la traducción tendría que elegir uno. Escribe el mismo número en ambos, o solo el límite.

Nada se redondea, y no se emite ningún valor que signifique otra cosa.

Una solicitud de GPU reserva GPU NVIDIA. Un contenedor de Workload que pide nvidia.com/gpu: "1" se renderiza como un servicio que lleva esta reserva, junto a cualquier cpus y memory que reserven sus solicitudes:

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

Docker Compose entrega las GPU reservadas al contenedor cuando el host de Docker tiene esa cantidad de GPU NVIDIA y está configurado para dárselas a los contenedores; la compilación no puede ver el host, así que un archivo que reserva GPU se ensambla del mismo modo dondequiera que vaya a ejecutarse. La entrada siempre indica su número, porque Compose lee una entrada de dispositivo sin número como todas las GPU del host. Solo se traduce la clave de NVIDIA: amd.com/gpu y la clave de cualquier otro fabricante mantienen la advertencia de la fila de claves descartadas. La fila runtimeClassName de Campos a nivel de pod no cambia — compose no tiene equivalente de la clase de runtime, así que a un Workload que nombra un runtime con GPU se le indica que el runtime se omitió, mientras que su número de GPU se reserva.

Sondas

Los tres slots de sonda de un Workload (live, ready, startup) se reducen al único healthcheck por servicio de compose, con la prioridad live > ready > startup (gana la señal de liveness más canónica). Donde esa reducción descarta un slot que el autor declaró, la compilación emite una advertencia unsupported-field que nombra el slot traducido y los slots descartados, de modo que una intención que no llega a ninguna parte de la salida se informa en lugar de perderse. Un bloque health que declara un solo slot se traduce sin pérdida y no emite nada, salvo que el slot establezca successThreshold: un healthcheck de compose no tiene campo para ello, así que un valor escrito por el autor — 1 incluido — se omite con una advertencia unsupported-field que lo nombra (containers.<name>.health.<slot>.successThreshold), y el resto del slot se traduce como muestra la tabla siguiente.

Forma de sonda del Workloadhealthcheck.test de Compose
http: /path["CMD-SHELL", "curl -f http://localhost:<port>/path || exit 1"]
tcp: <port>["CMD-SHELL", "nc -z localhost <port>"]
exec: [cmd, ...]["CMD", cmd, ...]

La forma HTTP requiere que el contenedor declare al menos un puerto con nombre; el sintetizador elige el primer nombre de puerto por orden alfabético y usa su número para construir la URL de curl. Los contenedores sin puertos declarados no pueden usar sondas HTTP — el compilador se detiene con un TRANSLATION_ERROR que nombra la sonda en cuestión.

Los campos de tiempo de espera de las sondas se corresponden con cadenas de duración al estilo de compose:

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

Volúmenes

Compose tiene una primitiva de config propia, que es a lo que se traduce un volumen configmap. No tiene un equivalente de Kubernetes para Secret ni para las plantillas de volumen por réplica, así que esas variantes se degradan a la primitiva de compose más cercana:

Variante de volumen del WorkloadTraducción de ComposeNotas sobre pérdidas
ephemeralentrada de lista tmpfs: a nivel de serviciosizeLimit no se conserva (la forma corta de tmpfs de compose no tiene tamaño). Un sizeLimit escrito por el autor genera una advertencia unsupported-field que lo nombra en su coordenada de autoría (volumes.<name>.ephemeral.sizeLimit), tanto si un contenedor monta el volumen como si no; omitir el campo no genera nada
configmapreferencia configs: a nivel de servicio que nombra el configmap, montado en la ruta del montaje del volumen🔴 La ruta de montaje es la ruta de un único archivo, no de un directorio. Compose escribe el contenido de la config exactamente en la ruta de destino, mientras que un destino Kubernetes que monta un ConfigMap en una ruta produce un directorio que contiene un archivo por clave. Así, el mismo path: escrito designa aquí un archivo y allí un directorio: apunta el montaje de un volumen configmap al nombre de archivo que el contenedor debe leer (/seed/config.json), no al directorio que lo contendría, y una Recipe escrita para ambos destinos lleva una ruta distinta para cada destino. Nada en la compilación puede detectar una ruta escrita para la forma del otro destino — la ruta es una cadena opaca que el compilador transmite tal cual, y la salida emitida es válida en ambos casos. La referencia es por nombre, exactamente como un destino Kubernetes hace referencia a un recurso ConfigMap — nada lee el contenido de la config. La entrada configs: de nivel superior correspondiente proviene de la entrada artifacts: de la Recipe, cuyo fragmento de compose la declara con content: en línea; una referencia sin esa entrada detiene la compilación (consulta Fragmentos compose emitidos como artefactos). Una referencia configs: lleva el nombre de la config y la ruta de montaje y nada más, por lo que el readOnly del montaje no tiene una expresión propia
secretbind-mount de volumes en forma larga, de solo lecturaUn volumen de secreto deliberadamente no sigue la traducción configmap: una entrada configs: en línea escribiría el valor del secreto en texto plano en el archivo compose emitido, y el compilador nunca resuelve un secreto en texto plano — un secreto sigue siendo un puntero en todas las etapas de la compilación. El origen del bind es el nombre source del secreto, resuelto como una ruta que el operador hace accesible en el host de compose con independencia de la compilación
persistentvolumen con nombre + declaración volumes: { <volume-name>: {} } de nivel superior, con el nombre formado según Cómo se deriva un nombre de volumenLa clase de almacenamiento, los modos de acceso y el tamaño no se conservan (compose no tiene una forma equivalente). Un class o un accessModes escrito por el autor genera una advertencia unsupported-field que lo nombra en su coordenada de autoría (volumes.<name>.persistent.class, volumes.<name>.persistent.accessModes); omitir cualquiera de los dos no genera nada. El size obligatorio no genera ninguna advertencia — consulta más abajo
persistentTemplatevolumen con nombre + declaración de nivel superior, con el nombre formado del mismo modo (igual que persistent)Complemento de form: stateful; compose no tiene una primitiva de plantillas de volumen por réplica, así que el comportamiento por réplica se pierde, y una advertencia unsupported-field indica que el volumen se convirtió en un único volumen que comparten todas las réplicas. La clase de almacenamiento, los modos de acceso y el tamaño no se conservan, exactamente como en persistent: un class o un accessModes escrito por el autor genera una advertencia unsupported-field en volumes.<name>.persistentTemplate.class o volumes.<name>.persistentTemplate.accessModes, y el size obligatorio no genera ninguna

El subPath de un montaje monta una parte de un volumen donde compose tiene una forma para ello. Una entrada volumeMounts que nombra un volumen persistent o persistentTemplate con subPath se convierte en una entrada volumes en forma larga que lleva volume.subpath, de modo que el montaje ve el directorio o el archivo nombrado dentro del volumen en lugar de su raíz, y dos montajes de un mismo volumen con dos valores subPath distintos ven dos partes distintas de él:

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

Un montaje escrito sin subPath no lleva ningún bloque volume:. Un subPath en un montaje de un volumen ephemeral, configmap o secret detiene la compilación con un error TRANSLATION_ERROR que nombra el componente, el contenedor, la ruta escrita del montaje (containers.<name>.volumeMounts[<i>]), el volumen y el subPath: esas variantes llegan a compose como una entrada tmpfs, una referencia configs: y un montaje bind, ninguno de los cuales monta una parte de lo que entrega, así que de otro modo el montaje vería el volumen entero. Quita subPath de un montaje así, o monta un volumen persistent. Docker Compose lee volume.subpath desde la versión 2.26.0, en Docker Engine 26.0 o posterior; la compilación no puede ver el host que ejecutará el archivo, por lo que un archivo que lleve uno se ensambla igual dondequiera que vaya a ejecutarse.

Un volumen dice qué variante es y nada más. Un volumen secret tiene exactamente una traducción — el montaje bind de solo lectura descrito arriba — y un volumen no lleva ningún campo as: para seleccionar otra. Entregar lo que un slot publicó como variable de entorno corresponde a una entrada attachments del contenedor (as: env) y no a un volumen; lo que compose hace con una entrada así se describe en Lo que el proveedor compose no entrega.

Tres variantes llevan un tamaño de almacenamiento, y solo una de ellas advierte de que el tamaño se descartó. La diferencia está en si tuviste elección. El sizeLimit de un volumen ephemeral es opcional, así que escribirlo fue una decisión, y la advertencia te dice que el valor no da forma a nada en este destino y puede eliminarse — es orientativa y fuera de banda, el archivo emitido es byte a byte lo que sería sin ella, y --no-unsupported-field-warnings la silencia junto con el resto de la clase. El size de un volumen persistent o persistentTemplate es obligatorio, así que ninguna versión del documento lo omite: una advertencia en cada compilación se dispararía ahí en cada carga de trabajo con estado sin nombrar nada que pudieras cambiar, por lo que la diferencia se explica aquí en lugar de notificarse en cada compilación. Con compose como destino, size, class y accessModes de un volumen persistente no dan forma a nada en el archivo emitido — lo que obtienes es un volumen con nombre simple, dimensionado y respaldado por lo que haga de forma predeterminada el controlador de volúmenes del host de compose. class y accessModes son opcionales, así que cada uno que escribas se notifica igual que el sizeLimit de un volumen ephemeral: una advertencia unsupported-field por campo, orientativa y fuera de banda, silenciada por el mismo indicador. Dimensiona el almacenamiento subyacente en el host, o en el destino Kubernetes, donde los campos sí llegan a la salida.

Un volumen que ningún contenedor monta genera una advertencia unsupported-field que lo nombra en su coordenada de autoría (volumes.<name>), porque lo que llega al archivo emitido difiere entonces mucho según la variante. persistent y persistentTemplate siguen produciendo su declaración de nivel superior, así que el volumen se crea y nada lo usa. ephemeral, configmap y secret no tienen ninguna expresión fuera del propio montaje — cada uno se traduce en algo escrito en la ruta de montaje, respectivamente una entrada tmpfs, una referencia configs o un montaje bind — así que, si nada monta uno de ellos, el volumen que declaraste no deja ningún rastro en la salida. Ese segundo caso es la razón de que exista la advertencia: sin ella, un volumen configmap cuyo montaje olvidaste simplemente estaría ausente, sin nada en el archivo emitido que lo hiciera notar. Cada contenedor de la carga de trabajo cuenta como contenedor que monta el volumen, incluidos los contenedores de inicialización, así que un volumen montado solo por un contenedor de inicialización está conectado y no genera nada. La advertencia es orientativa y fuera de banda — el archivo emitido es byte a byte lo que sería sin ella — y --no-unsupported-field-warnings silencia la clase.

Cómo se deriva un nombre de volumen

Un volumen persistent o persistentTemplate se convierte en un volumen con nombre de compose: una entrada volumes: de nivel superior, referenciada por cada contenedor que lo monta. Un volumen de compose es almacenamiento compartido, y el bloque volumes: de nivel superior une sus entradas por nombre — así que dos volúmenes escritos que llegan a un mismo nombre se convierten en un solo volumen en el que escriben ambos contenedores, sin nada en el archivo emitido que muestre que se pretendían dos. Por eso el nombre se construye a partir de las dos identidades que juntas dicen de qué volumen se trata: el <component> al que pertenece el volumen, y el nombre que el Workload dio al volumen bajo volumes:.

Un nombre de volumen de compose acepta un conjunto de caracteres más reducido que el que puede llevar cualquiera de las dos identidades: letras, dígitos, puntos, guiones bajos y guiones. En lugar de sustituir un carácter que compose no acepta, la derivación lo escribe explícitamente, de modo que dos volúmenes que difieren en lo más mínimo llegan a dos nombres — y un nombre ensamblado puede leerse de vuelta en las dos identidades a partir de las que se construyó.

  • Una letra, un dígito, un punto y un guion bajo se conservan exactamente como se escribieron.
  • Un guion se mantiene tal como se escribió siempre que el carácter que lo sigue se conserve directamente y no sea una z minúscula. Un guion seguido de una z minúscula abre una secuencia de escape, así que uno escrito en esa posición se escribe a su vez explícitamente — api-zone se convierte en api-zhzone, que es lo que permite leer de vuelta cualquier nombre sin adivinar. Un guion sin nada detrás se escribe explícitamente por la misma razón, así que db- da db-zh.
  • Cualquier otro carácter se escribe como -z seguido de una letra que lo nombra: s para un separador de ruta, h para un guion que la regla anterior no mantiene. Todo lo demás — incluidos un espacio y una letra no ASCII — se escribe como x seguido del punto de código hexadecimal de seis dígitos del carácter, y un byte que no inicia ningún carácter como b seguido de su propio valor de dos dígitos, de modo que un nombre que no es texto válido se escribe igualmente de forma distinta en lugar de confundirse con otro.
  • Un valor vacío se escribe -ze, que ningún valor no vacío puede producir.
  • Las dos identidades se unen con --. Una sola identidad codificada nunca contiene ese par, así que el nombre unido dice sin ambigüedad dónde termina una identidad y dónde empieza la otra.

Así, el componente store con un volumen que el Workload llama data da el nombre de volumen store--data, y db-server con data da db-server--data. Una entrada idéntica produce siempre el nombre idéntico.

La unión doble es lo que hace que el par no sea ambiguo, y una unión de un solo carácter no puede lograrlo. Cualquiera de las dos identidades puede llevar a su vez un guion, así que una unión con un solo guion deja un nombre que se divide en más de un lugar: db con un volumen llamado data-cache y db-data con un volumen llamado cache darían ambos db-data-cache, y como el bloque de nivel superior une por nombre, los dos componentes compartirían un solo volumen sin nada en el archivo emitido que lo mostrara. Una identidad codificada nunca contiene un par de guiones, así que la unión doble no admite una segunda lectura: los dos llegan a db--data-cache y db-data--cache.

Cambiar cualquiera de las dos identidades renombra el volumen de compose, y compose no renombra un volumen en su sitio. El volumen se crea de nuevo con el nuevo nombre mientras el antiguo queda atrás con los datos dentro, así que el contenedor arranca con un almacenamiento vacío y el contenido queda en un volumen que nada monta. Renombra cualquiera de las dos identidades solo como un reemplazo que hay que planificar — con copia de seguridad, copiando los datos o programado — y no como un cambio que se despliega sin más.

Forma de controlador

El form del Workload selecciona una forma abstracta de controlador (consulta entities/workload.md). Compose renderiza stateless y stateful (y el valor predeterminado vacío, tratado como stateless) como servicios de larga duración; la forma stateful añade el volumen con nombre para un complemento persistentTemplate. Las formas daemon, scheduled y task no tienen una correspondencia limpia en compose de un solo host, así que un Workload que declara una de ellas con un límite de compose como destino detiene la compilación con un error TRANSLATION_ERROR que nombra la forma y el conjunto admitido — compose no degrada una forma no admitida a un servicio simple que tergiverse la intención. Un Workload reference declara un endpoint externo y ningún contenedor, así que compose no emite ningún servicio para él.

Como no se emite ningún servicio para un Workload reference, nada lee la tubería de entrega del componente que realiza: una credencial vinculada a ese componente — entregada en su tubería por dotenv-secret, o por el propio bloque inject: de una vinculación — no llegaría a ningún archivo emitido. Por eso, toda Recipe de Compose de la biblioteca estándar que realiza así un servicio externo, y cuyo Component declara un slot de credencial, rechaza una credencial que llene ese slot: la compilación se detiene nombrando el slot y el componente, en lugar de terminar con éxito sin la credencial. En compose, una credencial para un servicio externo se vincula al componente que lo llama, bajo la variable de entorno que lee ese componente. Ese rechazo es una aserción propia de cada Recipe, y se ejecuta antes de que este proveedor renderice nada. Este proveedor también rechaza en el propio nodo, sea cual sea el catálogo del que procede la Recipe: una vinculación en un nodo reference cuyo material se declara sensible — su Feature declara un campo sensitive: true, o lo hace el slot que llena — detiene la compilación con TRANSLATION_ERROR (E0288), nombrando el nodo y cada una de esas vinculaciones, tanto si algún slot declara el nombre bajo el que está vinculada como si no. Una vinculación que no lleva nada declarado sensible no se rechaza aquí. Esos Components declaran opcionales sus slots de credencial, así que en compose un slot que se deja vacío no detiene nada. Donde la realización de Kubernetes necesita la credencial — las Recipes helm de twilio, vonage, telnyx, bland, letta, retell y vapi — esa Recipe exige el slot en su lugar, y detiene la compilación nombrándolo cuando está vacío.

Exposición de servicios

El campo type de una entrada services del Workload decide si compose publica puertos, y en qué dirección del host:

Tipo de servicio del WorkloadComportamiento de Compose
ClusterIPSin publicación ports: — el servicio solo es accesible en la red de compose
NodePortPublicación ports: [<host>:<container>], en todas las interfaces del host
LoadBalancerPublicación ports: [<host>:<container>], en todas las interfaces del host (compose no tiene un equivalente de balanceador de carga gestionado; la publicación en un puerto del host es el análogo más cercano)
LoopbackPublicación ports: [127.0.0.1:<host>:<container>] — accesible desde el propio host y desde ningún otro lugar
HeadlessSin publicación ports:

Qué número va en qué lado. Una entrada de servicio nombra un puerto de contenedor y le da un número, del mismo modo que un Service de Kubernetes asigna su port a un targetPort. El número de la entrada es el lado <host> del par publicado, y el número del puerto de contenedor al que se resuelve el nombre es el lado <container>. Así, un contenedor que declara http: 8080 y una entrada NodePort que escribe http: 8081 publican 8081:8080: el puerto 8081 del host llega al puerto en el que sirve el contenedor. Una entrada que lleva el propio número del puerto de contenedor publica ese número en ambos lados, 8080:8080. Un par en la red de compose alcanza el servicio por su nombre de servicio en el puerto del contenedor, nunca en el publicado — el puerto publicado pertenece al host — así que una Recipe que publica un puerto de su elección sigue entregando a sus consumidores el puerto del contenedor.

Una entrada Loopback se enlaza solo a la dirección de loopback IPv4. La dirección de loopback IPv6 ::1 no se enlaza: la sintaxis de puertos de compose lleva una sola dirección de host por entrada, y un host cuya interfaz de loopback no tiene dirección IPv6 no podría enlazarla, así que el servicio no arrancaría allí. Los clientes en el host alcanzan el puerto en 127.0.0.1.

Cuando varios servicios de un mismo Workload publican el mismo puerto de contenedor con el mismo número, se publica una vez, y gana el alcance más amplio: cualquier referencia NodePort o LoadBalancer lo publica en todas las interfaces del host, aunque una entrada Loopback también lo nombre y sea cual sea la entrada que se declare primero; un puerto que solo nombran entradas Loopback se publica en 127.0.0.1. Un puerto de contenedor publicado con dos números se publica dos veces, una con cada uno. Los puertos publicados se enumeran en el orden de los puertos de contenedor, y por puerto publicado dentro de un mismo puerto de contenedor.

Transporte de los puertos. Una entrada publicada lleva el transporte declarado en el puerto de contenedor que nombra, como el sufijo /protocol de compose: 53:53/udp, o 127.0.0.1:53:53/udp para una entrada Loopback. Un puerto que no declara ningún transporte se publica como <host>:<container> sin sufijo, lo que deja en vigor el valor predeterminado de compose. Compose escribe el transporte de un puerto publicado como tcp o udp; un puerto que declara SCTP no tiene grafía en compose, así que detiene la compilación con un error TRANSLATION_ERROR en lugar de publicar un puerto que llevaría un transporte distinto. Un puerto de contenedor que ningún servicio publica no llega a ninguna parte del archivo compose, así que un transporte declarado en un puerto así no tiene dónde escribirse y no detiene la compilación.

Workloads multicontenedor

Un Workload con varios contenedores se convierte en un servicio principal más un servicio sidecar por cada contenedor no principal. El contenedor principal es el que se llama main (cuando existe) o el primer contenedor en orden de declaración. Los sidecars comparten el espacio de nombres de red del servicio principal mediante network_mode: "service:<main>" — la primitiva de compose más cercana al modelo de red compartida de un pod de Kubernetes.

Cómo se nombra un servicio sidecar o init

El servicio principal lleva el nombre <component> tal cual. Cualquier otro servicio que produce el Workload — uno por sidecar, y uno por contenedor init — recibe su nombre de dos identidades juntas: el <component>, y el nombre del contenedor, que es su clave bajo containers: para un sidecar y su name para un contenedor init, o el init-<index> posicional que toma una entrada init sin nombre. El bloque services: ensamblado contiene un servicio por nombre, así que el nombre se construye de forma que dos contenedores que difieren en cualquiera de las dos identidades lleguen siempre a dos nombres.

Cada identidad se escribe exactamente como las dos partes de un nombre de volumen — una letra, un dígito, un punto y un guion bajo tal como se escribieron, un guion conservado donde las reglas de esa sección lo conservan, y cualquier otro carácter transcrito — y las dos se unen con --, que ninguna identidad transcrita contiene. Así, el componente api con un sidecar logger lo ejecuta como api--logger, el contenedor init import-seed de platform se ejecuta como platform--import-seed, y una primera entrada init sin nombre de api se ejecuta como api--init-0. Un nombre de contenedor que lleva un carácter que un nombre de servicio no admite se transcribe en lugar de emitirse tal como se escribió: un contenedor init llamado warm cache/x de api se ejecuta como api--warm-zx000020cache-zsx.

La unión doble mantiene separados los contenedores de dos componentes. api con un contenedor warm-cache y api-warm con un contenedor cache se ejecutan como api--warm-cache y api-warm--cache, dos servicios, donde una unión de un solo guion escribiría ambos como api-warm-cache.

Los sidecars y los contenedores init comparten esta única forma de nombrar, así que una entrada containers y una entrada initContainers con el mismo nombre llegan al mismo nombre de servicio, y la compilación se detiene ante el par en vez de ejecutar un contenedor en el lugar del otro (consulta Contenedores de inicialización).

El servicio propio de un componente no toma ninguno de estos nombres. El servicio principal recibe el nombre del componente, y un guion doble escrito en el nombre de un componente se transcribe también allí — un componente llamado api--prep se ejecuta como api-zh-prep — así que nunca lleva la unión --. Donde servicios de dos componentes distintos coinciden aun así en un nombre dentro de un mismo archivo compose — a través de un servicio que un artefacto nombra para sí mismo, por ejemplo — la compilación se detiene nombrando a ambos, como describe Salida por (path, provider).

Cambiar el nombre del componente o el nombre del contenedor renombra el servicio. Compose trata un servicio con un nombre nuevo como un servicio nuevo, así que su contenedor se crea de nuevo con el nombre nuevo.

Campos a nivel de pod

Los campos del Workload a nivel de pod se aplican solo al servicio principal — los sidecars comparten el espacio de nombres de red del servicio principal — y un servicio de inicialización sigue la misma regla. La única excepción es el usuario del pod: un pod ejecuta cada uno de sus contenedores como podSecurityContext.runAsUser y runAsGroup, así que estos llegan a cada servicio que produce el Workload, incluidos los servicios sidecar y de inicialización.

Varios se corresponden con un campo de servicio de compose:

Campo del WorkloadCampo de Compose
podSecurityContext.runAsUser / runAsGroupuser ("1000", o 1000:3000 con un grupo) en cada servicio del Workload. Un contenedor que establece su propio securityContext.runAsUser se ejecuta en cambio como ese usuario en su propio servicio, con su propio runAsGroup donde establece uno
terminationGracePeriodSecondsstop_grace_period: <n>s
dnsConfig.nameservers / dnsConfig.searchesdns / dns_search
hostAliasesuna entrada extra_hosts por nombre de host, en el orden del autor
hostNetwork: truenetwork_mode: host

Ejecución en la red del nodo. Una carga de trabajo que declara hostNetwork: true obtiene network_mode: host en su propio servicio, y ese servicio queda entonces fuera de la red del límite en lugar de conectarse a ella: compose rechaza un servicio que declara a la vez networks: y network_mode:, así que ambos son alternativas y no adiciones. La consecuencia práctica es la que siempre conlleva la red del host — los pares ya no alcanzan el servicio por su nombre de servicio de compose en esa red, porque ya no está en ella; lo alcanzan en las direcciones propias del host, que es lo que pidió la declaración. Ningún otro servicio del límite se ve afectado.

Dos formas se combinan con ello. Un sidecar sigue nombrando el servicio principal (network_mode: "service:<main>"), así que sigue al servicio principal a la red del host sin declarar nada por sí mismo — del mismo modo en que los contenedores de un pod de Kubernetes comparten un solo espacio de nombres. Un servicio de inicialización no: se une a la red del límite por derecho propio, porque compartir el espacio de nombres del servicio principal haría circular la espera del servicio principal sobre él. Así, una carga de trabajo con hostNetwork y initContainers a la vez ejecuta su propio servicio en la red del host mientras sus servicios de inicialización permanecen en la red del límite, lo cual es más reducido que la forma de pod que modela; una advertencia unsupported-field nombra esa diferencia en lugar de dejar que se descubra en tiempo de ejecución.

El resto no tiene equivalente en un solo host. Ninguno se descarta en silencio: cada uno que se escribe genera una advertencia unsupported-field que nombra el campo, así que un autor sabe qué ajuste no pudo respetar el destino en lugar de descubrirlo en el stack en ejecución.

Campo del WorkloadPor qué compose no puede respetarlo
schedulingLa ubicación — nodeSelector, affinity, tolerations, topologySpreadConstraints — presupone un planificador que elige entre nodos. Compose se ejecuta en un solo host
replicasEl número de réplicas propio de compose está bajo deploy: y es una funcionalidad del modo swarm
runtimeClassNameSeleccionar un runtime de contenedores alternativo — uno habilitado para GPU, por ejemplo — no tiene expresión en compose
priorityClassNameEl orden de desalojo presupone un planificador
serviceAccountLa identidad de Workload es un concepto de clúster
imagePullSecretsLas credenciales de registro en un host de compose son el estado de inicio de sesión propio del host, no un campo del archivo
dnsPolicy, dnsConfig.optionsCompose expone dns y dns_search y nada más fino
podSecurityContext.fsGroup, podSecurityContext.supplementalGroupsuser lleva un usuario y un grupo; el grupo propietario de los volúmenes de un pod, y los grupos adicionales para sus procesos, no se traducen
podSecurityContext.runAsGroup, donde el pod no establece ningún runAsUser, o donde un contenedor — principal, sidecar o de inicialización — establece su propio runAsUser y ningún runAsGroupuser nombra un grupo solo junto a un usuario, y el usuario propio de un contenedor ocupa el lugar del del pod, así que el grupo del pod no llega a ningún servicio escrito de esa forma

El securityContext a nivel de contenedor se traduce parcialmente: readOnlyRootFilesystem → read_only, capabilities.add / drop → cap_add / cap_drop, runAsUser / runAsGroup → user. runAsNonRoot y allowPrivilegeEscalation no tienen expresión en compose y generan la misma advertencia unsupported-field, igual que un runAsGroup de contenedor escrito sin un runAsUser al lado: el servicio se ejecuta entonces como el usuario del pod donde el pod establece uno, sin ese grupo.

Cada advertencia de esta sección es orientativa y fuera de banda: la compilación se completa correctamente, y el archivo emitido es byte a byte lo que sería sin ella. --no-unsupported-field-warnings silencia la clase.

Contenedores de inicialización

Las entradas initContainers de un Workload se convierten en servicios propios, usando el modismo de ejecución hasta completarse de compose. Cada entrada añade un servicio, cuyo nombre se forma a partir de <component> y del name de la entrada con la misma nomenclatura que usan los sidecars — <component>--<container-name> para un nombre corriente; una entrada que omite name toma el nombre posicional init-<index> que documenta la referencia de Workload, y su nombre se forma a partir de él.

El orden que promete el contrato de autoría — los contenedores de inicialización se ejecutan hasta completarse en el orden en que están escritos, y cualquier otro contenedor arranca solo después de que todos hayan terminado — se expresa con la forma larga de depends_on:

  • Cada servicio de inicialización después del primero espera a su predecesor con condition: service_completed_successfully.
  • El servicio principal, y cada servicio sidecar, espera al último servicio de inicialización con la misma condición. Esperar al último es suficiente porque los servicios de inicialización forman una cadena.
  • Cada servicio de inicialización lleva restart: "no". Un servicio de inicialización se ejecuta una vez; un servicio que volviera a levantarse nunca alcanzaría el estado completado que esperan sus dependientes, así que una restartPolicy escrita en un contenedor de inicialización no cambia esto.
services:
platform:
image: platform:1.0
depends_on:
platform--verify-seed:
condition: service_completed_successfully
platform--import-seed:
image: platform:1.0
restart: "no"
platform--verify-seed:
image: platform:1.0
depends_on:
platform--import-seed:
condition: service_completed_successfully
restart: "no"

Un contenedor de inicialización se traduce exactamente como cualquier otro contenedor: su image (incluida la reescritura de registro que aplica una anotación aggrega.ai/image-registry), command, args, variables, attachments, volumeMounts y securityContext llegan todos al servicio de inicialización. Eso es lo que hace que la configuración que lleva un contenedor de inicialización — casi siempre un archivo que monta y escribe en un volumen que el contenedor principal también monta — sobreviva en el destino compose en lugar de perderse con el contenedor. Una forma que compose no puede expresar falla igual para un contenedor de inicialización que para uno ordinario: un lifecycle o envFrom declarado detiene la compilación con un error TRANSLATION_ERROR que nombra el contenedor de inicialización del que procede.

Dos diferencias respecto al servicio principal se derivan de que un servicio de inicialización es un servicio no principal:

  • Los campos del Workload a nivel de pod no se aplican, la misma regla que siguen los sidecars — salvo el usuario del pod, que llega a cada servicio como describe Campos a nivel de pod.
  • Un servicio de inicialización se une directamente a la red de su límite en lugar de compartir el espacio de nombres de red del servicio principal como hace un sidecar. Tiene que hacerlo: el servicio principal espera al servicio de inicialización, y compartir un espacio de nombres es en sí una dependencia del servicio principal, que cerraría la espera en un ciclo que compose se niega a iniciar. Por eso, un contenedor de inicialización alcanza otros servicios en la red del límite por nombre de servicio, pero no comparte el localhost del servicio principal.

Los servicios de inicialización y los servicios sidecar comparten un solo espacio de nombres, porque una sola nomenclatura nombra a ambos, así que una entrada initContainers y una entrada containers no pueden llevar el mismo nombre. Cuando lo hacen, el compilador se detiene con un TRANSLATION_ERROR que nombra el nodo, el nombre del contenedor y el nombre de servicio que ambos querían, en lugar de dejar que un servicio reemplace silenciosamente al otro.

Emitir la condición de completado no eleva ninguna versión mínima de Compose. condition y sus valores pertenecen a la Compose Specification base — a diferencia de los campos restart y required que los acompañan en el mismo bloque de forma larga, que la especificación asocia a versiones concretas de Compose. Cada versión mínima que pide la salida del proveedor compose llega con la construcción que la necesita: ≥ 2.23.1 para configs.content en línea, ≥ 2.26.0 para el subPath de un montaje (consulta Volúmenes), y 2.38 para los modelos. La primera alcanza cualquier salida de compose que lleve una config con content: en línea, que es como llegan tanto el archivo detrás de un volumen configmap como la config detrás de una arista entre redes con puente — no una sola ruta de autoría.

A qué red se une un servicio

Cada servicio se une a una red de Docker; los sidecars la heredan mediante su referencia network_mode al servicio principal. La red en la que acaba un nodo se lee de la anotación aggrega.ai/namespace de ese nodo, recurriendo a la ruta del archivo compose donde el nodo no lleva esa anotación — el directorio en el que se escribe el archivo bajo el directorio de salida de la compilación, como bridge/compose para un límite cuyo directory: es bridge. Así, cada nodo sin la anotación en un archivo compose se une a una sola red con el nombre de la ruta del archivo, sea cual sea el límite en el que se encuentre: los límites sin anotación que comparten un archivo compose comparten esa red, y aggrega.ai/namespace es lo que los separa. Los nodos que llevan anotaciones distintas acaban en una red por cada anotación distinta. Cómo se deriva un nombre de red es el nombre que produce esa identidad.

Cómo se deriva un nombre de red

Una red de compose es conectividad L3 compartida, y el bloque networks: de nivel superior une sus entradas por nombre — así que dos identidades que llegan a un mismo nombre se convierten en una sola red en la que están ambos conjuntos de servicios, que se alcanzan entre sí por nombre de servicio, sin nada en el archivo emitido que muestre que se pretendían dos redes. Por eso el nombre se construye a partir de la identidad que dice de qué red se trata: la anotación aggrega.ai/namespace del nodo, o la ruta del archivo compose donde el nodo no lleva ninguna.

Un nombre de red de compose acepta un conjunto de caracteres más reducido que el que puede llevar cualquiera de las dos identidades: letras, dígitos, puntos, guiones bajos y guiones. En lugar de sustituir un carácter que compose no acepta, la derivación lo escribe explícitamente, de modo que dos identidades que difieren en lo más mínimo llegan a dos redes — y un nombre puede leerse de vuelta en la identidad a partir de la que se construyó.

  • Una letra, un dígito, un punto y un guion bajo se conservan exactamente como se escribieron, con las mayúsculas y minúsculas con que se escribieron. Así, prod y Prod son dos redes, no una.
  • Un guion se mantiene tal como se escribió siempre que el carácter que lo sigue se conserve directamente y no sea una z minúscula. Un guion seguido de una z minúscula abre una secuencia de escape, así que uno escrito en esa posición se escribe a su vez explícitamente — api-zone se convierte en api-zhzone, que es lo que permite leer de vuelta cualquier nombre sin adivinar. Un guion sin nada detrás se escribe explícitamente por la misma razón, así que db- da db-zh.
  • Cualquier otro carácter se escribe como -z seguido de una letra que lo nombra: s para un separador de ruta, h para un guion que la regla anterior no mantiene. Todo lo demás — incluidos un espacio y una letra no ASCII — se escribe como x seguido del punto de código hexadecimal de seis dígitos del carácter, y un byte que no inicia ningún carácter como b seguido de su propio valor de dos dígitos, de modo que una identidad que no es texto válido se escribe igualmente de forma distinta en lugar de confundirse con otra.
  • Una identidad totalmente ausente — un nodo sin anotación aggrega.ai/namespace en un archivo compose sin ruta — se escribe -ze, que ninguna identidad escrita por un autor puede producir. Por eso, una red sin identidad nunca comparte conectividad con una que tiene una identidad escrita de alguna forma concreta.

Así, un namespace prod da la red prod, core-net da core-net, y un archivo compose en dist/app/compose da dist-zsapp-zscompose. Una entrada idéntica produce siempre el nombre idéntico.

Un namespace y la ruta de un archivo compose se escriben en el mismo espacio. Son dos formas de nombrar lo mismo — en qué red está un nodo — así que un nodo cuyo namespace es app/compose y un nodo sin namespace en el archivo compose en app/compose acaban deliberadamente en una sola red, exactamente como hacen dos límites que llevan la misma anotación aggrega.ai/namespace. Donde quieras mantener separados dos nodos, dales identidades que difieran.

Cambiar la identidad de un nodo renombra la red de compose, y compose no renombra una red en su sitio. La red se crea de nuevo con el nuevo nombre y cada servicio en ella se recrea para conectarse a ella, mientras la red antigua queda atrás hasta que algo la elimine. Una red no contiene datos, así que no se pierde nada — pero los contenedores en ella sí se reinician, y cualquier cosa que mantenga una conexión a través del cambio ve cómo se corta. Trata el cambio de una anotación de namespace, o del directorio en el que se escribe un archivo compose, como un nuevo despliegue que hay que planificar y no como un valor que se ajusta en su sitio.

Cuando dos límites confluyen en una sola ruta de ensamblado (directory: compartido), sus nodos sin una anotación aggrega.ai/namespace comparten la única red del archivo; da a cada límite su propia anotación aggrega.ai/namespace y el docker-compose.yaml fusionado declara una entrada networks: de nivel superior por anotación. Los servicios de límites distintos dentro del mismo archivo compose pueden comunicarse por sus nombres de servicio dentro de la resolución DNS predeterminada de compose, sujetos a las propias reglas de alcanzabilidad entre redes de compose. El enrutamiento L4 entre redes dentro de un solo archivo compose es lo que habilita la Feature compose-bridge de la biblioteca estándar, como contenido de catálogo del que este proveedor no contiene ninguna lógica: vinculada al límite ancestro común, su FeatureRecipe deriva un gateway de las aristas uses del límite cuyos dos extremos se ensamblan en su propio archivo compose y están en redes distintas de él — un servicio aggrega-gw cuya config nginx stream hace de proxy de cada arista con puente (un bloque server por arista, en el puerto del destino con un respaldo portBase en caso de colisión) — y su propio injectMapping reescribe la variable de entorno de host de cada consumidor a aggrega-gw:<port>, o a aggrega-gw con la variable de puerto reescrita al puerto de escucha donde la misma conexión entrega ambas. Esa reescritura reemplaza el valor que entregó la propia conexión del consumidor; si otra Feature vinculada al consumidor entregó la misma variable, la compilación se detiene nombrando ambas en lugar de reemplazarlo. El valuesMapping de la FeatureRecipe escribe esa config como una config de compose montada — una entrada configs: de nivel superior con content: en línea, referenciada desde el gateway y montada en /etc/nginx/nginx.conf; no es un montaje a cargo del operador — y nombra cada endpoint con puente bajo el x-aggrega-networks-of del gateway, que este proveedor resuelve en las redes en las que están ubicados esos endpoints (más abajo). Una arista cuyos dos extremos se ensamblan en dos archivos compose no pasa por el puente y conserva el nombre propio del destino; un límite sin nada que conectar por puente sigue llevando el gateway inactivo, sin config y sin otra red que la suya; y un bridge vinculado a un límite cuyo archivo compose no contiene ningún componente detiene la compilación en lugar de escribir el gateway en ninguna parte. La config stream lleva una directiva resolver y hace de proxy mediante una variable por arista (set $uN <host>; proxy_pass $uN) para que cada upstream se resuelva en el momento de la conexión y no una sola vez al arrancar — de lo contrario, un proxy_pass directo a un destino que aún no está en ejecución haría fallar el gateway al arrancar. (El $ de esas variables se escapa como $$ dentro de configs.content para que la interpolación $ propia de Docker Compose deje un $ literal para nginx.) configs.content en línea requiere Docker Compose ≥ 2.23.1. Consulta el patrón compose-bridge.

Unirse a las redes de otros componentes — x-aggrega-networks-of

Un servicio que escribe un fragmento — un archivo compose procedente de una fuente una vez fusionada su superposición, o un cuerpo artifacts: — puede unirse a las redes de otros componentes ensamblados en el mismo archivo compose nombrándolos bajo la clave de extensión x-aggrega-networks-of: una lista de IDs de componentes, los IDs que el Aggregate da a sus componentes, que una FeatureRecipe de ámbito de límite lee como las claves de .boundary.components y como el source y el target de sus listas de aristas .boundary. El proveedor resuelve cada ID en la red en la que está ubicado ese componente en este archivo, mediante la misma ubicación que recibe cada nodo, y añade esas redes al servicio, cada una una sola vez y en orden de nombre, antes de la red propia del servicio, a la que sigue uniéndose. La propia clave se omite del archivo ensamblado. El proveedor lee los IDs como referencias que resolver y nada sobre lo que hace el servicio, así que cualquier Recipe o FeatureRecipe puede usar la clave; el gateway del bridge de compose se une de este modo a las redes de los endpoints entre los que hace de relé.

# 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

Tres cosas detienen la compilación con TRANSLATION_ERROR cuando se ensambla el archivo, y cada una nombra el servicio:

  • Un ID que no lleva ningún componente ensamblado en este archivo — uno ensamblado en otro archivo compose, por ejemplo. Una red pertenece a un solo archivo, así que el mensaje nombra el ID y el archivo en el que está el servicio. Nombra solo componentes ensamblados en el mismo archivo, o elimina el ID.
  • Un valor que no es una lista de cadenas. La clave admite una lista de IDs de componentes, incluso para un solo ID.
  • La clave en un servicio que escribe network_mode. Compose no permite que un servicio con un network_mode se una a redes; elimina uno de los dos.

Inferencia de depends_on

El proveedor compose deriva depends_on automáticamente de las aristas uses del IR. Para cada arista cuyo origen y cuyo destino aportan ambos servicios al archivo compose combinado, el proveedor añade depends_on: [<target>] al servicio de origen.

La dependencia recae en el servicio propio del componente de origen, y en ningún otro servicio que ese componente aporte. Un componente que también declara contenedores de inicialización aporta un servicio que se ejecuta hasta completarse por cada entrada, y ninguno de ellos recibe la dependencia derivada de la arista — una arista nombra el componente, y un servicio de inicialización lleva un nombre propio. Así, un contenedor de inicialización que tiene que alcanzar el destino de la arista, como una migración de esquema contra una base de datos a la que el componente apunta con uses, no lleva ningún orden respecto a ese destino y puede ejecutarse antes de que sea alcanzable, mientras que el servicio propio del componente espera tanto a que la cadena de inicialización se complete como a que el destino se haya iniciado.

Las entradas derivadas de aristas se emiten sin condición: tienen la semántica service_started independientemente de que el destino declare un healthcheck. Condicionarlas a la salud del destino — lo que permitiría al runtime de compose bloquear el arranque hasta que el healthcheck del destino informe de que está sano — es expresable, y una arista uses no lo pide. Una oleada que nombra el mismo par es lo único que cambia la condición de una entrada derivada de una arista, y lo hace porque la oleada lo pide, no porque lo pida la arista.

Las entradas derivadas de aristas se emiten en orden alfabético de destino para la estabilidad de la salida. Las aristas cuyo origen o destino lo sirve otro proveedor (helm o helm-chart) se omiten — depends_on solo se aplica dentro del subconjunto de la Release servido por compose.

El depends_on de un servicio se emite en una de las dos formas de compose, nunca en una mezcla de ambas, porque compose exige una condición en cada entrada de la forma larga:

  • Lista en forma corta (depends_on: [<service-name>]) cuando ninguna entrada de ese servicio lleva una condición. Ese es el caso de todo servicio cuyas únicas dependencias provienen de aristas uses.
  • Mapeo en forma larga cuando alguna entrada lleva una — lo que ocurre cuando el servicio también espera a un contenedor de inicialización, o cuando una oleada de despliegue lo ordena. Ahí, las entradas derivadas de aristas emiten la condition: service_started explícita, que la Compose Specification define como el equivalente de la forma corta, así que su significado no cambia.

Dentro de un servicio, los orígenes mantienen su propio orden y no se intercalan: la espera de la cadena de inicialización, cuyo orden es aquel en que el autor escribió la lista, se emite primero, después las entradas derivadas de aristas en orden alfabético y después las derivadas de oleadas en orden alfabético.

Orden por oleadas de despliegue

El valor syncWave: de un límite de una Release ordena los servicios del archivo compose en el que se renderiza ese límite. Cada componente del límite hereda la oleada del límite, y donde varios límites comparten un mismo directory: — de modo que sus contribuciones se funden en un único docker-compose.yaml —, el archivo combinado contiene más de una oleada y el proveedor expresa el orden entre ellas como depends_on.

Cada servicio espera a todos los servicios de la oleada inmediatamente anterior que tenga servicios, y a ninguna oleada anterior a esa. Compose resuelve el resto de forma transitiva: un servicio de la oleada 2 espera a la oleada 1, que espera a la oleada 0, así que toda la secuencia queda ordenada mientras la lista propia de cada servicio se mantiene del tamaño de una oleada y no de todo el archivo. Las oleadas no tienen que ser contiguas, y los valores negativos son normales — -1 es una elección habitual para una migración que se ejecuta antes que todo lo demás.

La condición depende de lo que el destino puede satisfacer. Una oleada significa que el grupo anterior está en marcha antes de que el siguiente se inicie, lo cual es disponibilidad y no lanzamiento del proceso, así que:

  • donde el servicio de destino declara un healthcheck, la espera es condition: service_healthy;
  • donde no lo declara, la espera es condition: service_started, porque un servicio sin healthcheck nunca puede informar de que está sano y una espera condicionada a su salud nunca se satisfaría — el archivo nunca llegaría a arrancar.

La condición más débil es visible en el archivo emitido junto a la más fuerte, y la compilación además nombra cada uno de esos servicios en una advertencia, de modo que un autor que esperaba un orden por disponibilidad sabe qué parte de la oleada que declaró llega solo como orden de arranque. La advertencia es orientativa: la compilación tiene éxito y los bytes renderizados son exactamente los que serían sin ella. Añadir un bloque health: a ese contenedor es lo que refuerza la espera. --no-unsupported-field-warnings silencia la clase.

La oleada se sigue registrando como etiqueta. El orden se añade junto a la etiqueta aggrega.ai/sync-wave, no en su lugar: la etiqueta es donde quien inspecciona el archivo emitido ve de qué oleada proviene un servicio, algo que las entradas depends_on no indican.

Donde una oleada y una arista uses nombran el mismo par, una sola entrada lleva ambas. Compose acepta una entrada por dependencia, así que un servicio que apunta a un destino con uses y además está una oleada después de él emite una única entrada condicionada a la condición de la oleada — el requisito de la oleada es el más fuerte de los dos y es el que se expresa.

Un límite cuyos componentes están todos en una misma oleada no emite nada por esto. Tampoco una Release que no declara ningún syncWave: cada contribuidor lleva el valor predeterminado del campo, 0, el archivo combinado contiene una sola oleada, y la salida es exactamente la que sería si el proveedor no expresara ningún orden de oleadas.

El orden entre dos archivos compose no es expresable, y no se aproxima. depends_on nombra un servicio dentro del mismo archivo, y los límites que se evalúan a rutas de ensamblado distintas producen archivos docker-compose.yaml distintos que el runtime de compose trata como proyectos independientes. Así, una oleada ordena cada servicio del archivo en el que se renderiza y nada fuera de él. Secuenciar dos proyectos compose es asunto del operador, del mismo modo que el enrutamiento entre archivos; declarar un directory: compartido es lo que lleva dos límites a un solo archivo, y es una decisión sobre la forma de la salida que se toma por sus propias razones y no para obtener un orden.

Una arista uses que apunta a una oleada posterior se emite tal como está escrita, y se informa. El depends_on emitido refleja lo que se declaró — tanto las aristas uses como las oleadas. Una arista cuyo consumidor está en una oleada anterior a la del destino que usa afirma lo contrario de lo que afirman las oleadas: la arista hace que el consumidor espere al destino, mientras que las oleadas hacen que el destino espere, a través de cada oleada entre ellos, al consumidor. El archivo combinado expresa ambas cosas, lo que forma un conjunto de dependencias circulares que Docker Compose se niega a iniciar. La compilación nombra cada una de esas aristas en una advertencia que indica ambos servicios y ambas oleadas, de modo que el ciclo aflora al compilar y no en docker compose up. La advertencia es orientativa — la compilación tiene éxito y los bytes renderizados son exactamente los que serían sin ella — y --no-unsupported-field-warnings no la silencia, porque no se descartó nada: las dos declaraciones se expresan cada una, y juntas no pueden arrancar. Solo cubre el par directo: nombra los dos servicios que conecta una arista en lugar de rastrear todo el ciclo. Todo ciclo construido a partir de aristas uses y oleadas juntas pasa por al menos una de esas aristas, así que siempre se informa; un ciclo formado solo por aristas uses, sin ninguna oleada implicada, y uno cerrado por una entrada depends_on escrita en un archivo compose que aporta la Recipe se emiten tal como están escritos y no se informan. Mantén coherentes la dirección de las aristas y el orden de las oleadas: coloca al consumidor en la oleada del destino o en una posterior, o el destino en la oleada del consumidor o en una 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 no nombra a migrator: el orden alcanza la oleada inmediatamente anterior y compose encadena el resto a través de store.

Modo con fuente

El source: del proveedor compose nombra un archivo YAML de docker-compose que el proveedor puede leer y analizar, y acepta las dos formas que adopta el campo source:: una cadena simple con una ruta del sistema de archivos, y un objeto estructurado cuyo url: lleva la ubicación. Siempre que esa ubicación sea una ruta del sistema de archivos, se ancla al directorio que contiene el recipe.yaml que la declara, no al directorio desde el que se invoca la compilación, y debe permanecer dentro de ese directorio: una ruta que sale de él, o una absoluta, se rechaza, porque todo archivo que lleva una publicación de la Recipe se toma de su directorio — consulta entities/recipe.md «Content paths stay inside the Recipe’s own directory (Las rutas de contenido permanecen dentro del propio directorio de la Recipe)». El archivo nombrado de esta forma se publica con la Recipe, mientras que un archivo junto a la Recipe que nada de lo que ella declara nombra no se publica.

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

En la forma estructurada, lo que lleva url: decide si se obtiene algo. Un fragmento publicado a través de https:// se obtiene y se fija con kind: compose-https-fragment; aggrega pull lo adquiere y la compilación lo lee de la caché. Un url: que nombra una ruta del sistema de archivos no se obtiene — se lee del disco, anclado exactamente como la forma de cadena simple anterior, y aggrega pin registra el digest del archivo que nombra en el archivo entity.lock junto a la Recipe, que una compilación compara después antes de leer el fragmento. Copiar localmente un fragmento remoto (vendoring) y apuntar source: a la copia local se admite como alternativa a la obtención, y no es obligatorio. El esquema acepta un objeto estructurado abierto.

Una Recipe con source: <path-to-compose-file> y valuesMapping: ejecuta el siguiente pipeline:

  1. El archivo compose base en <path> se lee y se analiza como YAML.
  2. La plantilla valuesMapping se evalúa con el contexto de plantilla de la Recipe. Su salida se trata como un documento de superposición compose — un archivo compose parcial que amplía o sobrescribe campos de la base.
  3. La base y la superposición se combinan en profundidad usando la semántica de superposición nativa de docker-compose.

Las reglas de la combinación en profundidad:

  • Escalares: gana la superposición. Cuando tanto la base como la superposición establecen el mismo campo escalar, el valor de la superposición reemplaza el valor de la base.
  • Mapas: combinación recursiva. Cuando tanto la base como la superposición establecen el mismo campo de mapa, la combinación desciende recursivamente en el mapa. Las claves presentes en ambas siguen las mismas reglas; las claves presentes solo en una se conservan tal cual.
  • Listas: reemplazo. Cuando tanto la base como la superposición establecen el mismo campo de lista, la lista de la superposición reemplaza por completo la lista de la base (sin combinación elemento por elemento ni anexado). Esto coincide con el comportamiento de docker compose -f base.yaml -f overlay.yaml config.
  • null: reemplaza, y permanece. Una clave que la superposición establece en null en un servicio — una de las claves propias del servicio, como user, command o healthcheck, una entrada de environment, una etiqueta, o una clave directamente bajo healthcheck o deploy — reemplaza el valor de la base como cualquier escalar y se escribe en el archivo compose como key: null; no elimina la clave. Donde el proveedor escribe un valor propio en esa clave, el archivo lleva en su lugar el valor del proveedor: labels: null deja las etiquetas de procedencia que el proveedor estampa, y networks: null la red que conecta. Un null escrito en cualquier otro lugar de la superposición queda fuera de esta regla. Lo que significa entonces un null es la lectura que Compose hace de ese atributo — una entrada de environment sin valor, por ejemplo, toma su valor del entorno en el que se ejecuta docker compose.

Toda etiqueta que escribió el autor de un servicio se conserva. Las labels: de un servicio en el archivo base o en la superposición pueden escribirse como un mapa o como la lista de entradas key=value de Compose, y cada etiqueta llega al archivo compose junto a las etiquetas de procedencia que el proveedor estampa. Una entrada de lista se lee como la lee Compose: el texto antes de su primer = nombra la etiqueta y el texto después es el valor, y una entrada sin = es una etiqueta con valor vacío. Un número o un valor true/false se escribe como su texto, así que replicas-hint: 2 llega al archivo como replicas-hint: "2", y una etiqueta escrita como null sigue siendo null. Donde una etiqueta escrita por el autor y una etiqueta de procedencia comparten una clave, el archivo lleva el valor de procedencia. Un valor de labels: que no es ni un mapa ni una lista, y una entrada de lista que no es texto, detienen la compilación, nombrando el archivo de origen y el servicio. Las etiquetas de servicio del cuerpo de un artifacts: adoptan la forma de mapa: una lista ahí detiene la compilación, nombrando el artefacto y el servicio.

El documento combinado pasa después a la combinación a nivel de Release junto con cualquier contribución en modo sintetizado, con la misma red por límite y la misma inferencia de depends_on.

Dejar fuera servicios, volúmenes y configs. La superposición no puede eliminar nada del archivo base — un valor de superposición reemplaza, nunca borra — así que un archivo obtenido que incluye un servicio que la Release no debe ejecutar es precisamente para lo que sirven las entradas omits: de una Recipe o de una FeatureRecipe. Este proveedor las respeta en este modo y en ningún otro: un Workload sintetizado y un cuerpo de artifacts: se renderizan sin ellas. Una entrada nombra una unidad de nivel superior del archivo por su kind — service, volume o config — y su name, la clave de la unidad bajo services:, volumes: o configs:, comparada de forma exacta. Un archivo compose no tiene espacios de nombres, así que una entrada que lleva un namespace, igual que una que nombra cualquier otro tipo, detiene la compilación cuando se renderiza el componente, nombrando la entrada y los tipos que este proveedor acepta; cada entrada se comprueba antes de dejar nada fuera. Las entradas se cotejan con el archivo una vez que la superposición anterior se ha combinado en él, así que una unidad que añadió la superposición se deja fuera exactamente igual que una que declaró la base, y antes de que el proveedor añada nada propio, así que una entrada nunca nombra eso. Una unidad que nombra una entrada se elimina, y una sección cuyas unidades se dejan fuera todas se elimina con ellas; toda otra unidad se escribe exactamente como lo sería sin las entradas. Las entradas alcanzan el archivo de la Recipe o de la FeatureRecipe que las declara y nada más: lo que otro componente o una Feature vinculada aporta al mismo docker-compose.yaml queda intacto, incluida una unidad con la misma clave. El proveedor informa de cuántas unidades dejó fuera cada entrada, y una entrada que no dejó ninguna fuera detiene la compilación; consulta An omits entry left out nothing the source rendered (Una entrada omits no dejó fuera nada de lo que renderizó la fuente).

Una unidad que se deja fuera no debe seguir nombrada por lo que queda, porque compose rechaza un archivo que nombra un servicio, un volumen o una config que no declara. Una vez eliminadas las unidades, toda referencia que el archivo siga haciendo a una de ellas detiene la compilación, y el mensaje nombra cada servicio o job que hace la referencia, la unidad que nombra y el campo en el que está la referencia. Una referencia es lo que la Compose Specification define como una entrada de un archivo que nombra a otra:

  • un servicio, nombrado por depends_on en cualquiera de sus formas, por links (SERVICE o SERVICE:ALIAS), por volumes_from (SERVICE o SERVICE:MODE), por network_mode, ipc, pid o uts establecido en service:<name>, por extends que nombra un servicio del mismo archivo, o por un valor service:<name> de build.additional_contexts;
  • un volumen, nombrado como origen de una entrada volumes: — la forma corta SOURCE:TARGET donde el origen es un nombre y no una ruta, y la forma larga de type: volume;
  • una config, nombrada por una entrada configs:, en cualquiera de sus formas.

También se leen los hooks pre_start de un servicio y cada entrada jobs: de nivel superior, por las referencias que la especificación permite llevar a cada uno de ellos. Algunos valores solo parecen referencias y no se leen como tales: una entrada volumes_from o network_mode que empieza por container: nombra un contenedor, external_links nombra un contenedor que este archivo no declara, un extends con un file: nombra un servicio de otro archivo, y un credential_spec.config puede nombrar una config que guarda la plataforma y no el archivo. Cada valor se compara tal como está escrito, así que una referencia escrita mediante un ${VARIABLE} no es una que esta comprobación vea, y una referencia a una unidad que el archivo nunca declaró se deja como está.

La comprobación lee únicamente el archivo propio de la Recipe o FeatureRecipe que declara, así que una referencia a un servicio dejado fuera detiene la compilación incluso donde otro contribuidor en la misma ruta de ensamblado declara un servicio con ese nombre. Para conservar la referencia, conserva la unidad. Para eliminarla, cambia la entrada que hace la referencia mediante valuesMapping: — una lista ahí reemplaza la lista del archivo base, así que depends_on: [] vacía una — o deja fuera también el servicio que hace la referencia.

Salida por (path, provider)

Cada ruta de ensamblado de compose produce un docker-compose.yaml. Los límites que se evalúan en rutas distintas producen archivos compose distintos; los límites que comparten una ruta evaluada producen un único archivo compose fusionado que contiene a cada contribuidor en esa ruta. La ruta es el directory: del límite unido al subDirectory: por componente (cuyo valor predeterminado es {{ .capability }}, de modo que los contribuidores de compose quedan por defecto bajo una subcarpeta compose/).

Las colisiones de nombres de servicio dentro de una sola ruta de ensamblado detienen la compilación. Cuando dos nodos distintos aportan servicios con el mismo ID de instancia en la misma tupla (path, provider), el compilador se detiene y el diagnóstico nombra cada tupla (boundary, node) contribuyente en orden alfabético. El autor resuelve la colisión renombrando uno de los contribuidores (normalmente ajustando el identificador del nodo para que el sintetizador produzca un nombre de servicio distinto), o dirigiendo los contribuidores a rutas distintas mediante declaraciones directory: diferentes.

Los volúmenes de nivel superior se unen dentro de una ruta de ensamblado, y dos contribuidores pueden declarar un mismo nombre siempre que estén de acuerdo sobre él. Un contribuidor es un fragmento, así que dos fragmentos de un mismo componente — su propio archivo compose y una entrada artifacts:, o dos entradas artifacts: — son dos contribuidores exactamente como lo son dos componentes. Un volumen con nombre es un único volumen físico, así que dos declaraciones idénticas describen ambas exactamente la entrada con la que acaba el archivo ensamblado, y este conserva una sola entrada con ese nombre. Un volumen que el proveedor derivó no lleva ningún cuerpo, así que dos de ellos coinciden trivialmente, y en cualquier caso no pueden encontrarse (consulta Cómo se deriva un nombre de volumen).

Una entrada volumes: escrita por el autor es la que hay que vigilar, porque puede llevar un cuerpo propio — un driver, driver_opts o labels. Cuando dos contribuidores declaran un mismo nombre con cuerpos diferentes, la compilación se detiene con TRANSLATION_ERROR, nombrando el volumen y cada tupla (boundary, node, fragment) contribuyente. Cuando dos autores discrepan sobre un único volumen, no hay ninguna respuesta entre la que el ensamblador pueda elegir: conservar cualquiera de los dos cuerpos descarta lo que escribió el otro autor, en una compilación que de otro modo tendría éxito. Resuélvelo haciendo idénticas las dos declaraciones, cuando ambos autores se referían al mismo volumen, o renombrando una de ellas, cuando se referían a dos. Las redes de nivel superior son una por cada anotación aggrega.ai/namespace distinta, más una con el nombre de la ruta del archivo compose para los nodos que no llevan ninguna, nombradas según Cómo se deriva un nombre de red; dos límites contribuyentes con la misma anotación aggrega.ai/namespace se fusionan en una sola red compartida por ambos, igual que dos límites sin anotación que comparten el archivo.

Cada clave que escribe un fragmento se lleva o se rechaza

Un fragmento — un archivo compose procedente de una fuente una vez fusionada su superposición, o un cuerpo artifacts: que se evalúa como YAML de compose — llega al docker-compose.yaml ensamblado solo a través de las claves que el proveedor lleva, y ese conjunto es fijo. Cada clave que escribe un fragmento se lleva al archivo ensamblado tal como está escrita o se rechaza por su nombre; ninguna se deja fuera sin decir nada. Un fragmento es un solo archivo compose, así que es un solo documento YAML.

  • Llevadas. En el nivel superior: services, volumes, configs y models. En un servicio: 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 y profiles. Dentro de los bloques que describe el proveedor: deploy.resources con sus limits (cpus, memory) y reservations (cpus, memory, devices, y de cada entrada de dispositivo driver, count, device_ids, capabilities y options); test, interval, timeout, retries y start_period de un healthcheck; type, source, target, read_only y volume.subpath de una entrada volumes: en forma larga; source y target de una entrada configs: en forma larga; condition de una entrada depends_on: en forma larga; driver, driver_opts y labels de un volumen de nivel superior; content de una config de nivel superior. El cuerpo de un modelo y la entrada models: en forma larga de un servicio llevan cada miembro, como describe Modelos. Un miembro de extensión — una clave que empieza por x- — se lleva en el nivel superior y en un servicio, como describe Miembros de extensión.
  • Rechazadas. Cualquier otra clave — stdin_open en un servicio, un secrets: o un name: de nivel superior, deploy.replicas, un restart: o un required: dentro de una entrada depends_on: en forma larga, una clave x- dentro del cuerpo de un volumen de nivel superior o de un healthcheck — detiene la compilación con TRANSLATION_ERROR, nombrando cada una de esas claves, su ruta en el fragmento (services.migrate.stdin_open), el fragmento y el componente, y nombra los dos lugares de los que procede una clave así. Uno es el propio fragmento, y la corrección es eliminar la clave de él. El otro es una Recipe procedente de una fuente que no declara ningún valuesMapping:: los valores del nodo se superponen entonces al archivo compose tal cual, de modo que cada clave de valor llega como una clave de nivel superior del fragmento, y la corrección es declarar un valuesMapping: que coloque cada valor bajo una clave que el proveedor lleva. Una clave que una clave de fusión de YAML (<<: *anchor) introduce en un bloque se juzga donde llega, como si estuviera escrita allí. Un fragmento renderizado desde la fuente se llama <component>.compose-fragment.yaml; un fragmento artifacts:, por el nombre que le da su Recipe.
  • Rechazada en su totalidad: una red propia del fragmento. Una entrada bajo los networks: de nivel superior de un fragmento detiene la compilación con TRANSLATION_ERROR sea cual sea el contenido de su cuerpo — una entrada vacía, un driver, cualquier otra cosa — nombrando la entrada (networks.back), el fragmento y el componente, porque el archivo ensamblado solo contiene las redes que deriva el proveedor (consulta A qué red se une un servicio). Elimina la entrada: un servicio se une a la red de su propio componente sin declarar nada, la anotación aggrega.ai/namespace elige a qué red se une un componente, un servicio nombra los componentes a cuyas redes también se une bajo x-aggrega-networks-of, y la Feature compose-bridge enruta entre servicios de redes distintas. Un networks: {} vacío no declara nada y no se rechaza, y la propia lista networks: de un servicio se lleva como se indica arriba.
  • Rechazado en su totalidad: un fragmento de más de un documento. Un cuerpo artifacts: que contiene dos o más documentos YAML separados por --- detiene la compilación con TRANSLATION_ERROR, nombrando el fragmento, el componente y cuántos documentos contiene, porque la fusión lee un fragmento como un solo archivo compose y cada documento posterior al primero faltaría de otro modo en el archivo ensamblado. Escribe el fragmento como un solo documento, o da a cada documento su propia entrada artifacts:. Un documento que no contiene nada — el vacío que abre un --- final — no se cuenta. Un archivo compose procedente de una fuente con varios documentos nunca se convierte en un fragmento así: se rechaza cuando se lee el archivo.

El proveedor no lee el significado de ninguna clave: una clave se lleva porque está en el conjunto anterior y se rechaza porque no lo está.

Los miembros de extensión se llevan tal como están escritos

La Compose Specification reserva las claves que empiezan por x- para extensiones: datos que una herramienta que lee el archivo puede usar y que el propio Compose ignora. Los miembros de extensión de un fragmento en el nivel superior y en un servicio llegan al archivo ensamblado tal como están escritos, después de cada clave que el proveedor modela en ese nivel, en el orden en que el fragmento los contiene; el proveedor no lee nada dentro de ellos, salvo el x-aggrega-networks-of de un servicio, que resuelve en las redes a las que se une el servicio y deja fuera del archivo ensamblado (consulta Unirse a las redes de otros componentes). Un cuerpo artifacts: los contiene en el orden en que los escribe. Las claves de un archivo compose procedente de una fuente llegan a su fragmento en orden de nombre una vez fusionada su superposición, así que sus miembros de extensión se escriben en orden de nombre.

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

Un miembro alcanzado a través de un alias de YAML se escribe completo, y no se lleva ningún ancla, de modo que el archivo ensamblado nunca contiene un alias cuya ancla le falte; esto es lo que permite que un miembro de nivel superior contenga un ancla que incorpora la clave de fusión de un servicio (<<: *base). Los miembros de un servicio viajan con su servicio. Los miembros de nivel superior se unen dentro de una ruta de ensamblado según la regla que siguen los volúmenes: dos fragmentos que escriben un mismo miembro con el mismo contenido dejan una sola entrada, tanto si lo escriben en estilo de bloque como de flujo, y dos que lo escriben con contenido distinto detienen la compilación con TRANSLATION_ERROR, nombrando el miembro y cada tupla (boundary, node, fragment) contribuyente — incluidos dos fragmentos de un mismo componente. Haz idénticas las dos declaraciones, o da a una de ellas un nombre distinto.

profiles condiciona un servicio a un perfil de Compose. Un servicio que enumera profiles: es uno que docker compose up deja de lado a menos que uno de sus perfiles esté habilitado, y que docker compose run --rm <service> inicia a petición — la forma compose de una tarea que se ejecuta bajo demanda. La lista se lleva tal como la escribe el fragmento, en su orden:

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

Modelos

La sección models: de nivel superior de un archivo compose declara los modelos de IA que usan los servicios del archivo, y a un servicio se le concede un modelo mediante su propia entrada models:. El proveedor lleva ambos de un fragmento al docker-compose.yaml ensamblado, en la grafía propia de Compose, tanto si el fragmento es un archivo compose procedente de una fuente como un cuerpo artifacts: que se evalúa como YAML de compose. Un Workload no declara ningún modelo, así que una Recipe en modo Workload no aporta ninguno.

  • El cuerpo de un modelo se escribe tal como lo escribió el fragmento. model — el identificador del artefacto OCI del modelo — context_size y runtime_flags conservan sus nombres, y cualquier otro miembro, entre ellos una extensión x-, se lleva junto a ellos. Dentro de un modelo, los tres miembros nombrados van primero y el resto sigue en orden de clave, y los modelos se escriben en orden de nombre, de modo que una entrada idéntica produce un archivo idéntico byte a byte. El proveedor no lee nada en el cuerpo: no comprueba el identificador, y no sabe nada de lo que servirá el modelo.
  • La referencia de un servicio conserva su forma. La forma corta enumera nombres de modelos (models: [llm]); la forma larga asigna a cada modelo endpoint_var y model_var, los nombres de las variables que reciben la dirección del model runner y el identificador del modelo. Cualquiera de las dos se escribe en la forma y el orden que usó el fragmento, y viaja con su servicio. Cuando la forma larga deja una variable sin nombre, Compose le da nombre al ejecutar el archivo.
  • Los modelos se unen dentro de una ruta de ensamblado, según la regla que siguen los volúmenes. Dos contribuidores que declaran un mismo nombre de modelo con cuerpos que se emiten de forma idéntica dejan una sola entrada con ese nombre; dos que lo declaran con cuerpos diferentes detienen la compilación con TRANSLATION_ERROR, nombrando el modelo y cada tupla (boundary, node, fragment) contribuyente. Aquí también dos fragmentos de un mismo componente son dos contribuidores. Haz idénticas las declaraciones cuando ambos contribuidores se refieren a un mismo modelo, o da a una de ellas un nombre distinto.
  • Cada referencia nombra un modelo declarado. Una vez unidos los fragmentos de la ruta de ensamblado, un servicio al que se concede un modelo que ningún contribuidor en esa ruta declara detiene la compilación con TRANSLATION_ERROR, nombrando el servicio y el modelo. La comprobación se ejecuta sobre la unión completa, así que un componente puede conceder a su servicio un modelo que declara otro componente en la misma ruta de ensamblado.
  • Una entrada omits: no puede dejar fuera un modelo. service, volume y config son los tipos que acepta este proveedor, y una entrada que nombra un modelo detiene la compilación como una que nombra cualquier otro tipo.

Los modelos se sirven cuando se ejecuta el archivo, no cuando se compila. Docker Compose 2.38 o posterior, en una plataforma que admite modelos de Compose como Docker Model Runner, descarga y ejecuta cada modelo concedido a un servicio, dejando fuera cualquier otro a menos que se inicie con --all-resources, y establece, en cada servicio al que se concede, las variables que nombra su referencia con la dirección del model runner y el identificador del modelo. La compilación no puede ver el host que ejecutará el archivo, así que no comprueba ni la versión de Compose ni la plataforma: un archivo que lleva modelos se ensambla de la misma manera sea lo que sea lo que lo ejecute.

Una Feature vinculada a un componente contribuye al mismo archivo

Una Feature vinculada a un componente aporta sus servicios al docker-compose.yaml en el que se ensambla su componente anfitrión, en las mismas condiciones que la propia Recipe del anfitrión. No hay ningún segundo archivo junto a él: una ruta de ensamblado produce un solo documento, así que los servicios de una Feature vinculada o están en ese documento o no se despliegan en absoluto. Desvincular la Feature elimina exactamente esos servicios y deja intactos los propios del componente anfitrión.

Son contribuidores en esa ruta de ensamblado como cualquier otro, así que todo lo anterior se aplica a ellos sin cambios — la regla de los nombres de servicio, y el requisito de que dos contribuidores que declaran un mismo nombre de volumen o de config de nivel superior estén de acuerdo sobre lo que es. También se unen a la misma red que el resto del límite, de modo que un componente y una Feature vinculada a él se alcanzan mutuamente por nombre de servicio sin nada más que declarar.

Cada servicio que aporta una Feature lleva la identidad compuesta para esa vinculación en lugar de la del componente anfitrión, de modo que ambos siguen siendo distinguibles dentro de un documento al que ambos contribuyeron. Etiquetas y anotaciones explica cómo se construye esa identidad.

Este es un mecanismo distinto del bloque attachments: a nivel de contenedor de un Workload, y es fácil leer los dos como uno solo porque comparten una palabra. Vincular una Feature a un componente añade servicios al documento ensamblado; la entrada attachments: de un contenedor lee una credencial que un slot publicó en ese único contenedor, y se trata en Campos del contenedor.

Fragmentos compose emitidos como artefactos

Cuando el bloque artifacts: de una Recipe se evalúa como YAML de compose — un fragmento que lleva sus propios bloques services:, volumes:, configs:, models: o networks: (cada entrada en línea o cargada por entrada con $import:) —, la fusión en el ensamblado por (path, provider) sigue reglas específicas de cada forma:

  • Los services: de los artefactos se fusionan en el archivo compose ensamblado junto a los servicios por componente. Un nombre de servicio aportado por dos componentes distintos en la misma ruta de ensamblado detiene la compilación, y el diagnóstico nombra a cada contribuidor. Una colisión dentro de un solo componente — entre el propio fragmento de artefacto de ese componente y los servicios sintetizados para él — no se detecta, y la contribución posterior reemplaza a la anterior, así que mantén el nombre de un servicio escrito en un artefacto distinto de los nombres <component> y <component>--<container-name> que produce el sintetizador (consulta Cómo se nombra un servicio sidecar o de inicialización).
  • Los volumes: de los artefactos se fusionan en el bloque volumes: de nivel superior. Dos entradas que llegan a un mismo nombre dejan una sola entrada bajo él cuando lo declaran de forma idéntica, con la misma regla que los volúmenes por componente; dos que lo declaran de forma distinta detienen la compilación, tanto si proceden de dos componentes como de dos fragmentos de uno mismo — dos de sus entradas artifacts:, o una de ellas y el propio archivo compose del componente. Como un fragmento de artefacto escribe sus propios cuerpos, esta es la vía en la que es más probable que dos contribuidores discrepen. Mantén el nombre de un volumen escrito en un artefacto distinto de los demás en su ruta de ensamblado, incluida la forma <component>--<volume-name> que produce la derivación — salvo que dos contribuidores deban describir un único volumen compartido, en cuyo caso sus declaraciones deben coincidir.
  • Los configs: de los artefactos se fusionan en el bloque configs: de nivel superior. Así es como el archivo detrás de un volumen configmap llega al ensamblado: el volumen se convierte en una referencia configs: a nivel de servicio que nombra el configmap, y el fragmento de artefacto declara una entrada con ese nombre con content: en línea. Una vez unidos los fragmentos de la ruta de ensamblado, cada referencia a nivel de servicio debe resolverse en una entrada declarada, o la compilación se detiene con TRANSLATION_ERROR nombrando cada referencia no resuelta — el servicio, el nombre de la config y la ruta de montaje. La comprobación se ejecuta sobre la unión completa y no por componente, así que un componente puede referenciar una config que declara otro componente en la misma ruta de ensamblado. La unión se concilia por nombre cuando los contribuidores coinciden: dos que declaran un mismo nombre de config con un content: idéntico dejan la única entrada que ambos describieron. Dos que declaran un mismo nombre con un content: distinto detienen la compilación con TRANSLATION_ERROR, nombrando la config y cada tupla (boundary, node, fragment) que contribuye, incluidos dos fragmentos de un mismo componente — una entrada de config siempre lleva contenido, así que conservar cualquiera de las dos declaraciones descartaría un archivo que escribió un autor. Mantén un nombre de config distinto entre todos los contribuidores de su ruta de ensamblado, o haz idénticas las declaraciones cuando dos contribuidores deban entregar un único archivo compartido.
  • Los models: de los artefactos se fusionan en el bloque models: de nivel superior, y la referencia models: de un servicio viaja con su servicio, según las reglas de Modelos: dos contribuidores que declaran un mismo nombre de modelo deben declararlo de forma idéntica, y cada referencia debe nombrar un modelo que declare algún contribuidor de la ruta de ensamblado.
  • Los networks: de los artefactos se rechazan. El proveedor compose deriva las redes de las anotaciones del límite (una red por cada anotación aggrega.ai/namespace distinta, más una con el nombre de la ruta del archivo compose, a la que se une cada nodo que no lleva ninguna, cada una nombrada según Cómo se deriva un nombre de red), así que una declaración de red aportada por un artefacto no tiene cabida en el archivo ensamblado: cualquier entrada detiene la compilación, nombrando la entrada y el fragmento, según las reglas de Cada clave que escribe un fragmento se lleva o se rechaza. Elimina la entrada y da forma a las redes mediante la anotación aggrega.ai/namespace, o haz que un servicio se una a las redes de componentes nombrados mediante x-aggrega-networks-of; los autores que necesitan enrutamiento entre redes dentro de un solo archivo compose usan la Feature compose-bridge.
  • Los miembros de extensión de los artefactos se llevan. Una clave x- de nivel superior se escribe después de las demás secciones del archivo ensamblado, en el orden en que se escribió, según las reglas de Los miembros de extensión se llevan tal como están escritos.
  • Cualquier otra clave de nivel superior de los artefactos detiene la compilación. services:, volumes:, configs:, models: y los miembros de extensión son todo lo que el ensamblador lleva de un fragmento. Un bloque secrets: y un name: de nivel superior detienen cada uno la compilación nombrando la clave y el fragmento, según las reglas de Cada clave que escribe un fragmento se lleva o se rechaza.
  • Un cuerpo artifacts: es un solo documento. Un cuerpo que contiene varios documentos YAML detiene la compilación nombrando el fragmento y cuántos documentos contiene; da a cada documento una entrada artifacts: propia.

La asimetría entre los cuatro primeros y networks: es estructural: services:, volumes:, configs: y models: llevan contenido por Recipe que el ensamblador acumula en el archivo ensamblado; networks: es infraestructura por límite que el ensamblador deriva del estado del límite. Los artefactos pueden extender los primeros; solo las anotaciones del límite pueden dar forma a la segunda, y por eso se rechaza la propia entrada de red de un artefacto. Los miembros de extensión son datos que la Compose Specification define para otras herramientas, así que se llevan tal como están escritos. Todo lo demás es una forma para la que el documento ensamblado no tiene cabida, y por eso se rechaza en lugar de fusionarse.

Lo que el proveedor compose no entrega

  • Enrutamiento L4 entre redes dentro de un archivo compose. El proveedor coloca cada nodo en su red y une un servicio a las redes que nombra x-aggrega-networks-of, y no enruta nada entre redes por sí mismo. Un servicio de la red A que llega a un servicio de la red B por cualquier medio distinto del DNS predeterminado de docker-compose requiere la Feature compose-bridge, cuya FeatureRecipe escribe el gateway y la reescritura.
  • Enrutamiento entre archivos compose. Los límites que se evalúan a rutas de ensamblado distintas producen archivos docker-compose.yaml distintos; el runtime de compose los trata como proyectos independientes, y la Feature compose-bridge deja una conexión entre dos archivos tal como está escrita. La comunicación entre archivos es asunto del operador (publicar puertos del host, compartir redes externas o hacer confluir los límites en una sola ruta mediante un directory: compartido).
  • Obtener una variable de entorno de una vinculación. Compose no tiene una primitiva para ello, así que una entrada attachments de un Workload con as: env emite el nombre de la variable con un valor vacío en lugar de una referencia resuelta en tiempo de ejecución. El marcador de posición es deliberado — una variable presente pero vacía es visible para quien depure el contenedor, mientras que una ausente no deja nada que examinar — y la compilación lo indica en lugar de dejar que se descubra: cada una de esas entradas genera una advertencia unsupported-field que nombra la entrada en su coordenada de autoría (containers.<name>.attachments.<KEY>, o initContainers[<i>].attachments.<KEY>), para que el autor sepa qué variable llega vacía y a qué contenedor pertenece. La advertencia es orientativa: la compilación se completa, y el archivo renderizado es byte por byte lo que sería sin ella. --no-unsupported-field-warnings silencia la clase. Una entrada attachments con as: file no se ve afectada — compose la monta como bind mount, y no se genera ninguna advertencia.
  • Contenido deploy: del modo swarm. Las réplicas, las restricciones de ubicación y la estrategia de actualización bajo deploy: son funcionalidades del modo swarm, y el proveedor compose solo apunta a compose en un único host, así que no emite ninguna de ellas. Sí emite deploy.resources — las reservas y los límites a los que corresponden los resources de un contenedor, que docker compose respeta fuera del modo swarm (consulta Recursos de los contenedores).
  • depends_on condicionado al estado de salud a partir de una arista uses. Una dependencia derivada de una arista uses se emite sin condición, con la semántica service_started; no está condicionada a que el healthcheck del destino informe de que está sano. Se trata de lo que significa una arista uses, no de una forma que el proveedor no pueda producir: la forma larga se emite para la espera de un contenedor de inicialización, y una oleada de despliegue sí condiciona la espera a la salud del destino cuando el destino declara un healthcheck.

Ejemplo de autoría

Un despliegue compose de dos servicios con una arista 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

El proveedor compose produce un único docker-compose.yaml en la ruta evaluada del límite (de forma predeterminada dist/boundaries/production/compose/docker-compose.yaml, porque el directory: de un límite tiene como valor predeterminado dist/boundaries/<name> y subDirectory:, {{ .capability }}) que contiene:

  • services.api (el servicio api principal, red prod, puertos 8080:8080, healthcheck mediante curl, depends_on: [db])
  • services.db (el servicio db principal, red prod)
  • networks.prod (la red docker del límite)