Include

Con include, puedes incorporar un archivo compose.yaml independiente directamente en tu archivo compose.yaml actual. Esto facilita la modularización de aplicaciones complejas en subarchivos de Compose, lo que a su vez ayuda a que las configuraciones de la aplicación sean más simples y explícitas.

El elemento de nivel superior include ayuda a reflejar el equipo de ingeniería responsable del código directamente en la organización del archivo de configuración. También resuelve el problema de las rutas relativas que presentan extends y merge.

Cada ruta enumerada en la sección include se carga como un modelo de aplicación de Compose individual, con su propio directorio de proyecto, con el fin de resolver las rutas relativas.

Una vez que se carga la aplicación de Compose incluida, todos los recursos se copian en el modelo de aplicación de Compose actual.

Note

include se aplica de forma recursiva, por lo que si un archivo de Compose incluido declara su propia sección include, hace que esos archivos también se incluyan.

Ejemplo

include:
  - my-compose-include.yaml # con serviceB deaclarado
services:
  serviceA:
    build: .
    depends_on:
      - serviceB # usar serviceB directamente como si estuviera declarado en este archivo de Compose

my-compose-include.yaml gestiona serviceB, el cual detalla algunas réplicas, una interfaz de usuario web para inspeccionar datos, redes aisladas, volúmenes para la persistencia de datos, etc. La aplicación que depende de serviceB no necesita conocer los detalles de la infraestructura y consume el archivo de Compose como un bloque de construcción en el que puede confiar.

Esto significa que el equipo que gestiona serviceB puede refactorizar su propio componente de base de datos para introducir servicios adicionales sin afectar a los equipos dependientes. También significa que los equipos dependientes no necesitan incluir banderas (flags) adicionales en cada comando de Compose que ejecutan.

include:
  - oci://docker.io/username/my-compose-app:latest # usar un archivo de Compose almacenado como un artefacto OCI
services:
  serviceA:
    build: .
    depends_on:
      - serviceB

Con include puedes hacer referencia a archivos de Compose desde fuentes remotas, como artefactos OCI o repositorios de Git. Aquí, serviceB se define en un archivo de Compose almacenado en Docker Hub.

Uso de sobrescrituras (overrides) con archivos de Compose incluidos

Compose informa un error si algún recurso de include entra en conflicto con los recursos del archivo de Compose incluido. Esta regla evita conflictos inesperados con recursos definidos por el autor del archivo de Compose incluido. Sin embargo, puede haber algunas circunstancias en las que desees personalizar el modelo incluido. Esto se puede lograr agregando un archivo de sobrescritura a la directiva include:

include:
  - path:
      - third-party/compose.yaml
      - override.yaml # sobrescritura local para el modelo de terceros

La principal limitación de este enfoque es que necesitas mantener un archivo de sobrescritura dedicado por cada inclusión. Para proyectos complejos con múltiples inclusiones, esto daría como resultado muchos archivos de Compose.

La otra opción es utilizar un archivo compose.override.yaml. Aunque se rechazarán los conflictos del archivo que utiliza include cuando se declare el mismo recurso, un archivo de sobrescritura global de Compose puede sobrescribir el modelo fusionado resultante, como se demuestra en el siguiente ejemplo:

Archivo principal compose.yaml:

include:
  - team-1/compose.yaml # declarar service-1
  - team-2/compose.yaml # declarar service-2

Archivo de sobrescritura compose.override.yaml:

services:
  service-1:
    # sobrescribir el service-1 incluido para habilitar el puerto del depurador
    ports:
      - 2345:2345

  service-2:
    # sobrescribir el service-2 incluido para usar la carpeta de datos local que contiene datos de prueba
    volumes:
      - ./data:/data

De forma combinada, esto te permite beneficiarte de componentes reutilizables de terceros y ajustar el modelo de Compose a tus necesidades.

Información de referencia

include elemento de nivel superior