Compartir comentarios
Las respuestas se generan en base a la documentación.

Especificación de despliegue de Compose

Tabla de contenidos

Deploy es una parte opcional de la especificación de Compose. Proporciona un conjunto de especificaciones de despliegue para gestionar el comportamiento de los contenedores en diferentes entornos.

Atributos

endpoint_mode

endpoint_mode especifica un método de descubrimiento de servicios para clientes externos que se conectan a un servicio. La Especificación de Despliegue de Compose (Compose Deploy Specification) define dos valores canónicos:

  • endpoint_mode: vip: Asigna al servicio una IP virtual (VIP) que actúa como frontend para que los clientes accedan al servicio en una red. La plataforma enruta las solicitudes entre el cliente y los nodos que ejecutan el servicio, sin que el cliente sepa cuántos nodos participan en el servicio o sus direcciones IP o puertos.

  • endpoint_mode: dnsrr: La plataforma configura entradas DNS para el servicio de modo que una consulta DNS para el nombre del servicio devuelva una lista de direcciones IP (DNS round-robin), y el cliente se conecta directamente a una de ellas.

services:
  frontend:
    image: example/webapp
    ports:
      - "8080:80"
    deploy:
      mode: replicated
      replicas: 2
      endpoint_mode: vip

labels

labels especifica metadatos para el servicio. Estas etiquetas solo se establecen en el servicio y no en los contenedores del mismo. Esto asume que la plataforma tiene algún concepto nativo de "servicio" que puede coincidir con el modelo de aplicación de Compose.

services:
  frontend:
    image: example/webapp
    deploy:
      labels:
        com.example.description: "Esta etiqueta aparecerá en el servicio web"

mode

mode define el modelo de replicación utilizado para ejecutar un servicio o tarea (job). Las opciones incluyen:

  • global: Garantiza que se ejecute continuamente una tarea por nodo físico hasta que se detenga.
  • replicated: Ejecuta continuamente una cantidad especificada de tareas en los nodos hasta que se detengan (predeterminado).
  • replicated-job: Ejecuta una cantidad definida de tareas hasta alcanzar un estado de finalización (sale con código 0).
    • El total de tareas se determina mediante replicas.
    • La concurrencia se puede limitar mediante la opción max-concurrent (solo CLI).
  • global-job: Ejecuta una tarea por nodo físico con un estado de finalización (sale con código 0).
    • Se ejecuta automáticamente en los nodos nuevos a medida que se añaden.
services:
  frontend:
    image: example/webapp
    deploy:
      mode: global

  batch-job:
    image: example/processor
    deploy:
      mode: replicated-job
      replicas: 5

  maintenance:
    image: example/updater
    deploy:
      mode: global-job
Note
  • Los modos de tarea (job) (replicated-job y global-job) están diseñados para tareas que se completan y salen con código 0.
  • Las tareas completadas permanecen hasta que se eliminen explícitamente.
  • Las opciones como max-concurrent para controlar la concurrencia solo se admiten a través de la CLI y no están disponibles en Compose.

Para obtener información más detallada sobre las opciones y el comportamiento de las tareas, consulta la documentación de la CLI de Docker.

placement

placement especifica restricciones y preferencias para que la plataforma seleccione un nodo físico en el que ejecutar los contenedores del servicio.

constraints

constraints define una propiedad requerida que debe cumplir el nodo de la plataforma para ejecutar el contenedor del servicio. Para ver un ejemplo adicional, consulta los documentos de referencia de la CLI.

deploy:
  placement:
    constraints:
      - node.labels.disktype==ssd

preferences

preferences define una estrategia (actualmente spread es la única estrategia admitida) para distribuir las tareas de manera uniforme entre los valores de la etiqueta del nodo del centro de datos. Para ver un ejemplo adicional, consulta los documentos de referencia de la CLI.

deploy:
  placement:
    preferences:
      - spread: node.labels.zone

replicas

Si el servicio es replicated (que es el valor predeterminado), replicas especifica la cantidad de contenedores que deben estar ejecutándose en cualquier momento dado.

services:
  frontend:
    image: example/webapp
    deploy:
      mode: replicated
      replicas: 6

resources

resources configura restricciones de recursos físicos para que el contenedor se ejecute en la plataforma. Esas restricciones se pueden configurar como:

  • limits: La plataforma debe evitar que el contenedor asigne más recursos.
  • reservations: La plataforma debe garantizar que el contenedor pueda asignar al menos la cantidad configurada.
services:
  frontend:
    image: example/webapp
    deploy:
      resources:
        limits:
          cpus: '0.50'
          memory: 50M
          pids: 1
        reservations:
          cpus: '0.25'
          memory: 20M

cpus

cpus configura un límite o reserva de la cantidad de recursos de CPU disponibles, expresada como número de núcleos, que puede utilizar un contenedor.

memory

memory configura un límite o reserva de la cantidad de memoria que puede asignar un contenedor, establecida como una cadena que expresa un valor de bytes.

pids

pids ajusta el límite de PIDs de un contenedor, configurado como un número entero.

devices

devices configura reservas de los dispositivos que puede utilizar un contenedor. Contiene una lista de reservas, cada una configurada como un objeto con los siguientes parámetros: capabilities, driver, count, device_ids y options.

Los dispositivos se reservan utilizando una lista de capacidades (capabilities), lo que convierte a capabilities en el único campo obligatorio. Un dispositivo debe cumplir con todas las capacidades solicitadas para que la reserva sea exitosa.

capabilities

capabilities se configuran como una lista de cadenas que expresan capacidades tanto genéricas como específicas del controlador. Hoy en día se reconocen las siguientes capacidades genéricas:

  • gpu: Acelerador gráfico
  • tpu: Acelerador de IA

Para evitar conflictos de nombres, las capacidades específicas del controlador deben llevar el nombre del controlador como prefijo. Por ejemplo, reservar un acelerador compatible con NVIDIA CUDA podría verse así:

deploy:
  resources:
    reservations:
      devices:
        - capabilities: ["nvidia-compute"]
driver

Se puede solicitar un controlador diferente para los dispositivos reservados utilizando el campo driver. El valor se especifica como una cadena.

deploy:
  resources:
    reservations:
      devices:
        - capabilities: ["nvidia-compute"]
          driver: nvidia
count

Si count se establece en all o no se especifica, Compose reserva todos los dispositivos que cumplen con las capacidades solicitadas. De lo contrario, Compose reserva al menos la cantidad de dispositivos especificada. El valor se especifica como un número entero.

deploy:
  resources:
    reservations:
      devices:
        - capabilities: ["tpu"]
          count: 2

Los campos count y device_ids son mutuamente excluyentes. Compose devuelve un error si se especifican ambos.

device_ids

Si se establece device_ids, Compose reserva los dispositivos con los IDs especificados siempre que cumplan con las capacidades solicitadas. El valor se especifica como una lista de cadenas.

deploy:
  resources:
    reservations:
      devices:
        - capabilities: ["gpu"]
          device_ids: ["GPU-f123d1c9-26bb-df9b-1c23-4a731f61d8c7"]

Los campos count y device_ids son mutuamente excluyentes. Compose devuelve un error si se especifican ambos.

options

Las opciones específicas del controlador se pueden establecer con options como pares clave-valor.

deploy:
  resources:
    reservations:
      devices:
        - capabilities: ["gpu"]
          driver: gpuvendor
          options:
            virtualization: false

restart_policy

restart_policy configura si se deben reiniciar los contenedores y cómo hacerlo cuando finalizan. Si restart_policy no está establecido, Compose considera el campo restart establecido por la configuración del servicio.

  • condition. Cuando se establece en:
    • none, los contenedores no se reinician automáticamente independientemente del estado de salida.
    • on-failure, el contenedor se reinicia si finaliza debido a un error, lo que se manifiesta como un código de salida distinto de cero.
    • any (predeterminado), los contenedores se reinician independientemente del estado de salida.
  • delay: Cuánto tiempo esperar entre intentos de reinicio, especificado como una duración. El valor predeterminado es 0, lo que significa que los intentos de reinicio pueden ocurrir de inmediato.
  • max_attempts: La cantidad máxima de intentos de reinicio fallidos permitidos antes de rendirse. (Predeterminado: reintentos ilimitados). Un intento fallido solo cuenta para max_attempts si el contenedor no se reinicia correctamente dentro del tiempo definido por window. Por ejemplo, si max_attempts se establece en 2 y el contenedor no se reinicia dentro de la ventana en el primer intento, Compose continúa reintentando hasta que ocurran dos intentos fallidos de este tipo, incluso si eso significa intentarlo más de dos veces.
  • window: La cantidad de tiempo que se debe esperar después de un reinicio para determinar si tuvo éxito, especificada como una duración (predeterminado: el resultado se evalúa inmediatamente después del reinicio).
deploy:
  restart_policy:
    condition: on-failure
    delay: 5s
    max_attempts: 3
    window: 120s

rollback_config

rollback_config configura cómo se debe revertir (roll back) el servicio en caso de que falle una actualización.

  • parallelism: La cantidad de contenedores a revertir a la vez. Si se establece en 0, todos los contenedores se revierten simultáneamente.
  • delay: El tiempo que se debe esperar entre la reversión de cada grupo de contenedores (predeterminado 0s).
  • failure_action: Qué hacer si falla una reversión. Puede ser continue o pause (predeterminado pause).
  • monitor: Duración después de la actualización de cada tarea para monitorear si hay fallas (ns|us|ms|s|m|h) (predeterminado 0s).
  • max_failure_ratio: Tasa de fallas tolerable durante una reversión (predeterminado 0).
  • order: Orden de las operaciones durante las reversiones. Puede ser stop-first (la tarea antigua se detiene antes de iniciar la nueva) o start-first (la nueva tarea se inicia primero y las tareas en ejecución se superponen brevemente) (predeterminado stop-first).

update_config

update_config configura cómo se debe actualizar el servicio. Es útil para configurar actualizaciones progresivas (rolling updates).

  • parallelism: La cantidad de contenedores a actualizar a la vez.
  • delay: El tiempo que se debe esperar entre la actualización de un grupo de contenedores.
  • failure_action: Qué hacer si falla una actualización. Puede ser continue, rollback o pause (predeterminado: pause).
  • monitor: Duración después de la actualización de cada tarea para monitorear si hay fallas (ns|us|ms|s|m|h) (predeterminado 0s).
  • max_failure_ratio: Tasa de fallas tolerable durante una actualización.
  • order: Orden de las operaciones durante las actualizaciones. Puede ser stop-first (la tarea antigua se detiene antes de iniciar la nueva) o start-first (la nueva tarea se inicia primero y las tareas en ejecución se superponen brevemente) (predeterminado stop-first).
deploy:
  update_config:
    parallelism: 2
    delay: 10s
    order: stop-first