Usar include para modularizar archivos de Compose

Puedes reutilizar y modularizar las configuraciones de Docker Compose incluyendo otros archivos de Compose. Esto es útil si:

• Quieres reutilizar otros archivos de Compose.
• Necesitas separar partes de tu modelo de aplicación en archivos de Compose independientes para poder gestionarlas por separado o compartirlas con otros.
• Los equipos necesitan mantener un archivo de Compose únicamente con la complejidad necesaria para la cantidad limitada de recursos que deben declarar para su propio subdominio dentro de un despliegue más grande.

La sección de nivel superior include se utiliza para definir la dependencia de otra aplicación o subdominio de Compose. Cada ruta indicada en la sección include se carga como un modelo de aplicación de Compose individual, con su propio directorio de proyecto, para poder resolver las rutas relativas.

Una vez cargada la aplicación de Compose incluida, todas las definiciones de recursos se copian en el modelo de aplicación de Compose actual. Compose muestra una advertencia si hay conflictos en los nombres de los recursos y no intenta fusionarlos. Para forzar esto, include se evalúa después de haber analizado y fusionado los archivos de Compose seleccionados para definir el modelo de la aplicación de Compose, de modo que se detecten los conflictos entre los archivos de Compose.

include se aplica de forma recursiva, por lo que un archivo de Compose incluido que declare su propia sección include activará la inclusión de esos otros archivos también.

Cualquier volumen, red u otro recurso extraído del archivo de Compose incluido puede ser utilizado por la aplicación de Compose actual para referencias cruzadas entre servicios. Por ejemplo:

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

Compose también admite el uso de variables interpoladas con include. Se recomienda especificar variables obligatorias. Por ejemplo:

include:
  -${INCLUDE_PATH:?FOO}/compose.yaml

Sintaxis corta

La sintaxis corta solo define rutas a otros archivos de Compose. El archivo se carga tomando la carpeta contenedora como directorio del proyecto, y un archivo opcional .env que se carga para definir los valores predeterminados de cualquier variable por interpolación. El entorno del proyecto local puede invalidar esos valores.

include:
  - ../commons/compose.yaml
  - ../another_domain/compose.yaml

services:
  webapp:
    depends_on:
      - included-service # definido por another_domain

En el ejemplo anterior, tanto ../commons/compose.yaml como ../another_domain/compose.yaml se cargan como proyectos de Compose individuales. Las rutas relativas en los archivos de Compose a los que hace referencia include se resuelven en relación con su propia ruta de archivo de Compose, no basándose en el directorio del proyecto local. Las variables se interpolan utilizando los valores establecidos en el archivo opcional .env de la misma carpeta y son invalidadas por el entorno del proyecto local.

Sintaxis larga

La sintaxis larga ofrece más control sobre el análisis del subproyecto:

include:
   - path: ../commons/compose.yaml
     project_directory: ..
     env_file: ../another/.env

path

path es obligatorio y define la ubicación de los archivos de Compose a analizar e incluir en el modelo de Compose local.

path se puede establecer como:

• Una cadena: Cuando se utiliza un único archivo de Compose.
• Una lista de cadenas: Cuando es necesario fusionar varios archivos de Compose para definir el modelo de Compose de la aplicación local.

include:
   - path:
       - ../commons/compose.yaml
       - ./commons-override.yaml

project_directory

project_directory define una ruta base para resolver las rutas relativas establecidas en el archivo de Compose. Su valor predeterminado es el directorio del archivo de Compose incluido.

env_file

env_file define un archivo o archivos de entorno que se utilizarán para establecer los valores predeterminados al interpolar variables en el archivo de Compose que se está analizando. Por defecto, es el archivo .env en el project_directory del archivo de Compose que se está analizando.

env_file se puede establecer como una cadena o una lista de cadenas cuando es necesario fusionar varios archivos de entorno para definir el entorno de un proyecto.

include:
   - path: ../another/compose.yaml
     env_file:
       - ../another/.env
       - ../another/dev.env

El entorno del proyecto local tiene prioridad sobre los valores establecidos por el archivo de Compose, de modo que el proyecto local puede invalidar los valores para su personalización.

Recursos adicionales

Para obtener más información sobre el uso de include, consulta Trabajar con múltiples archivos de Compose.