Erreurs de configuration des profils Docker Compose : prévention, diagnostic et récupération

Introduction

Les profils Docker Compose permettent aux équipes de définir des services optionnels dans un même fichier compose et de les activer uniquement lorsque cela est nécessaire. Un profil est une étiquette attachée à un service, et vous activez cette étiquette avec le drapeau --profile ou la variable d'environnement COMPOSE_PROFILES. Cela est utile pour exécuter une pile de développement complète avec des outils de débogage, ou pour séparer les services de production des tâches de maintenance.

Cependant, les profils introduisent une catégorie d'erreurs de configuration faciles à commettre et parfois difficiles à remarquer. Un service qui ne démarre pas silencieusement parce que son profil n'a pas été activé est une cause fréquente de pannes déroutantes. Des définitions de profils mal placées, des fautes de frappe dans les noms de profils ou des drapeaux de profil oubliés dans les pipelines CI peuvent entraîner des bases de données manquantes, des travailleurs en arrière-plan absents ou des tâches ponctuelles cassées.

Ce guide couvre les erreurs de configuration de profils Docker Compose les plus fréquentes, comment les détecter, comment les récupérer et comment les prévenir. Chaque section comprend une commande concrète et la sortie attendue, afin que vous puissiez vérifier votre environnement immédiatement.

Fonctionnement des profils Docker Compose

Avant d'examiner les erreurs, clarifions la syntaxe correcte. Dans un fichier compose, la clé profiles est placée sous la définition d'un service, et non au niveau supérieur :

version: "3.9"
services:
  app:
    image: nginx:1.25
    ports:
      - "8080:80"
  debug-tools:
    image: busybox:1.36
    profiles: ["debug"]
    command: tail -f /dev/null

Ici, app n'a pas de profils, il est donc toujours démarré. Le service debug-tools appartient au profil debug. Pour le démarrer, vous devez explicitement activer le profil :

docker compose --profile debug up -d

Ou définir la variable d'environnement :

export COMPOSE_PROFILES=debug
docker compose up -d

Pour vérifier quels services sont activés pour un profil donné sans rien démarrer, utilisez :

docker compose --profile debug config --services

Sortie attendue :

app
debug-tools

Si vous exécutez docker compose config --services sans aucun profil, seul app apparaît. C'est le premier endroit où les erreurs se cachent : le fichier est valide, mais l'ensemble actif de services est plus petit que prévu.

Erreurs de configuration de profils courantes

1. Oublier d'activer un profil requis

Un développeur définit un profil db pour le service de base de données et s'attend à ce qu'il soit en cours d'exécution après docker compose up -d. Mais sans --profile db, le conteneur de base de données ne démarre jamais. L'application échoue alors à se connecter.

Pourquoi cela arrive : Le fichier compose semble correct, et le développeur peut ne pas se rendre compte que les profils sont optionnels. Le service est omis silencieusement.

Comment détecter : Listez les services qui seraient démarrés :

docker compose config --services

Si la base de données est manquante, comparez avec la liste complète des services :

docker compose config --profiles

Cela affiche tous les profils définis. Sortie attendue pour un fichier avec les profils db et debug :

db
debug

Comment récupérer : Activez le profil manquant et redémarrez :

docker compose --profile db up -d

Comment prévenir : Définissez un profil par défaut dans le fichier compose à l'aide de la variable d'environnement COMPOSE_PROFILES dans un fichier .env, ou documentez le profil requis dans le README du projet. Pour les environnements automatisés, définissez le profil dans le pipeline CI ou dans un script d'encapsulation.

2. Placer les profils au mauvais niveau

Une erreur de syntaxe courante consiste à placer profiles sous la clé de niveau supérieur services ou à la racine du fichier :

services:
  profiles: ["debug"]   # incorrect
  app:
    image: nginx

Lorsque vous exécutez docker compose config, vous pouvez voir une erreur comme :

services.profiles must be a mapping

Ou le fichier peut être accepté mais le profil est ignoré, ce qui entraîne le démarrage systématique du service.

Pourquoi cela arrive : Mauvaise compréhension de la structure YAML ou copier-coller à partir d'un exemple incorrect.

Comment détecter : Validez le fichier compose :

docker compose config

Recherchez des avertissements ou des définitions de services inattendues. Vérifiez également avec docker compose config --profiles pour voir si le profil est reconnu.

Comment récupérer : Déplacez la clé profiles dans la définition du service prévu :

services:
  app:
    image: nginx
    profiles: ["debug"]

Comment prévenir : Utilisez un linter ou une validation de schéma YAML dans votre éditeur. De nombreux éditeurs mettent en évidence les erreurs structurelles dans les fichiers compose.

3. Fautes de frappe dans les noms de profils

Un service est assigné au profil debug, mais vous activez --profile dbug. Le service ne démarre pas, et l'erreur n'est pas évidente car la commande réussit sans erreur.

Pourquoi cela arrive : Saisie manuelle ou dénomination incohérente entre les scripts.

Comment détecter : Comparez le profil actif avec les profils définis dans le fichier :

docker compose config --profiles
# affiche les profils disponibles
docker compose config --services --profile dbug
# affiche uniquement les services dans dbug, le cas échéant

Comment récupérer : Activez le nom de profil correct :

docker compose --profile debug up -d

Comment prévenir : Utilisez une source unique de vérité pour les noms de profils, comme une cible Makefile ou un script shell contenant la liste des profils, et évitez de les saisir manuellement.

4. Profils dans les fichiers de surcouche ne fusionnant pas comme prévu

Compose prend en charge plusieurs fichiers, comme docker-compose.yml et docker-compose.override.yml. Les profils dans un fichier de surcouche peuvent ajouter ou supprimer des profils du service de base. Si le fichier de surcouche n'est pas chargé, le profil peut être manquant.

Pourquoi cela arrive : Le fichier de surcouche n'est pas présent, ou la commande n'inclut pas le drapeau -f pour charger les fichiers corrects.

Comment détecter : Exécutez docker compose config et inspectez quels services ont des profils. Vous pouvez également utiliser docker compose config --profiles pour lister tous les profils.

Comment récupérer : Assurez-vous que le fichier de surcouche est chargé :

docker compose -f docker-compose.yml -f docker-compose.override.yml up -d

Comment prévenir : Listez explicitement tous les fichiers compose dans vos commandes, ou utilisez un script d'encapsulation. Évitez de vous fier à la découverte implicite des fichiers lorsque plusieurs fichiers existent.

5. Activation de profil dans les pipelines CI/CD

Un pipeline CI exécute docker compose up -d sans le profil requis, et les tests échouent parce que les services de support sont manquants.

Pourquoi cela arrive : Le drapeau de profil ne fait pas partie de la configuration du pipeline, ou la variable d'environnement n'est pas définie dans l'exécuteur.

Comment détecter : Ajoutez une étape au pipeline qui affiche les services actifs :

docker compose config --services

Comment récupérer : Mettez à jour le pipeline pour définir le profil :

export COMPOSE_PROFILES=test
docker compose up -d

Comment prévenir : Stockez le profil dans un fichier .env utilisé par le pipeline, et révisez le fichier .env dans le cadre des modifications de code.

Vérification et diagnostics

Après toute modification des profils, vérifiez la configuration effective et les conteneurs en cours d'exécution.

Configuration effective

Exécutez docker compose config pour voir le YAML fusionné final. Vérifiez les affectations de profils inattendues ou les services manquants. Utilisez --services pour lister les services qui seraient démarrés avec les profils actuels.

Exemple :

docker compose --profile debug config --services

La sortie attendue inclut à la fois le service toujours actif et le service de débogage :

app
debug-tools

Statut des conteneurs

Après avoir démarré la pile, confirmez que les conteneurs attendus sont en cours d'exécution :

docker compose ps

Recherchez les services souhaités et leur état. Si un service n'est pas en cours d'exécution, consultez ses journaux :

docker compose logs <nom-du-service>

Débogage de l'activation des profils

Si vous soupçonnez qu'un profil n'a pas été activé, utilisez le drapeau --profiles pour voir tous les profils définis dans le fichier :

docker compose config --profiles

Ensuite, vérifiez manuellement quels services appartiennent à chaque profil en examinant le YAML ou en utilisant :

docker compose config | grep -A2 -B2 'profiles:'

Cela affiche le contexte autour de chaque clé profiles.

Modes de défaillance et récupération

Les profils peuvent échouer de manière non immédiatement évidente. Voici des modes de défaillance spécifiques et comment les récupérer.

Service de base de données manquant

Symptôme : L'application ne peut pas se connecter à la base de données.

Vérifiez :

docker compose config --services

Si le service de base de données est absent, activez son profil :

docker compose --profile db up -d

Vérifiez :

docker compose ps

Le conteneur de base de données devrait maintenant être listé et sain.

Travailleur en arrière-plan ne traitant pas les tâches

Symptôme : La file d'attente s'allonge mais aucune tâche n'est traitée.

Vérifiez si le service travailleur a un profil et n'est pas démarré :

docker compose config --services

Démarrez le travailleur avec son profil :

docker compose --profile worker up -d

Consultez les journaux pour confirmer le traitement :

docker compose logs -f worker

Tâche de maintenance ponctuelle non exécutée

Un service destiné à une tâche ponctuelle, comme une migration de base de données, est défini avec un profil mais le profil n'a pas été activé lors de l'exécution de docker compose run.

Commande correcte :

docker compose --profile migrate run migrate

Sans le profil, docker compose run migrate échoue avec « no such service: migrate ».

Restauration d'une modification de profil

Si une modification de profil cause des problèmes, revenez au fichier compose précédent. La restauration la plus simple consiste à restaurer la version précédente depuis le contrôle de version :

git checkout -- docker-compose.yml

Ensuite, redémarrez la pile :

docker compose down
docker compose up -d

Si vous devez désactiver temporairement un profil sans modifier le fichier, vous pouvez définir COMPOSE_PROFILES sur une chaîne vide :

export COMPOSE_PROFILES=
docker compose up -d

Cela démarre uniquement les services sans affectation de profil.

Liste de contrôle opérationnelle pour les modifications de profils

Utilisez cette liste de contrôle avant et après avoir modifié les profils dans un fichier compose.

Avant de modifier :

• [ ] Identifiez le(s) service(s) affecté(s) par la modification de profil.
• [ ] Notez les profils actifs actuels (COMPOSE_PROFILES ou drapeaux --profile en usage).
• [ ] Confirmez que le fichier compose est valide : docker compose config.
• [ ] Enregistrez les conteneurs en cours d'exécution : docker compose ps.

Après modification :

• [ ] Validez la nouvelle configuration : docker compose config --services.
• [ ] Démarrez la pile avec les profils prévus.
• [ ] Vérifiez que tous les services attendus sont en cours d'exécution : docker compose ps.
• [ ] Vérifiez la fonctionnalité de l'application (par exemple, connexion à la base de données, traitement des travailleurs).
• [ ] Mettez à jour la documentation ou les scripts qui référencent les profils.

Propriétaire et fréquence de révision : attribuez un propriétaire (par exemple, un ingénieur DevOps) pour approuver les modifications de profils dans le fichier compose, et révisez l'utilisation des profils mensuellement ou chaque fois que l'environnement de déploiement change.

Conclusion

Les profils Docker Compose sont un moyen puissant de gérer des services optionnels, mais ils doivent être utilisés avec précaution. Les erreurs les plus courantes sont l'oubli d'activer un profil, le mauvais placement de la clé profiles et l'utilisation de noms de profils incohérents. Ces erreurs entraînent le non-démarrage des services, ce qui peut être difficile à diagnostiquer car le fichier compose lui-même est valide.

En suivant les étapes de vérification de ce guide, vous pouvez rapidement identifier les profils manquants et récupérer. Les commandes clés à retenir sont docker compose config --services pour voir ce qui démarrerait, docker compose config --profiles pour lister les profils disponibles, et docker compose ps pour vérifier les conteneurs effectivement en cours d'exécution.

Prévenez les erreurs futures en standardisant les noms de profils, en documentant les profils requis et en utilisant des variables d'environnement dans CI/CD. Validez toujours la configuration effective avant le déploiement, et incluez des vérifications de profils dans vos procédures opérationnelles.

Avec ces pratiques, vous pouvez utiliser les profils Docker Compose en toute sécurité et éviter les défaillances silencieuses qui perturbent les environnements de développement et de production.