Extender tu archivo de Compose

El atributo extends de Docker Compose permite compartir configuraciones comunes entre diferentes archivos, o incluso entre proyectos completamente distintos.

Extender servicios resulta útil si tienes varios servicios que reutilizan un conjunto común de opciones de configuración. Con extends puedes definir un conjunto común de opciones de servicio en un solo lugar y hacer referencia a él desde cualquier sitio. Puedes hacer referencia a otro archivo de Compose y seleccionar un servicio que también desees utilizar en tu propia aplicación, con la capacidad de sobrescribir algunos atributos para satisfacer tus necesidades.

Important

Cuando utilices múltiples archivos de Compose, debes asegurarte de que todas las rutas en los archivos sean relativas al archivo de Compose base (es decir, el archivo de Compose en la carpeta de tu proyecto principal). Esto es necesario porque los archivos extendidos no tienen por qué ser archivos de Compose válidos. Los archivos extendidos pueden contener pequeños fragmentos de configuración. Realizar el seguimiento de qué fragmento de un servicio es relativo a qué ruta es difícil y confuso, por lo que para mantener las rutas más fáciles de entender, todas deben definirse en relación con el archivo base.

Note

extends no es compatible cuando se realiza un despliegue con docker stack deploy. Ejecutar docker stack config en un archivo de Compose que utiliza extends devuelve el error: Configuration contains forbidden properties.

Cómo funciona el atributo extends

Extender servicios desde otro archivo

Toma el siguiente ejemplo:

services:
  web:
    extends:
      file: common-services.yml
      service: webapp

Esto indica a Compose que reutilice únicamente las propiedades del servicio webapp definido en el archivo common-services.yml. El servicio webapp en sí mismo no forma parte del proyecto final.

Si common-services.yml se ve así:

services:
  webapp:
    build: .
    ports:
      - "8000:8000"
    volumes:
      - "/data"

Obtienes exactamente el mismo resultado que si hubieras escrito compose.yaml con los mismos valores de configuración de build, ports y volumes definidos directamente bajo web.

Para incluir el servicio webapp en el proyecto final al extender servicios desde otro archivo, necesitas incluir explícitamente ambos servicios en tu archivo de Compose actual. Por ejemplo (esto es solo con fines ilustrativos):

services:
  web:
    build: ./alpine
    command: echo
    extends:
      file: common-services.yml
      service: webapp
  webapp:
    extends:
      file: common-services.yml
      service: webapp

Como alternativa, puedes utilizar include.

Extender servicios dentro del mismo archivo

Si defines servicios en el mismo archivo de Compose y extiendes un servicio de otro, tanto el servicio original como el servicio extendido formarán parte de tu configuración final. Por ejemplo:

services:
  web:
    build: ./alpine
    extends: webapp
  webapp:
    environment:
      - DEBUG=1

Extender servicios dentro del mismo archivo y desde otro archivo

Puedes ir más allá y definir, o redefinir, la configuración localmente en compose.yaml:

services:
  web:
    extends:
      file: common-services.yml
      service: webapp
    environment:
      - DEBUG=1
    cpu_shares: 5

  important_web:
    extends: web
    cpu_shares: 10

Ejemplo adicional

Extender un servicio individual resulta útil cuando tienes múltiples servicios que comparten una configuración común. El siguiente ejemplo muestra una aplicación de Compose con dos servicios: una aplicación web y un procesador de cola (queue worker). Ambos servicios utilizan la misma base de código y comparten muchas opciones de configuración.

El archivo common.yaml define la configuración común:

services:
  app:
    build: .
    environment:
      CONFIG_FILE_PATH: /code/config
      API_KEY: xxxyyy
    cpu_shares: 5

El archivo compose.yaml define los servicios específicos que utilizan la configuración común:

services:
  webapp:
    extends:
      file: common.yaml
      service: app
    command: /code/run_web_app
    ports:
      - 8080:8080
    depends_on:
      - queue
      - db

  queue_worker:
    extends:
      file: common.yaml
      service: app
    command: /code/run_worker
    depends_on:
      - queue

Rutas relativas

Al usar extends con un atributo file que apunta a otra carpeta, las rutas relativas declaradas por el servicio que se está extendiendo se convierten para que sigan apuntando al mismo archivo cuando son utilizadas por el servicio que lo extiende. Esto se ilustra en el siguiente ejemplo:

Archivo de Compose base:

services:
  webapp:
    image: example
    extends:
      file: ../commons/compose.yaml
      service: base

El archivo commons/compose.yaml:

services:
  base:
    env_file: ./container.env

El servicio resultante hace referencia al archivo original container.env dentro del directorio commons. Esto se puede confirmar con docker compose config que inspecciona el modelo real:

services:
  webapp:
    image: example
    env_file:
      - ../commons/container.env

Información de referencia

• extends