Étendre votre fichier Compose

L'attribut extends de Docker Compose vous permet de partager des configurations communes entre différents fichiers, ou même différents projets entièrement.

L'extension de services est utile si vous avez plusieurs services qui réutilisent un ensemble commun d'options de configuration. Avec extends vous pouvez définir un ensemble commun d'options de service en un endroit et y faire référence de n'importe où. Vous pouvez faire référence à un autre fichier Compose et sélectionner un service que vous voulez également utiliser dans votre propre application, avec la possibilité de remplacer certains attributs pour vos propres besoins.

Important

Quand vous utilisez plusieurs fichiers Compose, vous devez vous assurer que tous les chemins dans les fichiers sont relatifs au fichier Compose de base (c'est-à-dire le fichier Compose dans votre dossier de projet principal). Ceci est requis parce que les fichiers d'extension n'ont pas besoin d'être des fichiers Compose valides. Les fichiers d'extension peuvent contenir de petits fragments de configuration. Suivre quel fragment d'un service est relatif à quel chemin est difficile et déroutant, donc pour garder les chemins plus faciles à comprendre, tous les chemins doivent être définis relativement au fichier de base.

Comment ça fonctionne

Étendre des services depuis un autre fichier

Prenez l'exemple suivant :

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

Ceci indique à Compose de réutiliser uniquement les propriétés du service webapp défini dans le fichier common-services.yml. Le service webapp lui-même ne fait pas partie du projet final.

Si common-services.yml ressemble à ceci :

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

Vous obtenez exactement le même résultat que si vous écriviez compose.yaml avec les mêmes valeurs de configuration build, ports, et volumes définies directement sous web.

Pour inclure le service webapp dans le projet final lors de l'extension de services depuis un autre fichier, vous devez explicitement inclure les deux services dans votre fichier Compose actuel. Par exemple (notez que c'est un exemple non normatif) :

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

Alternativement, vous pouvez utiliser include.

Étendre des services dans le même fichier

Si vous définissez des services dans le même fichier Compose et étendez un service depuis un autre, à la fois le service original et le service étendu feront partie de votre configuration finale. Par exemple :

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

Étendre des services dans le même fichier et depuis un autre fichier

Vous pouvez aller plus loin et définir, ou redéfinir, la configuration localement dans compose.yaml :

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

  important_web:
    extends: web
    cpu_shares: 10

Exemple supplémentaire

Étendre un service individuel est utile quand vous avez plusieurs services qui ont une configuration commune. L'exemple ci-dessous est une application Compose avec deux services, une application web et un worker de queue. Les deux services utilisent la même base de code et partagent de nombreuses options de configuration.

Le fichier common.yaml définit la configuration commune :

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

Le compose.yaml définit les services concrets qui utilisent la configuration commune :

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

Exceptions et limitations

volumes_from et depends_on ne sont jamais partagés entre les services utilisant extends. Ces exceptions existent pour éviter les dépendances implicites ; vous définissez toujours volumes_from localement. Ceci assure que les dépendances entre services sont clairement visibles lors de la lecture du fichier actuel. Définir ces éléments localement assure également que les changements au fichier référencé ne cassent rien.

extends est utile si vous avez seulement besoin qu'un seul service soit partagé et que vous êtes familier avec le fichier que vous étendez, pour que vous puissiez ajuster la configuration. Mais ce n'est pas une solution acceptable quand vous voulez réutiliser les configurations non familières de quelqu'un d'autre et que vous ne connaissez pas ses propres dépendances.

Chemins relatifs

Lors de l'utilisation d'extends avec un attribut file qui pointe vers un autre dossier, les chemins relatifs déclarés par le service étendu sont convertis pour qu'ils pointent toujours vers le même fichier quand ils sont utilisés par le service d'extension. Ceci est illustré dans l'exemple suivant :

Fichier Compose de base :

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

Le fichier commons/compose.yaml :

services:
  base:
    env_file: ./container.env

Le service résultant fait référence au fichier container.env original dans le répertoire commons. Ceci peut être confirmé avec docker compose config qui inspecte le modèle réel :

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

Référence d'information

• extends