## 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 : ```yaml 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 : ```bash docker compose --profile debug up -d ``` Ou définir la variable d'environnement : ```bash 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 : ```bash 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 : ```bash docker compose config --services ``` Si la base de données est manquante, comparez avec la liste complète des services : ```bash 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 : ```bash 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 : ```yaml 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 : ```bash 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 : ```yaml 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 : ```bash 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 : ```bash 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é : ```bash 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 : ```bash docker compose config --services ``` **Comment récupérer :** Mettez à jour le pipeline pour définir le profil : ```bash 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 : ```bash 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 : ```bash 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 : ```bash docker compose logs ``` ### 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 : ```bash docker compose config --profiles ``` Ensuite, vérifiez manuellement quels services appartiennent à chaque profil en examinant le YAML ou en utilisant : ```bash 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 : ```bash docker compose config --services ``` Si le service de base de données est absent, activez son profil : ```bash docker compose --profile db up -d ``` Vérifiez : ```bash 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é : ```bash docker compose config --services ``` Démarrez le travailleur avec son profil : ```bash docker compose --profile worker up -d ``` Consultez les journaux pour confirmer le traitement : ```bash 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 : ```bash 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 : ```bash git checkout -- docker-compose.yml ``` Ensuite, redémarrez la pile : ```bash 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 : ```bash 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.