E-NO
DevOps 10 min de lecture

Variables d'environnement Docker Compose : concepts avancés et guide de mise en œuvre pratique

calendar_today Publié : 2026-11-22
update Dernière mise à jour : 2026-11-22
analytics Efficacité SEO : 100%
Illustration du guide technique pour « Variables d'environnement Docker Compose : concepts avancés et guide de mise en œuvre pratique ».

Introduction

Les variables d'environnement Docker Compose sont un mécanisme puissant pour configurer les services sans coder en dur des valeurs dans vos fichiers Compose. Bien que l'utilisation de base soit simple, les concepts avancés tels que la précédence des variables, l'interpolation et la gestion des secrets peuvent être déroutants et entraîner des erreurs de configuration subtiles. Ce guide propose une plongée pratique dans le fonctionnement des variables d'environnement dans Docker Compose, en couvrant les mécanismes internes, les modèles d'implémentation sûrs et les stratégies opérationnelles. À la fin, vous serez en mesure de gérer en toute confiance les variables d'environnement dans des déploiements complexes, d'éviter les écueils courants et de mettre en œuvre des procédures robustes de vérification et de retour arrière.

Comprendre les mécanismes internes des variables d'environnement Docker Compose réduit les retouches en vous permettant de séparer les préoccupations telles que la configuration, le déploiement et le comportement à l'exécution. Une compréhension claire de ces concepts est essentielle pour maintenir la cohérence entre les environnements de développement, de préproduction et de production.

Pour un premier pilote utile avec les concepts avancés de variables d'environnement, commencez par un scénario étroit et mesurable, facile à inspecter localement avant de le déployer en production. Cette approche minimise les risques et vous permet de valider vos modèles de configuration.

Inventaire des versions et de l'environnement

Avant d'aborder les concepts avancés, établissez un inventaire clair de vos versions de Docker et Docker Compose, car le comportement peut varier selon les versions. La gestion des variables d'environnement, en particulier l'interpolation et la syntaxe des valeurs par défaut, a évolué. À l'heure où nous écrivons ces lignes, Docker Compose v2.24.0 et Docker Engine 24.0.7 sont des versions stables largement utilisées. Vérifiez votre environnement avec :

docker --version
docker compose version

Sortie attendue :

Docker version 24.0.7, build afdd53b
Docker Compose version v2.24.0

Supposons une topologie typique : un hôte exécutant le démon Docker, avec un ou plusieurs projets Compose. Chaque projet est défini par un fichier compose.yaml ou docker-compose.yml et peut inclure plusieurs services. Les variables d'environnement peuvent provenir de divers emplacements, notamment le shell, les fichiers .env et les définitions de service elles-mêmes. Comprendre l'ordre de précédence est essentiel (expliqué dans la section suivante).

Prérequis pour une utilisation avancée des variables d'environnement :

  • Une installation fonctionnelle de Docker et Docker Compose.
  • Un éditeur de texte pour modifier les fichiers Compose.
  • Une familiarité de base avec la syntaxe YAML et les commandes shell.
  • L'accès à un environnement de test où vous pouvez expérimenter en toute sécurité.

Question rapide 1 sur 2

Selon le passage sur les fournisseurs, quelle convention de nommage est utilisée pour les variables d'environnement transmises d'un service fournisseur aux services dépendants ?

Le passage indique que la convention de nommage est <<PROVIDER_SERVICE_NAME>>_<<VARIABLE_NAME>>, par exemple DATABASE_URL pour un service fournisseur nommé database.

Chemin de configuration sûr

Dans cette section, nous explorerons les mécanismes internes de résolution des variables d'environnement et fournirons des choix d'implémentation sûrs. Nous couvrirons la précédence, l'interpolation, la substitution de variables dans les fichiers Compose et l'injection de variables d'environnement dans les conteneurs. Nous discuterons également des meilleures pratiques pour gérer les valeurs sensibles à l'aide des secrets Docker.

Précédence des variables d'environnement

Docker Compose utilise un ordre de précédence spécifique lors de la résolution des variables d'environnement. De la priorité la plus élevée à la plus basse :

  1. Variables d'environnement du shell (lors de l'exécution des commandes docker compose).
  2. Les variables d'environnement définies dans le shell sont remplacées par les variables de la section environment du fichier Compose.
  3. Les variables du fichier .env sont utilisées pour l'interpolation dans le fichier Compose, mais elles ne deviennent pas automatiquement des variables d'environnement du conteneur.
  4. Les valeurs par défaut définies dans le fichier Compose à l'aide de la syntaxe ${VAR:-default}.

Cette précédence est cruciale car une variable définie dans le shell peut remplacer de manière inattendue une valeur du fichier .env, entraînant un comportement différent selon la manière dont la commande compose est invoquée.

Interpolation dans les fichiers Compose

Les fichiers Compose prennent en charge l'interpolation de variables à l'aide de la syntaxe ${VARIABLE}. Cela vous permet de paramétrer votre fichier Compose. Par exemple :

services:
  web:
    image: nginx:${NGINX_VERSION:-latest}
    ports:
      - "${WEB_PORT:-80}:80"

Ici, NGINX_VERSION et WEB_PORT sont interpolés depuis l'environnement ou le fichier .env lorsque vous exécutez les commandes docker compose. Si la variable n'est pas définie, les valeurs par défaut latest et 80 sont utilisées.

Pour fournir des valeurs via un fichier .env, créez un fichier nommé .env dans le même répertoire que votre fichier Compose :

NGINX_VERSION=1.25
WEB_PORT=8080

Ensuite, l'exécution de docker compose config affiche la configuration résolue :

docker compose config

Extrait de sortie attendue :

services:
  web:
    image: nginx:1.25
    ports:
      - published: 8080
        target: 80

Variables d'environnement dans les services

Pour définir des variables d'environnement à l'intérieur des conteneurs, utilisez la clé environment dans la définition du service. Vous pouvez transmettre des variables du shell, du fichier .env, ou explicitement.

Variables définies explicitement :

services:
  app:
    image: myapp:latest
    environment:
      - DEBUG=true
      - LOG_LEVEL=info

Transmettre des variables du shell ou du fichier .env :

services:
  app:
    image: myapp:latest
    environment:
      - DEBUG=${DEBUG:-false}
      - LOG_LEVEL=${LOG_LEVEL:-warn}

Maintenant, si DEBUG est défini dans votre shell, il sera transmis au conteneur ; sinon, la valeur par défaut false est utilisée.

Utilisation d'un fichier d'environnement pour les variables du conteneur

Vous pouvez spécifier un fichier d'environnement pour un service à l'aide de l'option env_file. Ce fichier peut contenir des variables d'environnement qui seront définies à l'intérieur du conteneur. Notez que cela est distinct du fichier .env utilisé pour l'interpolation.

Exemple de env_file :

services:
  app:
    image: myapp:latest
    env_file:
      - ./config/app.env

Fichier config/app.env :

DEBUG=true
LOG_LEVEL=debug

Les variables de env_file sont injectées directement dans le conteneur au moment de l'exécution.

Fonctionnalités de substitution avancées

Compose prend en charge des fonctionnalités de substitution avancées telles que :

  • Valeurs par défaut : ${VAR:-default} utilise la valeur par défaut si VAR n'est pas définie ou est vide.
  • Valeurs alternatives : ${VAR:+alternate} utilise la valeur alternative si VAR est définie et non vide.
  • Variables requises : ${VAR:?err} quitte avec une erreur si VAR n'est pas définie ou est vide.
  • Variables à longueur limitée : ${VAR:offset:length} pour l'extraction de sous-chaînes.

Ces fonctionnalités sont utiles pour une gestion robuste de la configuration. Par exemple, pour exiger une variable :

services:
  db:
    image: postgres:${POSTGRES_VERSION:?Définissez POSTGRES_VERSION}

Si POSTGRES_VERSION n'est pas définie, docker compose config échoue avec une erreur.

Gestion des secrets avec les variables d'environnement

Transmettre des données sensibles (mots de passe, clés API) via des variables d'environnement est courant mais comporte des risques, car elles peuvent être exposées dans docker inspect ou les listes de processus. Les secrets Docker offrent une alternative plus sûre pour les données sensibles en mode Swarm. Dans Compose, vous pouvez utiliser des secrets pour transmettre des informations sensibles aux conteneurs sans les exposer comme variables d'environnement.

Exemple d'utilisation des secrets :

services:
  db:
    image: postgres:14
    secrets:
      - db_password
    environment:
      POSTGRES_PASSWORD_FILE: /run/secrets/db_password
secrets:
  db_password:
    file: ./secrets/db_password.txt

Le conteneur peut alors lire le mot de passe depuis le fichier secret monté, évitant ainsi l'exposition par variable d'environnement.

Choix d'implémentation délimités

Lors de la mise en œuvre de la gestion des variables d'environnement, envisagez de délimiter les variables pour minimiser l'exposition involontaire. Utilisez des noms de variables distincts pour différents services et environnements. Évitez de transmettre toutes les variables d'environnement de l'hôte dans les conteneurs ; listez explicitement uniquement ce qui est nécessaire.

Pour le développement local, vous pouvez utiliser un fichier .env avec des valeurs par défaut non sensibles. Pour la production, préférez les outils de gestion des secrets comme Docker secrets, HashiCorp Vault ou les gestionnaires de secrets des fournisseurs cloud, et injectez les valeurs au moment du déploiement via des pipelines CI/CD (mais cela dépasse notre cadre ici). Validez toujours que les variables requises sont présentes avant le déploiement.

Vérification et diagnostic

Après avoir configuré les variables d'environnement, il est essentiel de vérifier qu'elles sont résolues correctement et injectées dans les conteneurs. Cette section fournit des commandes concrètes et les sorties attendues.

Inspection de la configuration effective

Utilisez docker compose config pour afficher le fichier Compose entièrement résolu après interpolation. Cela montre ce que Compose utilisera réellement.

Exemple :

docker compose config

Vérifiez que les valeurs correspondent à vos attentes. Par exemple, si vous avez défini WEB_PORT=8080 dans .env, la sortie doit montrer ce port.

Vérification de l'environnement du conteneur

Une fois les conteneurs en cours d'exécution, vous pouvez inspecter les variables d'environnement à l'intérieur d'un conteneur en utilisant docker compose exec ou docker inspect.

Utilisation de docker compose exec :

docker compose exec app env

La sortie attendue inclut des variables comme DEBUG=true et LOG_LEVEL=debug si elles sont définies.

Utilisation de docker inspect :

docker inspect <container_id> --format '{{range .Config.Env}}{{println .}}{{end}}'

Cela imprime toutes les variables d'environnement du conteneur.

Test de l'interpolation avec --env-file

Vous pouvez spécifier manuellement un fichier env alternatif pour tester les configurations sans modifier le .env par défaut. Par exemple :

docker compose --env-file .env.test config

Cela est utile pour valider différents scénarios d'environnement.

Débogage des variables non résolues

Si une variable n'est pas définie et qu'aucune valeur par défaut n'est fournie, Compose substitue une chaîne vide. Cela peut causer des problèmes. Pour détecter de tels cas, utilisez la syntaxe de variable requise ${VAR:?message d'erreur} pendant le développement, ou exécutez docker compose config et recherchez les valeurs vides.

Par exemple, si vous avez image: nginx:${NGINX_VERSION} et que NGINX_VERSION n'est pas définie, la sortie résolue affichera image: nginx: (notez l'étiquette manquante). Le conteneur peut ne pas démarrer si la référence d'image est invalide.

Utilisation de docker compose run pour des tests rapides

Vous pouvez exécuter un conteneur ponctuel avec des variables d'environnement spécifiques pour tester le comportement sans démarrer toute la pile :

docker compose run --rm -e DEBUG=true app

Cela remplace ou ajoute DEBUG pour cette exécution.

Écueils courants et comment les éviter

Comprendre les écueils courants peut vous faire gagner des heures de débogage. Voici les erreurs fréquentes et les moyens de les prévenir ou de s'en remettre.

Les variables non définies deviennent des chaînes vides

Sans valeurs par défaut ni vérifications requises, une variable non définie devient une chaîne vide. Par exemple, si vous avez :

services:
  app:
    image: myapp:${APP_VERSION}

et que APP_VERSION n'est pas définie, l'image résolue devient myapp: qui est invalide. Pour éviter cela, utilisez des valeurs par défaut :

image: myapp:${APP_VERSION:-latest}

Ou exigez la variable :

image: myapp:${APP_VERSION:?APP_VERSION doit être définie}

Sensibilité à la casse et collisions de noms

Les noms de variables d'environnement sont sensibles à la casse. Utiliser POSTGRES_PASSWORD au lieu de postgres_password peut prêter à confusion. De plus, une variable dans votre shell peut accidentellement remplacer une valeur du fichier .env car les variables du shell ont la précédence. Pour éviter les collisions, utilisez des noms uniques et descriptifs qui ne risquent pas d'entrer en conflit avec les variables shell courantes, et définissez toujours explicitement les variables dans le fichier Compose ou env_file plutôt que de dépendre du shell.

Fichier .env introuvable

Si le fichier .env est manquant, Compose continue avec uniquement les variables du shell. Cela peut conduire à des valeurs vides. Par exemple, si vous avez ports: "${WEB_PORT}:80" et que .env est manquant mais que WEB_PORT n'est pas défini dans le shell, le port devient :80 qui est invalide. Pour éviter cela, utilisez des valeurs par défaut, la syntaxe de variable requise, ou assurez-vous que le fichier .env est présent dans votre processus de déploiement.

L'interpolation ne se fait pas par défaut dans env_file

Les variables dans env_file ne sont pas interpolées par défaut. Si votre app.env contient API_URL=${API_BASE}/v1, le conteneur recevra la chaîne littérale ${API_BASE}/v1. Pour interpoler dans env_file, vous devez utiliser les options required et interpolate introduites dans Compose v2.24.0 :

services:
  app:
    image: myapp:latest
    env_file:
      - path: ./config/app.env
        required: true
        interpolate: true

Mauvaise configuration des secrets

Des chemins de fichiers secrets incorrects ou des permissions inadéquates peuvent empêcher les conteneurs de démarrer. Assurez-vous toujours que le fichier secret existe et est lisible. Utilisez docker compose config pour valider les définitions de secrets, et testez l'accès au secret à l'intérieur du conteneur avec docker compose exec <service> cat /run/secrets/<secret_name>.

Mélange de .env et env_file

Rappelez-vous que .env est utilisé pour l'interpolation dans le fichier Compose, tandis que env_file injecte les variables directement dans le conteneur. Les mélanger peut prêter à confusion. Par exemple, si vous définissez DEBUG=true dans .env mais pas dans env_file, le conteneur peut ne pas le voir. Utilisez .env uniquement pour les valeurs que vous devez interpoler dans le fichier Compose, et env_file pour l'environnement d'exécution du conteneur.

Question rapide 2 sur 2

Selon le passage sur la préséance, quelle source de variables d'interpolation a la préséance la plus élevée ?

Le passage liste les variables de l'environnement shell en premier dans l'ordre de préséance, suivies de --env-file, puis du fichier .env du projet.

Modes de défaillance et récupération

Comprendre les modes de défaillance courants liés aux variables d'environnement vous permet de concevoir des configurations robustes et de récupérer rapidement des problèmes.

Modes de défaillance courants

  • Variables non définies conduisant à des valeurs vides : Sans valeurs par défaut ni vérifications requises, les variables non définies deviennent des chaînes vides, provoquant des erreurs de configuration. Par exemple, un POSTGRES_PASSWORD manquant peut empêcher l'initialisation de la base de données.
  • Sensibilité à la casse et collisions de noms : Les noms de variables d'environnement sont sensibles à la casse. Utiliser POSTGRES_PASSWORD au lieu de postgres_password peut prêter à confusion. Les collisions avec les variables d'environnement de l'hôte peuvent accidentellement remplacer les valeurs prévues.
  • Fichier .env introuvable : Si le fichier .env est manquant, Compose continue avec uniquement les variables du shell, ce qui peut entraîner des valeurs vides inattendues.
  • Interpolation dans env_file vs environment : Les variables dans env_file ne sont pas interpolées par défaut (sauf si vous utilisez env_file avec les options required et interpolate dans Compose v2.24+). Cela peut conduire à des chaînes ${VAR} littérales dans les conteneurs.
  • Mauvaise configuration des secrets : Des chemins de fichiers secrets incorrects ou des permissions inadéquates peuvent empêcher les conteneurs de démarrer.

Stratégies de retour arrière et de récupération

Pour récupérer des erreurs de configuration des variables d'environnement :

  • Contrôle de version : Conservez les fichiers Compose et les modèles .env dans le contrôle de version. Si un changement cause des problèmes, revenez à la configuration précédente connue comme bonne en utilisant git revert.
  • Utiliser des valeurs par défaut : Dans la mesure du possible, définissez des valeurs par défaut sensées dans le fichier Compose afin que les variables manquantes ne provoquent pas de défaillances catastrophiques.
  • Valider avant le déploiement : Exécutez toujours docker compose config et examinez la sortie avant de déployer en production. Envisagez d'utiliser --quiet pour vérifier uniquement les erreurs : docker compose config --quiet (sort avec le code 0 si valide).
  • Surveiller les journaux des conteneurs : Après le déploiement, vérifiez les journaux des conteneurs pour les erreurs liées aux variables d'environnement manquantes. Par exemple, un conteneur de base de données peut enregistrer une erreur si des variables requises sont absentes.
  • Procédure de retour arrière : Si un déploiement avec de nouvelles variables d'environnement échoue, exécutez docker compose down puis docker compose up -d avec la configuration précédente. Assurez-vous d'avoir les anciennes valeurs .env ou utilisez un --env-file spécifique pour restaurer.
  • Changements incrémentaux : Appliquez les modifications à un service à la fois, et vérifiez chacun avant de passer au suivant. Cela limite l'impact d'une erreur.

Exemple de vérification de récupération

Supposons que vous ayez accidentellement supprimé POSTGRES_PASSWORD du fichier .env, et que le conteneur de base de données ne démarre pas. Les journaux peuvent afficher :

Error: Database is uninitialized and superuser password is not specified.

Pour récupérer, restaurez la variable, puis recréez le service :

docker compose up -d db

Liste de contrôle opérationnelle

Pour garantir des opérations fiables avec les variables d'environnement Docker Compose, intégrez la liste de contrôle suivante dans votre flux de travail.

Liste de contrôle pré-déploiement

  • [ ] Confirmer que les versions de Docker et Docker Compose sont cohérentes dans tous les environnements.
  • [ ] S'assurer que le fichier .env existe et contient toutes les variables requises (ou que des valeurs par défaut sont définies).
  • [ ] Exécuter docker compose config et inspecter visuellement la configuration résolue.
  • [ ] Vérifier l'absence de valeurs vides qui pourraient indiquer des variables manquantes.
  • [ ] Vérifier que les valeurs sensibles ne sont pas codées en dur dans les fichiers Compose ; utiliser des secrets ou une injection externe.
  • [ ] Tester avec docker compose --env-file .env.staging config pour les valeurs spécifiques à la préproduction.

Liste de contrôle de déploiement

  • [ ] Utiliser docker compose up -d pour appliquer les modifications.
  • [ ] Surveiller docker compose ps pour confirmer que les services sont en cours d'exécution.
  • [ ] Vérifier les journaux avec docker compose logs <service> pour les erreurs liées à l'environnement.
  • [ ] Vérifier les variables d'environnement à l'intérieur des conteneurs en utilisant docker compose exec <service> env.

Vérification post-déploiement

  • [ ] Exécuter des tests de fumée qui exercent la fonctionnalité du service.
  • [ ] Valider que les secrets sont montés correctement et accessibles aux conteneurs.
  • [ ] S'assurer qu'aucune variable d'environnement de l'hôte non prévue n'a fui dans les conteneurs (comparer avec la liste prévue).

Maintenance continue

  • [ ] Mettre régulièrement à jour les fichiers .env et les valeurs secrètes, et faire tourner les informations d'identification.
  • [ ] Examiner les modifications des fichiers Compose pour l'utilisation des variables d'environnement lors des revues de code.
  • [ ] Documenter les variables d'environnement requises pour chaque service dans le README ou les procédures.
  • [ ] Exécuter périodiquement docker compose config pour détecter les dérives.

En suivant cette liste de contrôle, vous pouvez minimiser le risque d'erreurs de configuration des variables d'environnement et récupérer rapidement en cas de problème.

Conclusion

Les variables d'environnement Docker Compose sont un moyen flexible et puissant de gérer la configuration à travers les environnements. En comprenant les concepts avancés tels que la précédence, l'interpolation et la gestion des secrets, vous pouvez créer des déploiements robustes et sécurisés. Ce guide a fourni un chemin de mise en œuvre pratique : commencez par un inventaire clair de votre environnement, suivez des pratiques de configuration sûres, vérifiez minutieusement avec des commandes de diagnostic, et préparez-vous aux modes de défaillance avec des stratégies de retour arrière. Utilisez la liste de contrôle opérationnelle comme un cadre reproductible pour votre équipe.

Une compréhension claire de ces mécanismes internes réduit les retouches et permet une collaboration plus fluide entre le développement et les opérations. Commencez par un scénario pilote étroit pour valider vos modèles, puis passez à des configurations plus complexes. Avec ces outils, vous pouvez gérer en toute confiance les variables d'environnement dans Docker Compose et éviter les écueils courants.

Recherches connexes

Score de qualité de l’article

Utilité pour le lecteur 100%
  • check_circle Guide prêt à lire
  • check_circle Exemples pratiques inclus
  • check_circle URL d’article optimisée pour le SEO