Profils Docker Compose : services facultatifs et dépendances

Les profils Docker Compose permettent de conserver des services facultatifs dans un même fichier et de les sélectionner au besoin. Une application web peut démarrer normalement tandis qu’un outil de diagnostic reste inactif. Il faut surtout comprendre comment les profils interagissent avec les services explicitement ciblés et leurs dépendances.

Ce guide compare ces choix à l’aide d’un petit exemple local. Vous pouvez examiner chaque configuration sans démarrer de conteneur. Les commandes d’exécution sont destinées à un environnement de test distinct : nous avons vérifié les modèles avec Docker Compose v5.1.4, sans télécharger les images ni lancer les conteneurs.

Comment les profils Docker Compose sélectionnent les services

Ajoutez profiles sous un service avec une liste de noms. Les services sans cet attribut restent activés. Si un service appartient à plusieurs profils, un seul profil correspondant actif suffit ; il n’est pas nécessaire de les activer tous.

La spécification des profils Compose distingue aussi les services des autres éléments de premier niveau. Les profils ne retirent pas conditionnellement les déclarations de réseaux ou de volumes de premier niveau. Gardez les services indispensables hors des profils et utilisez ceux-ci pour les tâches facultatives.

Un fichier Compose avec des outils de diagnostic facultatifs

Créez un répertoire et enregistrez le contenu suivant dans compose.yaml. Pour l’exécuter, utilisez le plugin actuel docker compose et un Docker Engine configuré pour les conteneurs Linux. Choisissez un autre port local si 8089 est déjà occupé.

services:
  web:
    image: nginx:stable-alpine
    ports:
      - "127.0.0.1:8089:80"
  probe:
    image: alpine:3.22
    profiles: [debug]
    command: ["wget", "-qO-", "http://web:80"]
    depends_on: [web]
  toolbox:
    image: alpine:3.22
    profiles: [debug, ops]
    command: ["sleep", "3600"]

web constitue le service principal. La tâche ponctuelle probe demande sa page par défaut. toolbox reste actif pendant une heure pour servir de conteneur de diagnostic temporaire. L’exemple utilise des tags d’image lisibles ; enregistrez les versions ou empreintes testées pour rendre un déploiement reproductible.

La sonde contacte web:80 sur le réseau du projet. Un navigateur sur l’hôte utilise http://127.0.0.1:8089. Notre guide des réseaux Compose explique cette différence d’adresse.

Examiner le modèle actif avant tout démarrage

Depuis le répertoire de l’exemple, exécutez :

docker compose -p profiles-demo config --profiles
docker compose -p profiles-demo config --services
docker compose -p profiles-demo --profile debug config --services
docker compose -p profiles-demo --profile ops config --services

docker compose config résout la configuration. L’option --profiles énumère les profils déclarés, pas les conteneurs en cours d’exécution. L’option --services affiche les services du modèle sélectionné.

Sélection	Services du modèle dans cet exemple
Aucun profil	web
debug	web, probe, toolbox
ops	web, toolbox
debug et ops	web, probe, toolbox

Ces combinaisons ont passé nos contrôles locaux de configuration. L’ordre des services dans la sortie n’a pas d’importance. Pour reproduire la ligne sans profil, utilisez un répertoire de test propre, sans variable COMPOSE_PROFILES héritée ni fichier de surcharge Compose supplémentaire.

Démarrer un profil ou cibler un service

Pour un test d’exécution, choisissez la première commande pour le service principal seul, ou la seconde pour la sélection debug :

docker compose -p profiles-demo up -d
docker compose -p profiles-demo --profile debug up -d

up -d crée et démarre l’application sélectionnée en arrière-plan. Avec debug, la sonde se termine après sa requête, tandis que web et toolbox peuvent continuer à fonctionner. Un service sélectionné n’est pas nécessairement un processus permanent.

Pour lancer uniquement la tâche de diagnostic et sa dépendance déclarée, ciblez-la explicitement :

docker compose -p profiles-demo run --rm probe
docker compose -p profiles-demo --profile "*" ps -a

Le guide des profils Docker décrit cette exception : cibler un service associé à un profil le rend disponible sans option de profil supplémentaire. Sans autre sélection, probe entraîne le démarrage de web via depends_on, mais pas celui de toolbox au seul motif qu’ils partagent debug. Les conteneurs restés actifs après une commande précédente constituent un état distinct. Partez d’un projet propre pour comparer les résultats.

La commande run crée un conteneur ponctuel ; --rm le supprime à sa sortie, sans supprimer la dépendance qu’il a démarrée. Elle ne publie pas non plus les ports configurés du service par défaut. La sonde n’a pas besoin de port entrant.

Distinguer sélection et disponibilité de l’application

La forme courte depends_on: [web] définit l’ordre de démarrage. Elle ne prouve pas que Nginx accepte déjà les requêtes. La sonde n’effectue aucune nouvelle tentative automatique : une erreur de connexion au démarrage peut donc venir de la disponibilité du service, même si les profils sont corrects.

Pour cet exercice, vérifiez la page web depuis le navigateur de l’hôte et relancez la sonde si nécessaire. Pour une dépendance applicative, utilisez un contrôle de santé adapté avec condition: service_healthy lorsque c’est nécessaire, tout en conservant les nouvelles tentatives côté application pour les pannes ultérieures. La documentation de l’ordre de démarrage et notre guide des healthchecks Compose détaillent cette distinction.

Utiliser COMPOSE_PROFILES de façon explicite

Vous pouvez répéter l’option CLI, par exemple --profile debug --profile ops. Pour conserver ce choix au niveau du projet, la variable COMPOSE_PROFILES accepte une liste séparée par des virgules. Le fichier .env du projet peut contenir :

COMPOSE_PROFILES=debug,ops

Cette valeur est une entrée de la commande Compose. La placer dans la section environment d’un service définit seulement une variable dans ce conteneur ; elle n’indique pas à la commande Compose sur l’hôte quels profils sélectionner. Notre guide des variables d’environnement explique les rôles de .env, des valeurs d’environnement du service et de env_file.

Retirez ce paramètre à la fin de l’exercice. Une valeur oubliée dans le shell ou le projet peut donner l’impression qu’un outil facultatif démarre par défaut. Dans les scripts partagés, rendez le choix visible dans la commande ou documentez son origine.

Une dépendance dans un profil inactif peut invalider le modèle

Enregistrez cette démonstration distincte dans cross-profile.yaml. Le service nommé database est un simple conteneur témoin pour tester les dépendances, pas un serveur de base de données.

services:
  web:
    image: nginx:stable-alpine
  database:
    image: alpine:3.22
    profiles: [data]
    command: ["sleep", "3600"]
  task:
    image: alpine:3.22
    profiles: [tools]
    command: ["echo", "example"]
    depends_on: [database]

Comparez les deux contrôles :

docker compose -p profiles-demo -f cross-profile.yaml --profile tools config --quiet
docker compose -p profiles-demo -f cross-profile.yaml --profile tools --profile data config --quiet

Le premier échoue : task dépend de database, mais le profil data est inactif. Le second active les deux profils et réussit. Nous avons reproduit ces deux résultats localement. Pour corriger ce cas, intégrez la dépendance indispensable au modèle principal, donnez un profil commun aux services facultatifs liés ou activez volontairement les deux profils. depends_on ne contourne pas toutes les restrictions de profil.

Arrêter un outil sans arrêter l’application

Ces commandes ont des portées différentes. La première arrête uniquement toolbox. La seconde supprime le projet de test pour l’ensemble des profils :

docker compose -p profiles-demo --profile debug stop toolbox
docker compose -p profiles-demo --profile "*" down

stop conserve le conteneur. down supprime les conteneurs et les réseaux gérés du projet sélectionné. Placez le caractère générique entre guillemets pour que le shell le transmette tel quel à Compose, puis vérifiez le nom du projet avant le nettoyage.

Un down limité à un profil inclut aussi les services sans profil. Il ne convient donc pas pour arrêter uniquement un outil facultatif tout en conservant l’application principale. Ciblez explicitement le service pour cette tâche plus restreinte.

Quand préférer un fichier de surcharge

Les profils conviennent pour inclure ou omettre des services entiers. Si un même service nécessite une autre commande, un autre port, montage ou image dans un environnement différent, utilisez un fichier de surcharge et examinez le résultat fusionné. Un nom de profil seul ne modifie pas ces champs.

Les profils facilitent la configuration ; ils ne constituent pas une limite d’autorisation. Une personne capable de lancer le projet Compose peut sélectionner explicitement un service facultatif. Adaptez les identifiants, l’exposition réseau et les permissions au service lui-même.

Pour chaque combinaison prise en charge, conservez la liste attendue des services et un contrôle de configuration. Testez ensuite le démarrage, la disponibilité et le nettoyage dans un environnement jetable. Un modèle valide décrit le déploiement prévu, sans prouver que les images sont disponibles ou que l’application fonctionnera.