Fusionner les fichiers Compose

Table des matières

Docker Compose vous permet de fusionner et de remplacer un ensemble de fichiers Compose ensemble pour créer un fichier Compose composite.

Par défaut, Compose lit deux fichiers, un fichier compose.yaml et un fichier optionnel compose.override.yaml. Par convention, le compose.yaml contient votre configuration de base. Le fichier de remplacement peut contenir des remplacements de configuration pour les services existants ou des services entièrement nouveaux.

Si un service est défini dans les deux fichiers, Compose fusionne les configurations en utilisant les règles décrites ci-dessous et dans la Spécification Compose.

Comment fusionner plusieurs fichiers Compose

Pour utiliser plusieurs fichiers de remplacement, ou un fichier de remplacement avec un nom différent, vous pouvez soit utiliser la variable d'environnement prédéfinie COMPOSE_FILE, soit utiliser l'option -f pour spécifier la liste des fichiers.

Compose fusionne les fichiers dans l'ordre où ils sont spécifiés sur la ligne de commande. Les fichiers suivants peuvent fusionner, remplacer ou ajouter à leurs prédécesseurs.

Par exemple :

$ docker compose -f compose.yaml -f compose.admin.yaml run backup_db

Le fichier compose.yaml peut spécifier un service webapp.

webapp:
  image: examples/web
  ports:
    - "8000:8000"
  volumes:
    - "/data"

Le compose.admin.yaml peut aussi spécifier ce même service :

webapp:
  environment:
    - DEBUG=1

Tous les champs correspondants remplacent le fichier précédent. Les nouvelles valeurs s'ajoutent à la configuration du service webapp :

webapp:
  image: examples/web
  ports:
    - "8000:8000"
  volumes:
    - "/data"
  environment:
    - DEBUG=1

Règles de fusion

Les chemins sont évalués relativement au fichier de base. Lorsque vous utilisez plusieurs fichiers Compose, vous devez vous assurer que tous les chemins dans les fichiers sont relatifs au fichier Compose de base (le premier fichier Compose spécifié avec -f). Ceci est requis car les fichiers de remplacement n'ont pas besoin d'être des fichiers Compose valides. Les fichiers de remplacement peuvent contenir de petits fragments de configuration. Suivre quel fragment d'un service est relatif à quel chemin est difficile et confus, donc pour garder les chemins plus faciles à comprendre, tous les chemins doivent être définis relativement au fichier de base.

Tip

Vous pouvez utiliser docker compose config pour réviser votre configuration fusionnée et éviter les problèmes liés aux chemins.

Compose copie les configurations du service original vers le service local. Si une option de configuration est définie à la fois dans le service original et le service local, la valeur locale remplace ou étend la valeur originale.

Pour les options à valeur unique comme image, command ou mem_limit, la nouvelle valeur remplace l'ancienne valeur.

service original :

services:
  myservice:
    # ...
    command: python app.py

service local :

services:
  myservice:
    # ...
    command: python otherapp.py

résultat :

services:
  myservice:
    # ...
    command: python otherapp.py

Pour les options à valeurs multiples ports, expose, external_links, dns, dns_search, et tmpfs, Compose concatène les deux ensembles de valeurs :

service original :

services:
  myservice:
    # ...
    expose:
      - "3000"

service local :

services:
  myservice:
    # ...
    expose:
      - "4000"
      - "5000"

résultat :

services:
  myservice:
    # ...
    expose:
      - "3000"
      - "4000"
      - "5000"

Dans le cas de environment, labels, volumes, et devices, Compose "fusionne" les entrées ensemble avec les valeurs définies localement qui prennent la précédence. Pour environment et labels, le nom de la variable d'environnement ou de l'étiquette détermine quelle valeur est utilisée :

service original :

services:
  myservice:
    # ...
    environment:
      - FOO=original
      - BAR=original

service local :

services:
  myservice:
    # ...
    environment:
      - BAR=local
      - BAZ=local

résultat :

services:
  myservice:
    # ...
    environment:
      - FOO=original
      - BAR=local
      - BAZ=local

Les entrées pour volumes et devices sont fusionnées en utilisant le chemin de montage dans le conteneur :

service original :

services:
  myservice:
    # ...
    volumes:
      - ./original:/foo
      - ./original:/bar

service local :

services:
  myservice:
    # ...
    volumes:
      - ./local:/bar
      - ./local:/baz

résultat :

services:
  myservice:
    # ...
    volumes:
      - ./original:/foo
      - ./local:/bar
      - ./local:/baz

Pour plus de règles de fusion, voir Fusionner et remplacer dans la Spécification Compose.

Informations supplémentaires

L'utilisation de -f est optionnelle. Si non fournie, Compose recherche dans le répertoire de travail et ses répertoires parents un fichier compose.yaml et un fichier compose.override.yaml. Vous devez fournir au moins le fichier compose.yaml. Si les deux fichiers existent au même niveau de répertoire, Compose les combine en une seule configuration.
Vous pouvez utiliser un -f avec - (tiret) comme nom de fichier pour lire la configuration depuis stdin. Par exemple :
$ docker compose -f - <<EOF webapp: image: examples/web ports: - "8000:8000" volumes: - "/data" environment: - DEBUG=1 EOF
Quand stdin est utilisé, tous les chemins dans la configuration sont relatifs au répertoire de travail actuel.

Vous pouvez utiliser le flag -f pour spécifier un chemin vers un fichier Compose qui n'est pas situé dans le répertoire actuel, soit depuis la ligne de commande soit en configurant une variable d'environnement COMPOSE_FILE dans votre shell ou dans un fichier d'environnement.

Par exemple, si vous exécutez l'exemple Compose Rails, et avez un fichier compose.yaml dans un répertoire appelé sandbox/rails. Vous pouvez utiliser une commande comme docker compose pull pour obtenir l'image postgres pour le service db depuis n'importe où en utilisant le flag -f comme suit : docker compose -f ~/sandbox/rails/compose.yaml pull db

Voici l'exemple complet :

$ docker compose -f ~/sandbox/rails/compose.yaml pull db
Pulling db (postgres:latest)...
latest: Pulling from library/postgres
ef0380f84d05: Pull complete
50cf91dc1db8: Pull complete
d3add4cd115c: Pull complete
467830d8a616: Pull complete
089b9db7dc57: Pull complete
6fba0a36935c: Pull complete
81ef0e73c953: Pull complete
338a6c4894dc: Pull complete
15853f32f67c: Pull complete
044c83d92898: Pull complete
17301519f133: Pull complete
dcca70822752: Pull complete
cecf11b8ccf3: Pull complete
Digest: sha256:1364924c753d5ff7e2260cd34dc4ba05ebd40ee8193391220be0f9901d4e1651
Status: Downloaded newer image for postgres:latest

Exemple

Un cas d'usage commun pour plusieurs fichiers est de changer une application Compose de développement pour un environnement de type production (qui peut être production, staging ou CI). Pour supporter ces différences, vous pouvez diviser votre configuration Compose en quelques fichiers différents :

Commencez avec un fichier de base qui définit la configuration canonique pour les services.

compose.yaml

services:
  web:
    image: example/my_web_app:latest
    depends_on:
      - db
      - cache

  db:
    image: postgres:latest

  cache:
    image: redis:latest

Dans cet exemple, la configuration de développement expose quelques ports vers l' hôte, monte notre code comme un volume, et construit l'image web.

compose.override.yaml

services:
  web:
    build: .
    volumes:
      - '.:/code'
    ports:
      - 8883:80
    environment:
      DEBUG: 'true'

  db:
    command: '-d'
    ports:
     - 5432:5432

  cache:
    ports:
      - 6379:6379

Quand vous exécutez docker compose up il lit les remplacements automatiquement.

Pour utiliser cette application Compose dans un environnement de production, un autre fichier de remplacement est créé, qui pourrait être stocké dans un dépôt git différent ou géré par une équipe différente.

compose.prod.yaml

services:
  web:
    ports:
      - 80:80
    environment:
      PRODUCTION: 'true'

  cache:
    environment:
      TTL: '500'

Pour déployer avec ce fichier Compose de production vous pouvez exécuter

$ docker compose -f compose.yaml -f compose.prod.yaml up -d

Ceci déploie tous les trois services en utilisant la configuration dans compose.yaml et compose.prod.yaml mais pas la configuration de dev dans compose.override.yaml.

Pour plus d'informations, voir Utiliser Compose en production.

Limitations

Docker Compose supporte les chemins relatifs pour les nombreuses ressources à inclure dans le modèle d'application : contexte de construction pour les images de service, emplacement du fichier définissant les variables d'environnement, chemin vers un répertoire local utilisé dans un volume bind-monté. Avec une telle contrainte, l'organisation du code dans un monorepo peut devenir difficile car un choix naturel serait d'avoir des dossiers dédiés par équipe ou composant, mais alors les chemins relatifs des fichiers Compose deviennent non pertinents.

Informations de référence

Règles de fusion