Define servicios en Docker Compose

Un servicio es una definición abstracta de un recurso informático dentro de una aplicación que se puede escalar o reemplazar independientemente de otros componentes. Los servicios están respaldados por un conjunto de contenedores, ejecutados por la plataforma de acuerdo con los requisitos de replicación y las restricciones de ubicación. Dado que los servicios están respaldados por contenedores, se definen mediante una imagen de Docker y un conjunto de argumentos de tiempo de ejecución. Todos los contenedores de un servicio se crean de manera idéntica con estos argumentos.

Un archivo de Compose debe declarar un elemento de nivel superior services como un mapa cuyas claves son representaciones de cadenas de los nombres de los servicios, y cuyos valores son definiciones de servicios. Una definición de servicio contiene la configuración que se aplica a cada contenedor de servicio.

Cada servicio también puede incluir una sección build, que define cómo crear la imagen de Docker para el servicio. Compose admite la construcción de imágenes de Docker utilizando esta definición de servicio. Si no se utiliza, la sección build se ignora y el archivo de Compose se sigue considerando válido. El soporte de compilación es un aspecto opcional de la especificación de Compose y se describe en detalle en la documentación de la Especificación de compilación de Compose (Build).

Cada servicio define restricciones y requisitos de tiempo de ejecución para ejecutar sus contenedores. La sección deploy agrupa estas restricciones y permite a la plataforma ajustar la estrategia de despliegue para que coincida mejor con las necesidades de los contenedores y los recursos disponibles. El soporte de despliegue es un aspecto opcional de la especificación de Compose y se describe en detalle en la documentación de la Especificación de despliegue de Compose (Deploy). Si no se implementa, la sección deploy se ignora y el archivo de Compose se sigue considerando válido.

Ejemplos

Ejemplo sencillo

El siguiente ejemplo demuestra cómo definir dos servicios sencillos, establecer sus imágenes, mapear puertos y configurar variables de entorno básicas utilizando Docker Compose.

services:
  web:
    image: nginx:latest
    ports:
      - "8080:80"

  db:
    image: postgres:18
    environment:
      POSTGRES_USER: example
      POSTGRES_DB: exampledb

Ejemplo avanzado

En el siguiente ejemplo, el servicio proxy utiliza la imagen de Nginx, monta un archivo de configuración local de Nginx en el contenedor, expone el puerto 80 y depende del servicio backend.

El servicio backend construye una imagen a partir del Dockerfile ubicado en el directorio backend que está configurado para compilarse en la etapa builder.

services:
  proxy:
    image: nginx
    volumes:
      - type: bind
        source: ./proxy/nginx.conf
        target: /etc/nginx/conf.d/default.conf
        read_only: true
    ports:
      - 80:80
    depends_on:
      - backend

  backend:
    build:
      context: backend
      target: builder

Para obtener más ejemplos de archivos de Compose, explora las muestras de Awesome Compose.

Atributos

annotations

annotations define anotaciones para el contenedor. annotations puede usar un array o un mapa.

annotations:
  com.example.foo: bar

annotations:
  - com.example.foo=bar

attach

Cuando se define attach y se establece en false, Compose no recopila los logs del servicio hasta que lo solicites explícitamente.

La configuración predeterminada del servicio es attach: true.

build

build especifica la configuración de compilación para crear una imagen de contenedor desde el origen, tal como se define en la Especificación de compilación de Compose (Build).

blkio_config

blkio_config define un conjunto de opciones de configuración para establecer límites de E/S de bloques para un servicio.

services:
  foo:
    image: busybox
    blkio_config:
      weight: 300
      weight_device:
        - path: /dev/sda
          weight: 400
      device_read_bps:
        - path: /dev/sdb
          rate: "12mb"
      device_read_iops:
        - path: /dev/sdb
          rate: 120
      device_write_bps:
        - path: /dev/sdb
          rate: "1024k"
      device_write_iops:
        - path: /dev/sdb
          rate: 30

device_read_bps, device_write_bps

Establece un límite en bytes por segundo para las operaciones de lectura y escritura en un dispositivo determinado. Cada elemento de la lista debe tener dos claves:

• path: Define la ruta simbólica al dispositivo afectado.
• rate: Ya sea un valor entero que representa el número de bytes o una cadena que expresa un valor en bytes.

device_read_iops, device_write_iops

Establece un límite en operaciones por segundo para las operaciones de lectura y escritura en un dispositivo determinado. Cada elemento de la lista debe tener dos claves:

• path: Define la ruta simbólica al dispositivo afectado.
• rate: Un valor entero que representa el número permitido de operaciones por segundo.

weight

Modifica la proporción de ancho de banda asignada a un servicio en relación con otros servicios. Toma un valor entero entre 10 y 1000, siendo 500 el valor predeterminado.

weight_device

Ajusta la asignación de ancho de banda por dispositivo. Cada elemento de la lista debe tener dos claves:

• path: Define la ruta simbólica al dispositivo afectado.
• weight: Un valor entero entre 10 and 1000.

cpu_count

cpu_count define el número de CPU utilizables para el contenedor del servicio.

cpu_percent

cpu_percent define el porcentaje utilizable de las CPU disponibles.

cpu_shares

cpu_shares define, como un valor entero, el peso relativo de CPU de un contenedor de servicio en comparación con otros contenedores.

cpu_period

cpu_period configura el período CPU CFS (Completely Fair Scheduler) cuando la plataforma se basa en el kernel de Linux.

cpu_quota

cpu_quota configura la cuota CPU CFS (Completely Fair Scheduler) cuando la plataforma se basa en el kernel de Linux.

cpu_rt_runtime

cpu_rt_runtime configura los parámetros de asignación de CPU para plataformas con soporte para planificador en tiempo real. Puede ser un valor entero que usa microsegundos como unidad o una duración.

 cpu_rt_runtime: '400ms'
 cpu_rt_runtime: '95000'

cpu_rt_period

cpu_rt_period configura los parámetros de asignación de CPU para plataformas con soporte para planificador en tiempo real. Puede ser un valor entero que usa microsegundos como unidad o una duración.

 cpu_rt_period: '1400us'
 cpu_rt_period: '11000'

cpus

cpus define el número de CPU (potencialmente virtuales) que se asignarán a los contenedores del servicio. Este es un número fraccionario. 0.000 significa sin límite.

Cuando se establece, cpus debe ser coherente con el atributo cpus en la Especificación de despliegue (Deploy).

cpuset

cpuset define las CPU explícitas en las que se permite la ejecución. Puede ser un rango 0-3 o una lista 0,1.

cap_add

cap_add especifica capacidades (capabilities) de contenedor adicionales como cadenas.

cap_add:
  - ALL

cap_drop

cap_drop especifica las capacidades (capabilities) de contenedor a eliminar como cadenas.

cap_drop:
  - NET_ADMIN
  - SYS_ADMIN

cgroup

cgroup especifica el espacio de nombres cgroup al que unirse. Cuando no se establece, corresponde al entorno de ejecución del contenedor decidir qué espacio de nombres cgroup usar, si es compatible.

• host: Ejecuta el contenedor en el espacio de nombres cgroup del entorno de ejecución del contenedor.
• private: Ejecuta el contenedor en su propio espacio de nombres cgroup privado.

cgroup_parent

cgroup_parent especifica un cgroup padre opcional para el contenedor.

cgroup_parent: m-executor-abcd

command

command anula el comando predeterminado declarado por la imagen del contenedor, por ejemplo, el CMD del Dockerfile.

command: bundle exec thin -p 3000

Si el valor es null, se utiliza el comando predeterminado de la imagen.

Si el valor es [] (lista vacía) o '' (cadena vacía), se ignora el comando predeterminado declarado por la imagen o, en otras palabras, se anula para que quede vacío.

Note

A diferencia de la instrucción CMD en un Dockerfile, el campo command no se ejecuta automáticamente dentro del contexto de la instrucción SHELL definida en la imagen. Si tu command depende de características específicas del shell, como la expansión de variables de entorno, debes ejecutarlo explícitamente dentro de un shell. Por ejemplo:

command: /bin/sh -c 'echo "hello $$HOSTNAME"'

El valor también puede ser una lista, similar a la sintaxis de formato exec utilizada por el Dockerfile.

configs

configs permite a los servicios adaptar su comportamiento sin necesidad de reconstruir una imagen de Docker. Los servicios solo pueden acceder a las configuraciones cuando se les concede explícitamente mediante el atributo configs. Se admiten dos variantes de sintaxis diferentes.

Compose informa un error si config no existe en la plataforma o no está definido en el elemento de nivel superior configs en el archivo de Compose.

Hay dos sintaxis definidas para configs: una sintaxis corta y una sintaxis larga.

Puedes otorgar a un servicio acceso a múltiples configuraciones y puedes mezclar la sintaxis larga y la corta.

Sintaxis corta

La variante de sintaxis corta solo especifica el nombre de la configuración. Esto otorga al contenedor acceso a la configuración y la monta como archivos en el sistema de archivos del contenedor del servicio. La ubicación del punto de montaje dentro del contenedor tiene como valor predeterminado /<config_name> en contenedores Linux y C:\<config-name> en contenedores Windows.

El siguiente ejemplo utiliza la sintaxis corta para otorgar al servicio redis acceso a las configuraciones my_config y my_other_config. El valor de my_config se establece con el contenido del archivo ./my_config.txt, y my_other_config se define como un recurso externo, lo que significa que ya se ha definido en la plataforma. Si la configuración externa no existe, el despliegue falla.

services:
  redis:
    image: redis:latest
    configs:
      - my_config
      - my_other_config
configs:
  my_config:
    file: ./my_config.txt
  my_other_config:
    external: true

Sintaxis larga

La sintaxis larga proporciona más granularidad sobre cómo se crea la configuración dentro de los contenedores de tareas del servicio.

• source: El nombre de la configuración tal como existe en la plataforma.
• target: La ruta y el nombre del archivo que se montará en los contenedores de tareas del servicio. Por defecto es /<source> si no se especifica.
• uid y gid: El uid o gid numérico propietario del archivo de configuración montado dentro de los contenedores de tareas del servicio.
• mode: Los permisos para el archivo que se monta dentro de los contenedores de tareas del servicio, en notación octal. El valor predeterminado es lectura pública (0444). El bit de escritura debe ignorarse. El bit de ejecución se puede establecer.

El siguiente ejemplo establece el nombre de my_config como redis_config dentro del contenedor, establece el modo en 0440 (lectura de grupo) y establece el usuario y el grupo en 103. El servicio redis no tiene acceso a la configuración my_other_config.

services:
  redis:
    image: redis:latest
    configs:
      - source: my_config
        target: /redis_config
        uid: "103"
        gid: "103"
        mode: 0440
configs:
  my_config:
    external: true
  my_other_config:
    external: true

container_name

container_name es una cadena que especifica un nombre de contenedor personalizado, en lugar de un nombre generado de forma predeterminada.

container_name: my-web-container

Compose no escala un servicio más allá de un contenedor si el archivo de Compose especifica un container_name. Intentar hacerlo resulta en un error.

container_name sigue el formato regex de [a-zA-Z0-9][a-zA-Z0-9_.-]+

credential_spec

credential_spec configura la especificación de credenciales para una cuenta de servicio gestionada.

Si tienes servicios que utilizan contenedores de Windows, puedes usar los protocolos file: y registry: para credential_spec. Compose también admite protocolos adicionales para casos de uso personalizados.

La especificación credential_spec debe estar en el formato file://<filename> o registry://<value-name>.

credential_spec:
  file: my-credential-spec.json

Cuando se usa registry:, la especificación de credenciales se lee desde el registro de Windows en el host del demonio. Un valor de registro con el nombre dado debe estar ubicado en:

HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Virtualization\Containers\CredentialSpecs

El siguiente ejemplo carga la especificación de credenciales desde un valor llamado my-credential-spec en el registro:

credential_spec:
  registry: my-credential-spec

Ejemplo de configuración de gMSA

Al configurar una especificación de credenciales gMSA para un servicio, solo necesitas especificar una especificación de credenciales con config, como se muestra en el siguiente ejemplo:

services:
  myservice:
    image: myimage:latest
    credential_spec:
      config: my_credential_spec

configs:
  my_credentials_spec:
    file: ./my-credential-spec.json

depends_on

Con el atributo depends_on, puedes controlar el orden de inicio y parada de los servicios. Resulta útil si los servicios están estrechamente acoplados y la secuencia de inicio afecta a la funcionalidad de la aplicación.

Sintaxis corta

La variante de sintaxis corta solo especifica los nombres de los servicios de las dependencias. Las dependencias de servicios provocan los siguientes comportamientos:

• Compose crea los servicios en orden de dependencia. En el siguiente ejemplo, db y redis se crean antes que web.
• Compose elimina los servicios en orden de dependencia. En el siguiente ejemplo, web se elimina antes que db y redis.

Ejemplo sencillo:

services:
  web:
    build: .
    depends_on:
      - db
      - redis
  redis:
    image: redis
  db:
    image: postgres:18

Compose garantiza que los servicios de dependencia se hayan iniciado antes de iniciar un servicio dependiente. Con la sintaxis corta, Compose no espera a que los servicios de dependencia estén "sanos (healthy)" antes de iniciar un servicio dependiente.

Sintaxis larga

La sintaxis de formato largo permite la configuración de campos adicionales que no se pueden expresar en la forma corta.

• restart: Cuando se establece en true, Compose reinicia este servicio después de actualizar el servicio de dependencia. Esto se aplica a un reinicio explícito controlado por una operación de Compose y excluye el reinicio automático por parte del entorno de ejecución del contenedor después de que el contenedor muere. Introducido en la versión de Docker Compose 2.17.0.
• condition: Establece la condición bajo la cual la dependencia se considera satisfecha.
  • service_started: Un equivalente de la sintaxis corta descrita anteriormente.
  • service_healthy: Especifica que se espera que una dependencia esté "sana (healthy)" (como se indica en healthcheck) antes de iniciar un servicio dependiente.
  • service_completed_successfully: Especifica que se espera que una dependencia se ejecute hasta completarse con éxito antes de iniciar un servicio dependiente.
• required: Cuando se establece en false, Compose solo te advierte cuando el servicio de dependencia no está iniciado o disponible. Si no está definido, el valor predeterminado de required es true. Introducido en la versión de Docker Compose 2.20.0.

Las dependencias de servicios provocan los siguientes comportamientos:

• Compose crea los servicios en orden de dependencia. En el siguiente ejemplo, db y redis se crean antes que web.
• Compose espera a que pasen las comprobaciones de salud (healthchecks) en las dependencias marcadas con service_healthy. En el siguiente ejemplo, se espera que db esté "sano (healthy)" antes de que se cree web.
• Compose elimina los servicios en orden de dependencia. En el siguiente ejemplo, web se elimina antes que db y redis.

services:
  web:
    build: .
    depends_on:
      db:
        condition: service_healthy
        restart: true
      redis:
        condition: service_started
  redis:
    image: redis
  db:
    image: postgres:18

Compose garantiza que los servicios de dependencia estén iniciados antes de iniciar un servicio dependiente. Compose garantiza que los servicios de dependencia marcados con service_healthy estén "sanos (healthy)" antes de iniciar un servicio dependiente.

deploy

deploy especifica la configuración para el despliegue y el ciclo de vida de los servicios, tal como se define en la Especificación de despliegue de Compose (Deploy).

develop

develop especifica la configuración de desarrollo para mantener un contenedor sincronizado con el código fuente, como se define en la Sección de desarrollo.

device_cgroup_rules

device_cgroup_rules define una lista de reglas de cgroup de dispositivos para este contenedor. El formato es el mismo que especifica el kernel de Linux en el Controlador de lista blanca de dispositivos de grupos de control (Control Groups Device Whitelist Controller).

device_cgroup_rules:
  - "c 1:3 mr"
  - "a 7:* rmw"

devices

devices define una lista de mapeos de dispositivos para los contenedores creados en la forma RUTA_HOST:RUTA_CONTENEDOR[:PERMISOS_CGROUP].

devices:
  - "/dev/ttyUSB0:/dev/ttyUSB0"
  - "/dev/sda:/dev/xvda:rwm"

devices también puede depender de la sintaxis CDI para permitir que el entorno de ejecución del contenedor seleccione un dispositivo:

devices:
  - "vendor1.com/device=gpu"

dns

dns define servidores DNS personalizados para establecer en la configuración de la interfaz de red del contenedor. Puede ser un valor único o una lista.

dns: 8.8.8.8

dns:
  - 8.8.8.8
  - 9.9.9.9

dns_opt

dns_opt enumera opciones de DNS personalizadas para pasar al resolvedor de DNS del contenedor (archivo /etc/resolv.conf en Linux).

dns_opt:
  - use-vc
  - no-tld-query

dns_search

dns_search define dominios de búsqueda DNS personalizados para establecer en la configuración de la interfaz de red del contenedor. Puede ser un valor único o una lista.

dns_search: example.com

dns_search:
  - dc1.example.com
  - dc2.example.com

domainname

domainname declara un nombre de dominio personalizado para usar en el contenedor del servicio. Debe ser un nombre de host válido según el RFC 1123.

driver_opts

driver_opts especifica una lista de opciones como pares clave-valor para pasar al controlador. Estas opciones dependen del controlador.

services:
  app:
    networks:
      app_net:
        driver_opts:
          com.docker.network.bridge.host_binding_ipv4: "127.0.0.1"

Consulta la documentación de los controladores de red para obtener más información.

entrypoint

entrypoint declara el punto de entrada predeterminado para el contenedor del servicio. Esto anula la instrucción ENTRYPOINT del Dockerfile del servicio.

Si entrypoint no es nulo, Compose ignora cualquier comando predeterminado de la imagen, por ejemplo, la instrucción CMD en el Dockerfile.

Consulta también command para establecer o anular el comando predeterminado que ejecutará el proceso de punto de entrada.

En su forma corta, el valor se puede definir como una cadena:

entrypoint: /code/entrypoint.sh

Alternativamente, el valor también puede ser una lista, de manera similar a la del Dockerfile:

entrypoint:
  - php
  - -d
  - zend_extension=/usr/local/lib/php/extensions/no-debug-non-zts-20100525/xdebug.so
  - -d
  - memory_limit=-1
  - vendor/bin/phpunit

Si el valor es null, se utiliza el punto de entrada predeterminado de la imagen.

Si el valor es [] (lista vacía) o '' (cadena vacía), se ignora el punto de entrada predeterminado declarado por la imagen o, en otras palabras, se anula para que quede vacío.

env_file

El atributo env_file sirve para especificar uno o más archivos que contienen variables de entorno que se pasarán a los contenedores.

env_file: .env

Las rutas relativas se resuelven a partir de la carpeta principal del archivo de Compose. Como las rutas absolutas impiden que el archivo de Compose sea portable, Compose te advierte cuando se utiliza una ruta de este tipo para configurar env_file.

Las variables de entorno declaradas en la sección environment anulan estos valores. Esto se cumple incluso si esos valores están vacíos o indefinidos.

env_file también puede ser una lista. Los archivos de la lista se procesan de arriba hacia abajo. Para una misma variable especificada en dos archivos de entorno, prevalece el valor del último archivo de la lista.

env_file:
  - ./a.env
  - ./b.env

Los elementos de la lista también se pueden declarar como un mapeo, lo que te permite establecer atributos adicionales.

required

El atributo required tiene como valor predeterminado true. Cuando required se establece en false y falta el archivo .env, Compose ignora la entrada silenciosamente.

env_file:
  - path: ./default.env
    required: true # predeterminado
  - path: ./override.env
    required: false

format

El atributo format te permite usar un formato de archivo alternativo para el env_file. Cuando no se establece, env_file se analiza de acuerdo con las reglas de Compose descritas en Formato de env_file.

El formato raw te permite usar un env_file con elementos clave=valor, pero sin que Compose intente analizar el valor para la interpolación. Esto te permite pasar los valores tal cual, incluyendo comillas y signos de $.

env_file:
  - path: ./default.env
    format: raw

Formato de env_file

Cada línea en un archivo .env debe estar en el formato VAR[=[VAL]]. Se aplican las siguientes reglas de sintaxis:

• Las líneas que comienzan con # se procesan como comentarios y se ignoran.
• Las líneas en blanco se ignoran.
• Los valores sin comillas y con comillas dobles (") tienen aplicada la interpolación.
• Cada línea representa un par clave-valor. Los valores pueden estar opcionalmente entre comillas.
• El delimitador que separa la clave y el valor puede ser = o :.
• Se ignoran los espacios antes y después del valor.
  • VAR=VAL -> VAL
  • VAR="VAL" -> VAL
  • VAR='VAL' -> VAL
  • VAR: VAL -> VAL
  • VAR = VAL -> VAL
• Los comentarios en línea para valores sin comillas deben ir precedidos de un espacio.
  • VAR=VAL # comentario -> VAL
  • VAR=VAL# no es un comentario -> VAL# no es un comentario
• Los comentarios en línea para valores entre comillas deben seguir a las comillas de cierre.
  • VAR="VAL # no es un comentario" -> VAL # no es un comentario
  • VAR="VAL" # comentario -> VAL
• Los valores entre comillas simples (') se utilizan literalmente.
  • VAR='$OTHER' -> $OTHER
  • VAR='${OTHER}' -> ${OTHER}
• Las comillas se pueden escapar con \.
  • VAR='Let\'s go!' -> Let's go!
  • VAR="{\"hello\": \"json\"}" -> {"hello": "json"}
• Las secuencias de escape comunes de shell, incluyendo \n, \r, \t y \\, son compatibles con los valores entre comillas dobles.
  • VAR="some\tvalue" -> some value
  • VAR='some\tvalue' -> some\tvalue
  • VAR=some\tvalue -> some\tvalue

VAL se puede omitir, en cuyo caso el valor de la variable es una cadena vacía. =VAL se puede omitir, en cuyo caso la variable queda sin establecer.

# Establecer el entorno de Rails/Rack
RACK_ENV=development
VAR="quoted"

environment

El atributo environment define las variables de entorno establecidas en el contenedor. environment puede utilizar un array o un mapa. Cualquier valor booleano (como true, false, yes, no) debe ir entre comillas para asegurar que el analizador (parser) de YAML no los convierta en True o False.

Las variables de entorno se pueden declarar mediante una sola clave (sin valor ni signo de igual). En este caso, Compose depende de ti para resolver el valor. Si el valor no se resuelve, la variable queda sin establecer y se elimina del entorno del contenedor del servicio.

Sintaxis de mapa:

environment:
  RACK_ENV: development
  SHOW: "true"
  USER_INPUT:

Sintaxis de array:

environment:
  - RACK_ENV=development
  - SHOW=true
  - USER_INPUT

Cuando se configuran tanto env_file como environment para un servicio, los valores establecidos por environment tienen prioridad.

expose

expose define el puerto (entrante) o un rango de puertos que Compose expone desde el contenedor. Estos puertos deben ser accesibles para los servicios vinculados y no deben publicarse en la máquina host. Solo se pueden especificar los puertos internos del contenedor.

La sintaxis es <portnum>/[<proto>] o <startport-endport>/[<proto>] para un rango de puertos. Cuando no se establece explícitamente, se utiliza el protocolo tcp.

expose:
  - "3000"
  - "8000"
  - "8080-8085/tcp"

Note

Si el Dockerfile de la imagen ya expone puertos, será visible para otros contenedores en la red incluso si expose no está configurado en tu archivo de Compose.

extends

extends te permite compartir configuraciones comunes entre diferentes archivos, o incluso entre diferentes proyectos por completo. Con extends puedes definir un conjunto común de opciones de servicio en un solo lugar y hacer referencia a él desde cualquier parte. Puedes hacer referencia a otro archivo de Compose y seleccionar un servicio que también desees usar en tu propia aplicación, con la capacidad de anular algunos atributos para tus propias necesidades.

Puedes usar extends en cualquier servicio junto con otras claves de configuración. El valor de extends debe ser un mapeo definido con una clave obligatoria service y una clave opcional file.

extends:
  file: common.yml
  service: webapp

• service: Define el nombre del servicio al que se hace referencia como base, por ejemplo, web o database.
• file: La ubicación de un archivo de configuración de Compose que define ese servicio.

extends no es compatible al realizar el despliegue con docker stack deploy.

Restricciones

Cuando se hace referencia a un servicio mediante extends, este puede declarar dependencias de otros recursos. Estas dependencias pueden definirse explícitamente a través de atributos como volumes, networks, configs, secrets, links, volumes_from o depends_on. Alternativamente, las dependencias pueden hacer referencia a otro servicio utilizando la sintaxis service:{name} en declaraciones de espacios de nombres como ipc, pid o network_mode.

Compose no importa automáticamente estos recursos de referencia al modelo extendido. Es tu responsabilidad asegurarte de que todos los recursos necesarios estén declarados explícitamente en el modelo que depende de extends.

No se admiten referencias circulares con extends, Compose devuelve un error cuando se detecta una.

Buscar el servicio de referencia

El valor de file puede ser:

• No presente. Esto indica que se está haciendo referencia a otro servicio dentro del mismo archivo de Compose.
• Ruta del archivo, que puede ser:
  • Ruta relativa. Esta ruta se considera relativa a la ubicación del archivo principal de Compose.
  • Ruta absoluta.

Un servicio indicado por service debe estar presente en el archivo de Compose de referencia identificado. Compose devuelve un error si:

• No se encuentra el servicio indicado por service.
• No se encuentra el archivo de Compose indicado por file.

Fusionar definiciones de servicios

Dos definiciones de servicios, la principal en el archivo de Compose actual y la de referencia especificada por extends, se fusionan de la siguiente manera:

• Mapeos: Las claves en los mapeos de la definición del servicio principal anulan las claves en los mapeos de la definición del servicio de referencia. Las claves que no se anulan se incluyen tal cual.
• Secuencias: Los elementos se combinan en una nueva secuencia. Se conserva el orden de los elementos, con los elementos de referencia primero y los elementos principales después.
• Escalares: Las claves en la definición del servicio principal tienen prioridad sobre las claves en el de referencia.

Mapeos

Los siguientes campos deben tratarse como mapeos: annotations, build.args, build.labels, build.extra_hosts, deploy.labels, deploy.update_config, deploy.rollback_config, deploy.restart_policy, deploy.resources.limits, environment, healthcheck, labels, logging.options, sysctls, storage_opt, extra_hosts, ulimits.

Una excepción que se aplica a healthcheck es que el mapeo principal no puede especificar disable: true a menos que el mapeo de referencia también especifique disable: true. Compose devuelve un error en este caso.

Por ejemplo, la siguiente entrada:

services:
  common:
    image: busybox
    environment:
      TZ: utc
      PORT: 80
  cli:
    extends:
      service: common
    environment:
      PORT: 8080

Produce la siguiente configuración para el servicio cli. Se produce el mismo resultado si se utiliza la sintaxis de array.

environment:
  PORT: 8080
  TZ: utc
image: busybox

Los elementos bajo blkio_config.device_read_bps, blkio_config.device_read_iops, blkio_config.device_write_bps, blkio_config.device_write_iops, devices y volumes también se tratan como mapeos donde la clave es la ruta de destino dentro del contenedor.

Por ejemplo, la siguiente entrada:

services:
  common:
    image: busybox
    volumes:
      - common-volume:/var/lib/backup/data:rw
  cli:
    extends:
      service: common
    volumes:
      - cli-volume:/var/lib/backup/data:ro

Produce la siguiente configuración para el servicio cli. Ten en cuenta que la ruta montada ahora apunta al nuevo nombre del volumen y se aplicó el flag ro.

image: busybox
volumes:
  - cli-volume:/var/lib/backup/data:ro

Si la definición del servicio de referencia contiene el mapeo extends, los elementos bajo este simplemente se copian en la nueva definición fusionada. Luego, el proceso de fusión se inicia nuevamente hasta que no queden claves extends.

Por ejemplo, la siguiente entrada:

services:
  base:
    image: busybox
    user: root
  common:
    image: busybox
    extends:
      service: base
  cli:
    extends:
      service: common

Produce la siguiente configuración para el servicio cli. Aquí, el servicio cli obtiene la clave user del servicio common, que a su vez obtiene esta clave del servicio base.

image: busybox
user: root

Secuencias

Los siguientes campos deben tratarse como secuencias: cap_add, cap_drop, configs, deploy.placement.constraints, deploy.placement.preferences, deploy.reservations.generic_resources, device_cgroup_rules, expose, external_links, ports, secrets, security_opt. Cualquier duplicado resultante de la fusión se elimina para que la secuencia solo contenga elementos únicos.

Por ejemplo, la siguiente entrada:

services:
  common:
    image: busybox
    security_opt:
      - label=role:ROLE
  cli:
    extends:
      service: common
    security_opt:
      - label=user:USER

Produce la siguiente configuración para el servicio cli.

image: busybox
security_opt:
  - label=role:ROLE
  - label=user:USER

En caso de que se use la sintaxis de lista, las siguientes claves también deben tratarse como secuencias: dns, dns_search, env_file, tmpfs. A diferencia de los campos de secuencia mencionados anteriormente, los duplicados resultantes de la fusión no se eliminan.

Escalares

Cualquier otra clave permitida en la definición del servicio debe tratarse como un escalar.

external_links

external_links vincula contenedores de servicios con servicios gestionados fuera de tu aplicación de Compose. external_links define el nombre de un servicio existente a recuperar utilizando el mecanismo de búsqueda de la plataforma. Se puede especificar un alias de la forma SERVICIO:ALIAS.

external_links:
  - redis
  - database:mysql
  - database:postgresql

extra_hosts

extra_hosts añade mapeos de nombres de host a la configuración de la interfaz de red del contenedor (/etc/hosts para Linux).

Sintaxis corta

La sintaxis corta utiliza cadenas simples en una lista. Los valores deben establecer el nombre de host y la dirección IP para hosts adicionales en la forma NOMBRE_HOST=IP.

extra_hosts:
  - "somehost=162.242.195.82"
  - "otherhost=50.31.209.229"
  - "myhostv6=::1"

Las direcciones IPv6 pueden encerrarse entre corchetes, por ejemplo:

extra_hosts:
  - "myhostv6=[::1]"

Se prefiere el separador =, pero también se puede usar :. Introducido en la versión de Docker Compose 2.24.1. Por ejemplo:

extra_hosts:
  - "somehost:162.242.195.82"
  - "myhostv6:::1"

Sintaxis larga

Alternativamente, extra_hosts se puede establecer como un mapeo entre nombres de host e IP:

extra_hosts:
  somehost: "162.242.195.82"
  otherhost: "50.31.209.229"
  myhostv6: "::1"

Compose crea una entrada coincidente con la dirección IP y el nombre de host en la configuración de red del contenedor, lo que significa que para Linux /etc/hosts obtiene líneas adicionales:

162.242.195.82  somehost
50.31.209.229   otherhost
::1             myhostv6

gpus

gpus especifica los dispositivos GPU que se asignarán para el uso del contenedor. Esto equivale a una solicitud de dispositivo (device request) con una capacidad implícita de gpu.

services:
  model:
    gpus:
      - driver: 3dfx
        count: 2

gpus también se puede establecer como la cadena all para asignar todos los dispositivos GPU disponibles al contenedor.

services:
  model:
    gpus: all

group_add

group_add especifica grupos adicionales, por nombre o número, de los cuales el usuario dentro del contenedor debe ser miembro.

Un ejemplo de dónde es útil esto es cuando varios contenedores (que se ejecutan como usuarios diferentes) necesitan leer o escribir en el mismo archivo en un volumen compartido. Ese archivo puede ser propiedad de un grupo compartido por todos los contenedores y especificado en group_add.

services:
  myservice:
    image: alpine
    group_add:
      - mail

Al ejecutar id dentro del contenedor creado se debe mostrar que el usuario pertenece al grupo mail, lo cual no habría sido el caso si no se hubiera declarado group_add.

healthcheck

El atributo healthcheck declara una comprobación que se ejecuta para determinar si los contenedores del servicio están "sanos" (healthy) o no. Funciona de la misma manera, y tiene los mismos valores predeterminados, que la instrucción HEALTHCHECK del Dockerfile establecida por la imagen de Docker del servicio. Tu archivo de Compose puede sobrescribir los valores definidos en el Dockerfile.

Para obtener más información sobre HEALTHCHECK, consulta la referencia de Dockerfile.

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost"]
  interval: 1m30s
  timeout: 10s
  retries: 3
  start_period: 40s
  start_interval: 5s

interval, timeout, start_period y start_interval se especifican como duraciones. Introducido en la versión de Docker Compose 2.20.2

test define el comando que ejecuta Compose para comprobar la salud del contenedor. Puede ser una cadena o una lista. Si es una lista, el primer elemento debe ser NONE, CMD o CMD-SHELL. Si es una cadena, es equivalente a especificar CMD-SHELL seguido de esa cadena.

# Acceder a la aplicación web local
test: ["CMD", "curl", "-f", "http://localhost"]

El uso de CMD-SHELL ejecuta el comando configurado como una cadena utilizando el shell predeterminado del contenedor (/bin/sh para Linux). Ambas formas siguientes son equivalentes:

test: ["CMD-SHELL", "curl -f http://localhost || exit 1"]

test: curl -f https://localhost || exit 1

NONE deshabilita la comprobación de salud y es útil principalmente para deshabilitar la instrucción Healthcheck del Dockerfile establecida por la imagen del contenedor del servicio. Alternativamente, la comprobación de salud establecida por la imagen se puede deshabilitar configurando disable: true:

healthcheck:
  disable: true

hostname

hostname declara un nombre de host personalizado para usar en el contenedor del servicio. Debe ser un nombre de host válido según el RFC 1123.

image

image especifica la imagen a partir de la cual iniciar el contenedor. image debe seguir el formato de imagen direccionable (addressable image format) de la especificación Open Container, como [<registry>/][<project>/]<image>[:<tag>|@<digest>].

    image: redis
    image: redis:5
    image: redis@sha256:0ed5d5928d4737458944eb604cc8509e245c3e19d02ad83935398bc4b991aac7
    image: library/redis
    image: docker.io/library/redis
    image: my_private.registry:5000/redis

Si la imagen no existe en la plataforma, Compose intenta descargarla (pull) basándose en la política pull_policy. Si también estás utilizando la Especificación de compilación de Compose (Build), existen opciones alternativas para controlar la prioridad de la descarga sobre la construcción de la imagen a partir de las fuentes; sin embargo, descargar la imagen es el comportamiento predeterminado.

image se puede omitir de un archivo de Compose siempre que se declare una sección build. Si no estás utilizando la especificación de compilación de Compose, Compose no funcionará si falta image en el archivo de Compose.

init

init ejecuta un proceso de inicio (PID 1) dentro del contenedor que reenvía señales y recolecta procesos huérfanos. Establece esta opción en true para habilitar esta característica para el servicio.

services:
  web:
    image: alpine:latest
    init: true

El binario de inicio que se utiliza es específico de la plataforma.

ipc

ipc configura el modo de aislamiento IPC establecido por el contenedor del servicio.

• shareable: Otorga al contenedor su propio espacio de nombres IPC privado, con la posibilidad de compartirlo con otros contenedores.
• service:{name}: Hace que el contenedor se una al espacio de nombres IPC (shareable) de otro contenedor.

    ipc: "shareable"
    ipc: "service:[nombre de servicio]"

isolation

isolation especifica la tecnología de aislamiento de un contenedor. Los valores admitidos son específicos de la plataforma.

labels

labels añade metadatos a los contenedores. Puedes usar un array o un mapa.

Se recomienda utilizar la notación DNS inversa para evitar que las etiquetas entren en conflicto con las utilizadas por otro software.

labels:
  com.example.description: "Accounting webapp"
  com.example.department: "Finance"
  com.example.label-with-empty-value: ""

labels:
  - "com.example.description=Accounting webapp"
  - "com.example.department=Finance"
  - "com.example.label-with-empty-value"

Compose crea contenedores con etiquetas canónicas:

• com.docker.compose.project establecida en todos los recursos creados por Compose con el nombre del proyecto del usuario.
• com.docker.compose.service establecida en los contenedores de servicios con el nombre del servicio tal como se define en el archivo de Compose.

El prefijo de etiqueta com.docker.compose está reservado. Especificar etiquetas con este prefijo en el archivo de Compose resulta en un error de tiempo de ejecución.

label_file

El atributo label_file te permite cargar etiquetas para un servicio desde un archivo externo o una lista de archivos. Esto proporciona una manera conveniente de gestionar múltiples etiquetas sin saturar el archivo de Compose.

El archivo utiliza un formato clave-valor, similar a env_file. Puedes especificar varios archivos como una lista. Al usar varios archivos, se procesan en el orden en que aparecen en la lista. Si la misma etiqueta se define en varios archivos, el valor del último archivo de la lista anula los anteriores.

services:
  one:
    label_file: ./app.labels

  two:
    label_file:
      - ./app.labels
      - ./additional.labels

Si una etiqueta se define tanto en label_file como en el atributo labels, el valor en labels tiene prioridad.

links

links define un enlace de red a contenedores de otro servicio. Especifica tanto el nombre del servicio como un alias de enlace (SERVICIO:ALIAS), o solo el nombre del servicio.

web:
  links:
    - db
    - db:database
    - redis

Los contenedores del servicio vinculado son alcanzables en un nombre de host idéntico al alias, o al nombre del servicio si no se especifica ningún alias.

No es necesario definir enlaces para permitir que los servicios se comuniquen. Cuando no se establece una configuración de red específica, cualquier servicio puede comunicarse con cualquier otro servicio utilizando el nombre de ese servicio en la red default. Si los servicios especifican las redes a las que están conectados, links no anula la configuración de la red. Los servicios que no están conectados a una red compartida no pueden comunicarse entre sí. Compose no advierte sobre una discrepancia de configuración.

Los enlaces también expresan una dependencia implícita entre servicios de la misma manera que depends_on, por lo que determinan el orden de inicio del servicio.

logging

logging define la configuración de registro para el servicio.

logging:
  driver: syslog
  options:
    syslog-address: "tcp://192.168.0.42:123"

El nombre de driver especifica un controlador de registro para los contenedores del servicio. Los valores predeterminados y disponibles son específicos de la plataforma. Las opciones específicas del controlador se pueden establecer con options como pares clave-valor.

mac_address

Disponible con la versión de Docker Compose 2.24.0 y posteriores.

mac_address establece una dirección Mac para el contenedor del servicio.

Note

Los entornos de ejecución de contenedores pueden rechazar este valor, por ejemplo, Docker Engine >= v25.0. En ese caso, debes usar networks.mac_address en su lugar.

mem_limit

mem_limit configura un límite en la cantidad de memoria que puede asignar un contenedor, establecido como una cadena que expresa un valor en bytes.

Cuando se establece, mem_limit debe ser coherente con el atributo limits.memory en la Especificación de despliegue (Deploy).

mem_reservation

mem_reservation configura una reserva en la cantidad de memoria que puede asignar un contenedor, establecido como una cadena que expresa un valor en bytes.

Cuando se establece, mem_reservation debe ser coherente con el atributo reservations.memory en la Especificación de despliegue (Deploy).

mem_swappiness

mem_swappiness define como un porcentaje, un valor entre 0 y 100, para que el kernel del host intercambie (swap) las páginas de memoria anónimas utilizadas por un contenedor.

• 0: Desactiva el intercambio de páginas anónimas.
• 100: Configura todas las páginas anónimas como intercambiables.

El valor predeterminado es específico de la plataforma.

memswap_limit

memswap_limit define la cantidad de memoria que el contenedor puede intercambiar (swap) a disco. Este es un atributo modificador que solo tiene significado si memory también está configurado. El uso del espacio de intercambio permite que el contenedor escriba el exceso de requisitos de memoria en el disco cuando ha agotado toda la memoria disponible. Existe una penalización de rendimiento para las aplicaciones que intercambian memoria al disco con frecuencia.

• Si memswap_limit se establece en un entero positivo, se deben configurar tanto memory como memswap_limit. memswap_limit representa la cantidad total de memoria e intercambio que se puede utilizar, y memory controla la cantidad utilizada por la memoria que no es de intercambio. Por lo tanto, si memory="300m" y memswap_limit="1g", el contenedor puede usar 300m de memoria y 700m (1g - 300m) de intercambio.
• Si memswap_limit se establece en 0, la configuración se ignora y el valor se trata como no establecido.
• Si memswap_limit se establece en el mismo valor que memory, y memory se establece en un entero positivo, el contenedor no tiene acceso al intercambio.
• Si memswap_limit no está configurado y memory sí lo está, el contenedor puede usar tanto intercambio como la configuración de memory, si el contenedor host tiene memoria de intercambio configurada. Por ejemplo, si memory="300m" y memswap_limit no está configurado, el contenedor puede usar 600m en total de memoria e intercambio.
• Si memswap_limit se establece explícitamente en -1, el contenedor puede usar intercambio ilimitado, hasta la cantidad disponible en el sistema host.

models

models define qué modelos de IA debe usar el servicio en tiempo de ejecución. Cada modelo de referencia debe definirse bajo el elemento de nivel superior models.

services:
  short_syntax:
    image: app
    models:
      - my_model
  long_syntax:
    image: app
    models:
      my_model:
        endpoint_var: MODEL_URL
        model_var: MODEL

Cuando un servicio se vincula a un modelo, Docker Compose inyecta variables de entorno para pasar detalles de conexión e identificadores de modelo al contenedor. Esto permite que la aplicación localice y se comunique con el modelo dinámicamente en tiempo de ejecución, sin codificar valores.

Sintaxis larga

La sintaxis larga te brinda más control sobre los nombres de las variables de entorno.

• endpoint_var establece el nombre de la variable de entorno que contiene la URL del ejecutor del modelo.
• model_var establece el nombre de la variable de entorno que contiene el identificador del modelo.

Si alguno de los dos se omite, Compose genera automáticamente los nombres de las variables de entorno basándose en la clave del modelo utilizando las siguientes reglas:

• Convertir la clave del modelo a mayúsculas
• Reemplazar cualquier carácter '-' con '_'
• Añadir _URL para la variable de endpoint

network_mode

network_mode establece el modo de red de un contenedor de servicio.

• bridge: Conecta el contenedor a la red puente (bridge) predeterminada de Docker en lugar de una red específica del proyecto. Los contenedores en la red puente predeterminada no pueden resolverse entre sí por el nombre del servicio. En su lugar, usa una red definida por el usuario para la resolución de DNS.
• none: Desactiva toda la conectividad de red del contenedor.
• host: Otorga al contenedor acceso directo a la interfaz de red del host.
• service:{name}: Otorga al contenedor acceso al contenedor especificado haciendo referencia a su nombre de servicio.
• container:{name}: Otorga al contenedor acceso al contenedor especificado haciendo referencia a su ID de contenedor.

Para obtener más información sobre las redes de contenedores, consulta la documentación de Docker Engine.

    network_mode: "bridge"
    network_mode: "host"
    network_mode: "none"
    network_mode: "service:[nombre del servicio]"

Cuando se establece, el atributo networks no está permitido y Compose rechaza cualquier archivo de Compose que contenga ambos atributos.

networks

El atributo networks define las redes a las que se conectan los contenedores de un servicio, haciendo referencia a las entradas del elemento de nivel superior networks. El atributo networks ayuda a gestionar los aspectos de red de los contenedores, ofreciendo control sobre cómo se segmentan e interactúan los servicios dentro del entorno de Docker. Sirve para especificar a qué redes deben conectarse los contenedores de ese servicio. Esto es importante para definir cómo se comunican los contenedores entre sí y de forma externa.

services:
  some-service:
    networks:
      - some-network
      - other-network

Para obtener más información sobre el elemento de nivel superior networks, consulta Redes.

Red predeterminada implícita

Si networks está vacío o ausente en el archivo de Compose, Compose considera una definición implícita para que el servicio se conecte a la red default:

services:
  some-service:
    image: foo

Este ejemplo es equivalente a:

services:
  some-service:
    image: foo
    networks:
      default: {}

Si deseas que el servicio no esté conectado a ninguna red, debes configurar network_mode: none.

aliases

aliases declara nombres de host alternativos para el servicio en la red. Otros contenedores en la misma red pueden usar el nombre del servicio o un alias para conectarse a uno de los contenedores del servicio.

Dado que los aliases tienen alcance de red, el mismo servicio puede tener diferentes alias en diferentes redes.

Note

Un alias para toda la red puede ser compartido por varios contenedores e incluso por varios servicios. Si es así, no se garantiza exactamente a qué contenedor se resuelve el nombre.

services:
  some-service:
    networks:
      some-network:
        aliases:
          - alias1
          - alias3
      other-network:
        aliases:
          - alias2

En el siguiente ejemplo, el servicio frontend puede comunicarse con el servicio backend en el nombre de host backend o database en la red back-tier. El servicio monitoring puede comunicarse con el mismo servicio backend en backend o mysql en la red admin.

services:
  frontend:
    image: example/webapp
    networks:
      - front-tier
      - back-tier

  monitoring:
    image: example/monitoring
    networks:
      - admin

  backend:
    image: example/backend
    networks:
      back-tier:
        aliases:
          - database
      admin:
        aliases:
          - mysql

networks:
  front-tier: {}
  back-tier: {}
  admin: {}

interface_name

interface_name te permite especificar el nombre de la interfaz de red utilizada para conectar un servicio a una red determinada. Esto garantiza un nombre de interfaz coherente y predecible entre servicios y redes.

services:
  backend:
    image: alpine
    command: ip link show
    networks:
      back-tier:
        interface_name: eth0

Al ejecutar la aplicación de Compose de ejemplo se muestra:

backend-1  | 11: eth0@if64: <BROADCAST,MULTICAST,UP,LOWER_UP,M-DOWN> mtu 1500 qdisc noqueue state UP

ipv4_address, ipv6_address

Especifica una dirección IP estática para un contenedor de servicio al unirse a la red.

La configuración de red correspondiente en la sección de redes de nivel superior debe tener un atributo ipam con configuraciones de subred que cubran cada dirección estática.

services:
  frontend:
    image: example/webapp
    networks:
      front-tier:
        ipv4_address: 172.16.238.10
        ipv6_address: 2001:3984:3989::10

networks:
  front-tier:
    ipam:
      driver: default
      config:
        - subnet: "172.16.238.0/24"
        - subnet: "2001:3984:3989::/64"

link_local_ips

link_local_ips especifica una lista de IP de enlace local (link-local). Las IP de enlace local son IP especiales que pertenecen a una subred conocida y son gestionadas únicamente por el operador, normalmente dependiendo de la arquitectura donde se despliegan.

Ejemplo:

services:
  app:
    image: busybox
    command: top
    networks:
      app_net:
        link_local_ips:
          - 57.123.22.11
          - 57.123.22.13
networks:
  app_net:
    driver: bridge

mac_address

mac_address establece la dirección Mac utilizada por el contenedor del servicio al conectarse a esta red en particular.

driver_opts

driver_opts especifica una lista de opciones como pares clave-valor para pasar al controlador. Estas opciones dependen del controlador. Consulta la documentación del controlador para obtener más información.

services:
  app:
    networks:
      app_net:
        driver_opts:
          foo: "bar"
          baz: 1

gw_priority

La red con el gw_priority más alto se selecciona como la puerta de enlace predeterminada para el contenedor del servicio. Si no se especifica, el valor predeterminado es 0.

En el siguiente ejemplo, app_net_2 se seleccionará como la puerta de enlace predeterminada.

services:
  app:
    image: busybox
    command: top
    networks:
      app_net_1:
      app_net_2:
        gw_priority: 1
      app_net_3:
networks:
  app_net_1:
  app_net_2:
  app_net_3:

priority

priority indica en qué orden conecta Compose los contenedores del servicio a sus redes. Si no se especifica, el valor predeterminado es 0.

Si el entorno de ejecución del contenedor acepta un atributo mac_address a nivel de servicio, este se aplica a la red con la priority más alta. En otros casos, usa el atributo networks.mac_address.

priority no afecta a qué red se selecciona como puerta de enlace predeterminada. Usa el atributo gw_priority en su lugar.

priority no controla el orden en el que se añaden las conexiones de red al contenedor, no se puede utilizar para determinar el nombre del dispositivo (eth0, etc.) en el contenedor.

services:
  app:
    image: busybox
    command: top
    networks:
      app_net_1:
        priority: 1000
      app_net_2:

      app_net_3:
        priority: 100
networks:
  app_net_1:
  app_net_2:
  app_net_3:

oom_kill_disable

Si se establece oom_kill_disable, Compose configura la plataforma para que no finalice el contenedor en caso de falta de memoria.

oom_score_adj

oom_score_adj ajusta la preferencia para que los contenedores sean finalizados por la plataforma en caso de falta de memoria. El valor debe estar dentro del rango -1000, 1000.

pid

pid establece el modo PID para el contenedor creado por Compose. Los valores admitidos son específicos de la plataforma.

pids_limit

pids_limit ajusta el límite de PID de un contenedor. Establécelo en -1 para PID ilimitados.

pids_limit: 10

Cuando se establece, pids_limit debe ser coherente con el atributo pids en la Especificación de despliegue (Deploy).

platform

platform define la plataforma de destino en la que se ejecutan los contenedores del servicio. Utiliza la sintaxis os[/arch[/variant]].

Los valores de os, arch y variant deben cumplir con la convención utilizada por la Especificación de imagen OCI (OCI Image Spec).

Compose utiliza este atributo para determinar qué versión de la imagen se descarga y/o en qué plataforma se realiza la compilación del servicio.

platform: darwin
platform: windows/amd64
platform: linux/arm64/v8

ports

El atributo ports sirve para definir las asociaciones de puertos (port mappings) entre la máquina host y los contenedores. Esto resulta crucial para permitir el acceso externo a los servicios que se ejecutan dentro de los contenedores. Se puede definir utilizando una sintaxis corta para asociaciones de puertos simples, o una sintaxis larga, que incluye opciones adicionales como el tipo de protocolo y el modo de red.

Note

Mapeo de puertos no debe utilizarse con network_mode: host. Hacerlo provoca un error de tiempo de ejecución porque network_mode: host ya expone los puertos del contenedor directamente a la red del host, por lo que no es necesario el mapeo de puertos.

Sintaxis corta

La sintaxis corta es una cadena separada por dos puntos para establecer la IP del host, el puerto del host y el puerto del contenedor en la forma:

[HOST:]CONTAINER[/PROTOCOL] donde:

• HOST es [IP:](puerto | rango) (opcional). Si no se establece, se vincula a todas las interfaces de red (0.0.0.0).
• CONTAINER es puerto | rango.
• PROTOCOL restringe los puertos a un protocolo específico, ya sea tcp o udp (opcional). El valor predeterminado es tcp.

Warning

Si no especificas una IP del host (como 127.0.0.1), Docker se vincula a todas las interfaces (0.0.0.0), omitiendo las reglas del firewall del host. Esto puede exponer el contenedor directamente a Internet si el host tiene una dirección IP pública. Para obtener más información, consulta Publicación y mapeo de puertos.

Los puertos pueden ser un valor único o un rango. HOST y CONTAINER deben usar rangos equivalentes.

Puedes especificar ambos puertos (HOST:CONTAINER) o solo el puerto del contenedor. En este último caso, el entorno de ejecución del contenedor asigna automáticamente cualquier puerto libre del host.

HOST:CONTAINER siempre debe especificarse como una cadena (entre comillas), para evitar conflictos con el tipo flotante de base-60 de YAML.

Las direcciones IPv6 se pueden encerrar entre corchetes.

Ejemplos:

ports:
  - "3000"
  - "3000-3005"
  - "8000:8000"
  - "9090-9091:8080-8081"
  - "49100:22"
  - "8000-9000:80"
  - "127.0.0.1:8001:8001"
  - "127.0.0.1:5000-5010:5000-5010"
  - "::1:6000:6000"
  - "[::1]:6001:6001"
  - "6060:6060/udp"

Note

Si el mapeo de IP del host no es compatible con el motor de contenedores, Compose rechaza el archivo de Compose e ignora la IP del host especificada.

Sintaxis larga

La sintaxis de formato largo te permite configurar campos adicionales que no se pueden expresar en la forma corta.

• target: El puerto del contenedor.
• published: El puerto expuesto públicamente. Se define como una cadena y se puede establecer como un rango mediante la sintaxis inicio-fin. Esto significa que al puerto real se le asigna un puerto disponible restante, dentro del rango establecido.
• host_ip: El mapeo de IP del host. Si no se establece, se vincula a todas las interfaces de red (0.0.0.0).
• protocol: El protocolo del puerto (tcp o udp). El valor predeterminado es tcp.
• app_protocol: El protocolo de aplicación (nivel 4 TCP/IP / nivel 7 OSI) para el cual se utiliza este puerto. Esto es opcional y se puede utilizar como una pista para que Compose ofrezca un comportamiento más rico para los protocolos que comprende. Introducido en la versión de Docker Compose 2.26.0.
• mode: Especifica cómo se publica el puerto en una configuración de Swarm. Si se establece en host, publica el puerto en cada nodo de Swarm. Si se establece en ingress, permite el equilibrio de carga entre los nodos de Swarm. El valor predeterminado es ingress.
• name: Un nombre legible por humanos para el puerto, que se utiliza para documentar su uso dentro del servicio.

ports:
  - name: web
    target: 80
    host_ip: 127.0.0.1
    published: "8080"
    protocol: tcp
    app_protocol: http
    mode: host

  - name: web-secured
    target: 443
    host_ip: 127.0.0.1
    published: "8083-9000"
    protocol: tcp
    app_protocol: https
    mode: host

post_start

post_start define una secuencia de ganchos (hooks) de ciclo de vida para ejecutarse después de que se ha iniciado un contenedor. No se garantiza el momento exacto en que se ejecuta el comando.

• command: Especifica el comando a ejecutar una vez que se inicia el contenedor. Este atributo es obligatorio y puedes elegir utilizar la forma de shell o la forma de exec.
• user: El usuario para ejecutar el comando. Si no se establece, el comando se ejecuta con el mismo usuario que el comando del servicio principal.
• privileged: Permite que el comando post_start se ejecute con acceso privilegiado.
• working_dir: El directorio de trabajo en el cual ejecutar el comando. Si no se establece, se ejecuta en el mismo directorio de trabajo que el comando del servicio principal.
• environment: Establece variables de entorno específicamente para el comando post_start. Si bien el comando hereda las variables de entorno definidas para el comando principal del servicio, esta sección te permite añadir nuevas variables o anular las existentes.

services:
  test:
    post_start:
      - command: ./do_something_on_startup.sh
        user: root
        privileged: true
        environment:
          - FOO=BAR

Para obtener más información, consulta Usar ganchos (hooks) de ciclo de vida.

pre_stop

pre_stop define una secuencia de ganchos (hooks) de ciclo de vida para ejecutarse antes de que se detenga el contenedor. Estos ganchos no se ejecutarán si el contenedor se detiene por sí solo o finaliza repentinamente.

La configuración es equivalente a la de post_start.

privileged

privileged configura el contenedor del servicio para que se ejecute con privilegios elevados. El soporte y los impactos reales son específicos de la plataforma.

profiles

profiles define una lista de perfiles con nombre bajo los cuales se habilitará el servicio. Si no se asigna, el servicio siempre se inicia, pero si se asigna, solo se inicia si se activa el perfil.

Si está presente, profiles sigue el formato regex de [a-zA-Z0-9][a-zA-Z0-9_.-]+.

services:
  frontend:
    image: frontend
    profiles: ["frontend"]

  phpmyadmin:
    image: phpmyadmin
    depends_on:
      - db
    profiles:
      - debug

provider

provider se puede usar para definir un servicio que Compose no gestionará directamente. Compose delega el ciclo de vida del servicio a un componente dedicado o de terceros.

database:
  provider:
    type: awesomecloud
    options:
      type: mysql
      foo: bar
app:
  image: myapp
  depends_on:
    - database

A medida que Compose ejecuta la aplicación, se utiliza el binario awesomecloud para gestionar la configuración del servicio database. El servicio dependiente app recibe variables de entorno adicionales prefijadas por el nombre del servicio para que pueda acceder al recurso.

A modo de ilustración, suponiendo que la ejecución de awesomecloud produjo las variables URL y API_KEY, el servicio app se ejecuta con las variables de entorno DATABASE_URL y DATABASE_API_KEY.

A medida que Compose detiene la aplicación, se utiliza el binario awesomecloud para gestionar el desmontaje del servicio database.

El mecanismo utilizado por Compose para delegar el ciclo de vida del servicio a un binario externo se describe en la documentación de extensibilidad de Compose (Compose extensibility).

Para obtener más información sobre el uso del atributo provider, consulta Usar servicios del proveedor (provider services).

type

El atributo type es obligatorio. Define el componente externo utilizado por Compose para gestionar los eventos del ciclo de vida de configuración y desmontaje.

options

Las options son específicas del proveedor seleccionado y no están validadas por la especificación de compose.

pull_policy

pull_policy define las decisiones que toma Compose cuando empieza a descargar (pull) imágenes. Los valores posibles son:

• always: Compose siempre descarga la imagen del registro.
• never: Compose no descarga la imagen de un registro y depende de la imagen almacenada en la caché de la plataforma. Si no hay una imagen en la caché, se informa de un fallo.
• missing: Compose descarga la imagen solo si no está disponible en la caché de la plataforma. Esta es la opción predeterminada si no estás utilizando también la Especificación de compilación de Compose (Build). if_not_present se considera un alias de este valor para mantener la compatibilidad hacia atrás. La etiqueta latest siempre se descarga incluso cuando se utiliza la política de descarga missing.
• build: Compose compila la imagen. Compose vuelve a compilar la imagen si ya está presente.
• daily: Compose comprueba el registro para buscar actualizaciones de imágenes si la última descarga se realizó hace más de 24 horas.
• weekly: Compose comprueba el registro para buscar actualizaciones de imágenes si la última descarga se realizó hace más de 7 días.
• every_<duration>: Compose comprueba el registro en busca de actualizaciones de imágenes si la última descarga se realizó antes de <duration>. La duración se puede expresar en semanas (w), días (d), horas (h), minutos (m), segundos (s) o una combinación de estos.

services:
  test:
    image: nginx
    pull_policy: every_12h

read_only

read_only configura el contenedor del servicio para que se cree con un sistema de archivos de solo lectura.

restart

restart define la política que aplica la plataforma al finalizar un contenedor.

• no: La política de reinicio predeterminada. No reinicia el contenedor bajo ninguna circunstancia.
• always: La política siempre reinicia el contenedor hasta su eliminación.
• on-failure[:max-retries]: La política reinicia el contenedor si el código de salida indica un error. Opcionalmente, limita el número de intentos de reinicio que realiza el demonio de Docker.
• unless-stopped: La política reinicia el contenedor independientemente del código de salida, pero deja de reiniciarlo cuando el servicio se detiene o se elimina.

    restart: "no"
    restart: always
    restart: on-failure
    restart: on-failure:3
    restart: unless-stopped

Puedes encontrar información más detallada sobre las políticas de reinicio en la sección Políticas de reinicio (--restart) (Restart Policies) de la página de referencia de Docker run.

runtime

runtime especifica qué entorno de ejecución utilizar para los contenedores del servicio.

Por ejemplo, runtime puede ser el nombre de una implementación de la especificación OCI Runtime (OCI Runtime Spec), como "runc".

web:
  image: busybox:latest
  command: true
  runtime: runc

El valor predeterminado es runc. Para utilizar un entorno de ejecución diferente, consulta Entornos de ejecución alternativos (Alternative runtimes).

scale

scale especifica el número predeterminado de contenedores a desplegar para este servicio. Cuando se configuran ambos, scale debe ser coherente con el atributo replicas en la Especificación de despliegue (Deploy).

secrets

El atributo secrets concede acceso a datos sensibles definidos por el elemento de nivel superior secrets de forma individual para cada servicio. Se puede conceder a los servicios acceso a múltiples secretos.

Se admiten dos variantes de sintaxis diferentes; la sintaxis corta y la sintaxis larga. En el mismo archivo de Compose se pueden utilizar sintaxis larga y corta para los secretos.

Compose informa un error si el secreto no existe en la plataforma o no está definido en la sección de nivel superior secrets del archivo de Compose.

Definir un secreto en secrets de nivel superior no debe implicar otorgar acceso al mismo a ningún servicio. Dicha concesión debe ser explícita dentro de la especificación del servicio como elemento del servicio secrets.

Sintaxis corta

La variante de sintaxis corta solo especifica el nombre del secreto. Esto otorga al contenedor acceso al secreto y lo monta como solo lectura en /run/secrets/<secret_name> dentro del contenedor. El nombre de origen y el punto de montaje de destino se establecen con el nombre del secreto.

El siguiente ejemplo utiliza la sintaxis corta para otorgar al servicio frontend acceso al secreto server-certificate. El valor de server-certificate se establece con el contenido del archivo ./server.cert.

services:
  frontend:
    image: example/webapp
    secrets:
      - server-certificate
secrets:
  server-certificate:
    file: ./server.cert

Sintaxis larga

La sintaxis larga proporciona más granularidad en cómo se crea el secreto dentro de los contenedores del servicio.

• source: El nombre del secreto tal como existe en la plataforma.
• target: El nombre del archivo que se montará en /run/secrets/ en el contenedor de tareas del servicio, o la ruta absoluta del archivo si se requiere una ubicación alternativa. Por defecto es source si no se especifica.
• uid y gid: El uid o gid numérico propietario del archivo dentro de /run/secrets/ en los contenedores de tareas del servicio.
• mode: Los permisos para el archivo que se montará en /run/secrets/ en los contenedores de tareas del servicio, en notación octal. El valor predeterminado son permisos de lectura pública (modo 0444). El bit de escritura debe ignorarse si se establece. El bit de ejecución puede establecerse.

Ten en cuenta que el soporte para los atributos uid, gid y mode solo se implementa en Docker Compose cuando el origen del secreto es environment. Cuando el origen es un file, Compose utiliza un montaje bind de fondo que no permite la reasignación de uid, y estos atributos se ignoran silenciosamente.

El siguiente ejemplo establece el nombre del archivo secreto my-token dentro del contenedor, establece el modo en 0440 (lectura de grupo) y establece el usuario y el grupo en 103. El valor de my-token se lee de la variable de entorno MY_TOKEN.

services:
  frontend:
    image: example/webapp
    secrets:
      - source: my-token
        uid: "103"
        gid: "103"
        mode: 0o440
secrets:
  my-token:
    environment: "MY_TOKEN"

security_opt

security_opt anula el esquema de etiquetado predeterminado para cada contenedor.

Las opciones aceptan la sintaxis option=value o option:value. Para opciones booleanas como no-new-privileges, el valor puede omitirse por completo, en cuyo caso la opción se trata como habilitada. Las siguientes sintaxis son equivalentes:

security_opt:
  - no-new-privileges
  - no-new-privileges=true
  - no-new-privileges:true

security_opt:
  - label=user:USER
  - label=role:ROLE

Para obtener más información sobre los esquemas de etiquetado predeterminados que puedes anular, consulta Configuración de seguridad (Security configuration).

shm_size

shm_size configura el tamaño de la memoria compartida (partición /dev/shm en Linux) permitida por el contenedor del servicio. Se especifica como un valor en bytes.

stdin_open

stdin_open configura el contenedor de un servicio para que se ejecute con una entrada estándar (stdin) asignada. Esto es lo mismo que ejecutar un contenedor con la bandera -i. Para obtener más información, consulta Mantener stdin abierto (Keep stdin open).

Los valores admitidos son true o false.

stop_grace_period

stop_grace_period especifica cuánto tiempo debe esperar Compose al intentar detener un contenedor si este no maneja SIGTERM (o cualquier señal de detención que se haya especificado con stop_signal), antes de enviar SIGKILL. Se especifica como una duración.

    stop_grace_period: 1s
    stop_grace_period: 1m30s

El valor predeterminado es 10 segundos para que el contenedor salga antes de enviar SIGKILL.

stop_signal

stop_signal define la señal que utiliza Compose para detener los contenedores del servicio. Si no se establece, Compose detiene los contenedores enviando SIGTERM.

stop_signal: SIGUSR1

storage_opt

storage_opt define las opciones del controlador de almacenamiento para un servicio.

storage_opt:
  size: "1G"

sysctls

sysctls define los parámetros del kernel a establecer en el contenedor. sysctls puede usar un array o un mapa.

sysctls:
  net.core.somaxconn: 1024
  net.ipv4.tcp_syncookies: 0

sysctls:
  - net.core.somaxconn=1024
  - net.ipv4.tcp_syncookies=0

Solo puedes usar sysctls que tengan espacio de nombres en el kernel. Docker no admite el cambio de sysctls dentro de un contenedor si estos también modifican el sistema host. Para obtener una descripción general de los sysctls admitidos, consulta configurar parámetros del kernel con espacio de nombres (sysctls) en tiempo de ejecución.

tmpfs

tmpfs monta un sistema de archivos temporal dentro del contenedor. Puede ser un valor único o una lista.

tmpfs:
  - <path>
  - <path>:<options>

• path: La ruta dentro del contenedor donde se montará el tmpfs.
• options: Lista separada por comas de opciones para el montaje tmpfs.

Opciones disponibles:

• mode: Establece los permisos del sistema de archivos.
• uid: Establece el ID de usuario propietario del tmpfs montado.
• gid: Establece el ID de grupo propietario del tmpfs montado.

services:
  app:
    tmpfs:
      - /data:mode=755,uid=1009,gid=1009
      - /run

tty

tty configura el contenedor de un servicio para que se ejecute con una TTY. Esto es lo mismo que ejecutar un contenedor con la bandera -t o --tty. Para obtener más información, consulta Asignar una pseudo-TTY (Allocate a pseudo-TTY).

Los valores admitidos son true o false.

ulimits

ulimits anula los ulimits predeterminados para un contenedor. Se especifica como un entero para un límite único o como un mapeo para límites blandos/duros (soft/hard).

ulimits:
  nproc: 65535
  nofile:
    soft: 20000
    hard: 40000

use_api_socket

Cuando se establece use_api_socket, el contenedor puede interactuar con el motor de contenedores subyacente a través del socket de la API. Tus credenciales se montan dentro del contenedor para que este actúe como un delegado puro para tus comandos relacionados con el motor de contenedores. Normalmente, los comandos ejecutados por el contenedor pueden realizar pull y push en tu registro.

user

user anula el usuario utilizado para ejecutar el proceso del contenedor. El valor predeterminado se establece por la imagen, por ejemplo, el USER del Dockerfile. Si no se establece, se utiliza root.

userns_mode

userns_mode establece el espacio de nombres de usuario para el servicio. Los valores admitidos son específicos de la plataforma y pueden depender de la configuración de la misma.

userns_mode: "host"

uts

uts configura el modo del espacio de nombres UTS establecido para el contenedor del servicio. Cuando no se especifica, corresponde al entorno de ejecución decidir si asigna un espacio de nombres UTS, si es compatible. Los valores disponibles son:

• 'host': Hace que el contenedor utilice el mismo espacio de nombres UTS que el host.

uts: "host"

volumes

El atributo volumes define rutas de host montadas o volúmenes con nombre que son accesibles para los contenedores de un servicio. Puedes usar volumes para definir múltiples tipos de montajes: volume, bind, tmpfs o npipe.

Si el montaje es una ruta de host y solo lo utiliza un único servicio, se puede declarar como parte de la definición del servicio. Para reutilizar un volumen entre múltiples servicios, se debe declarar un volumen con nombre en el elemento de nivel superior volumes.

El siguiente ejemplo muestra un volumen con nombre (db-data) utilizado por el servicio backend y un montaje bind definido para un único servicio.

services:
  backend:
    image: example/backend
    volumes:
      - type: volume
        source: db-data
        target: /data
        volume:
          nocopy: true
          subpath: sub
      - type: bind
        source: /var/run/postgres/postgres.sock
        target: /var/run/postgres/postgres.sock

volumes:
  db-data:

Para obtener más información sobre el elemento de nivel superior volumes, consulta Volúmenes (Volumes).

Sintaxis corta

La sintaxis corta utiliza una sola cadena con valores separados por dos puntos para especificar un montaje de volumen (VOLUMEN:RUTA_CONTENEDOR) o un modo de acceso (VOLUMEN:RUTA_CONTENEDOR:MODO_ACCESO).

• VOLUMEN: Puede ser una ruta de host en la plataforma que aloja los contenedores (montaje bind) o el nombre de un volumen.
• RUTA_CONTENEDOR: La ruta en el contenedor donde se monta el volumen.
• MODO_ACCESO: Una lista separada por comas , de opciones:
  • rw: Acceso de lectura y escritura. Este es el valor predeterminado si no se especifica ninguno.
  • ro: Acceso de solo lectura.
  • z: Opción de SELinux que indica que el contenido del host del montaje bind se comparte entre varios contenedores.
  • Z: Opción de SELinux que indica que el contenido del host del montaje bind es privado y no se comparte con otros contenedores.

Note

La opción de reetiquetado de SELinux en montajes bind se ignora en plataformas sin SELinux.

Note

Las rutas de host relativas solo son compatibles con entornos de Compose que realizan despliegues en un entorno de ejecución de contenedores local. Esto se debe a que la ruta relativa se resuelve a partir del directorio principal del archivo de Compose, lo cual solo es aplicable en el caso local. Cuando Compose realiza un despliegue en una plataforma no local, rechaza los archivos de Compose que utilizan rutas de host relativas con un error. Para evitar ambigüedades con los volúmenes con nombre, las rutas relativas siempre deben comenzar con . o ...

Note

Para montajes bind, la sintaxis corta crea un directorio en la ruta de origen en el host si no existe. Esto es para mantener la compatibilidad hacia atrás con el legado de docker-compose. Se puede evitar utilizando la sintaxis larga y configurando create_host_path en false.

Sintaxis larga

La sintaxis de formato largo te permite configurar campos adicionales que no se pueden expresar en la forma corta.

• type: El tipo de montaje. Puede ser volume, bind, tmpfs, image, npipe o cluster.
• source: El origen del montaje, una ruta en el host para un montaje bind, una referencia de imagen de Docker para un montaje de imagen, o el nombre de un volumen definido en la clave volumes de nivel superior. No aplicable para un montaje tmpfs.
• target: La ruta en el contenedor donde se monta el volumen.
• read_only: Bandera para establecer el volumen como de solo lectura.
• bind: Se utiliza para configurar opciones de bind adicionales:
  • propagation: El modo de propagación utilizado para el bind.
  • create_host_path: Crea un directorio en la ruta de origen en el host si no hay nada presente. El valor predeterminado es true.
  • selinux: La opción de reetiquetado de SELinux z (compartido) o Z (privado).
• volume: Configura opciones de volumen adicionales:
  • nocopy: Bandera para deshabilitar la copia de datos desde un contenedor cuando se crea un volumen.
  • subpath: Ruta dentro de un volumen para montar en lugar de la raíz del volumen.
• tmpfs: Configura opciones de tmpfs adicionales:
  • size: El tamaño del montaje tmpfs en bytes (numérico o como unidad de bytes).
  • mode: El modo de archivo para el montaje tmpfs como bits de permiso de Unix como un número octal. Introducido en la versión de Docker Compose 2.14.0.
• image: Configura opciones de imagen adicionales:
  • subpath: Ruta dentro de la imagen de origen para montar en lugar de la raíz de la imagen. Disponible en Docker Compose versión 2.35.0.
• consistency: Los requisitos de consistencia del montaje. Los valores disponibles son específicos de la plataforma.

Tip

¿Trabajas con repositorios grandes o monorepos, o con sistemas de archivos virtuales que ya no escalan con tu base de código? Compose ahora aprovecha el uso compartido de archivos sincronizados ( Synchronized file shares) y crea automáticamente usos compartidos de archivos para montajes de tipo bind (bind mounts). Asegúrate de haber iniciado sesión en Docker con una suscripción de pago y de haber habilitado tanto Access experimental features como Manage Synchronized file shares with Compose en la configuración de Docker Desktop.

volumes_from

volumes_from monta todos los volúmenes de otro servicio o contenedor. Opcionalmente, puedes especificar acceso de solo lectura ro o de lectura y escritura rw. Si no se especifica ningún nivel de acceso, se utiliza el acceso de lectura y escritura.

También puedes montar volúmenes desde un contenedor que no esté gestionado por Compose utilizando el prefijo container:.

volumes_from:
  - service_name
  - service_name:ro
  - container:container_name
  - container:container_name:rw

working_dir

working_dir anula el directorio de trabajo del contenedor especificado por la imagen, por ejemplo, el WORKDIR del Dockerfile.