Migrer vers Compose v2

Table des matières

Depuis juillet 2023, Compose v1 a cessé de recevoir des mises à jour. Il n'est également plus disponible dans les nouvelles versions de Docker Desktop.

Compose v2, qui a été publié pour la première fois en 2020, est inclus avec toutes les versions actuellement supportées de Docker Desktop. Il offre une expérience CLI améliorée, des performances de construction améliorées avec BuildKit, et un développement continu de nouvelles fonctionnalités.

Comment puis-je passer à Compose v2 ?

La façon la plus simple et recommandée est de s'assurer d'avoir la dernière version de Docker Desktop, qui intègre le Docker Engine et la plateforme Docker CLI incluant Compose v2.

Avec Docker Desktop, Compose v2 est toujours accessible comme docker compose.

Pour les installations manuelles sur Linux, vous pouvez obtenir Compose v2 soit en :

Utilisant le dépôt de Docker (recommandé)
Téléchargeant et installant manuellement

Quelles sont les différences entre Compose v1 et Compose v2 ?

`docker-compose` vs `docker compose`

Contrairement à Compose v1, Compose v2 s'intègre dans la plateforme Docker CLI et la syntaxe de ligne de commande recommandée est docker compose.

La plateforme Docker CLI fournit un ensemble cohérent et prévisible d'options et de drapeaux, comme la variable d'environnement DOCKER_HOST ou le drapeau de ligne de commande --context.

Ce changement vous permet d'utiliser tous les drapeaux partagés sur la commande racine docker. Par exemple, docker --log-level=debug --tls compose up active la journalisation de débogage du Docker Engine ainsi que s'assurer que TLS est utilisé pour la connexion.

Tip

Mettez à jour les scripts pour utiliser Compose v2 en remplaçant le trait d'union (-) par un espace, en utilisant docker compose au lieu de docker-compose.

Noms des conteneurs de service

Compose génère des noms de conteneur basés sur le nom du projet, le nom du service, et le compteur d'échelle/réplique.

Dans Compose v1, un trait de soulignement (_) était utilisé comme séparateur de mots. Dans Compose v2, un trait d'union (-) est utilisé comme séparateur de mots.

Les traits de soulignement ne sont pas des caractères valides dans les noms d'hôte DNS. En utilisant un trait d'union à la place, Compose v2 s'assure que les conteneurs de service peuvent être accessibles sur le réseau via des noms d'hôte cohérents et prévisibles.

Par exemple, exécuter la commande Compose -p myproject up --scale=1 svc résulte en un conteneur nommé myproject_svc_1 avec Compose v1 et un conteneur nommé myproject-svc-1 avec Compose v2.

Tip

Dans Compose v2, le drapeau global --compatibility ou la variable d'environnement COMPOSE_COMPATIBILITY préserve le comportement Compose v1 d'utiliser des traits de soulignement (_) comme séparateur de mots. Comme cette option doit être spécifiée pour chaque commande Compose v2 exécutée, il est recommandé de ne l'utiliser que comme mesure temporaire lors de la transition vers Compose v2.

Drapeaux de ligne de commande et sous-commandes

Compose v2 supporte presque tous les drapeaux et sous-commandes de Compose V1, donc dans la plupart des cas, il peut être utilisé comme un remplacement direct dans les scripts.

Non supporté dans v2

Les éléments suivants ont été dépréciés dans Compose v1 et ne sont pas supportés dans Compose v2 :

docker-compose scale. Utilisez docker compose up --scale à la place.
docker-compose rm --all

Différent dans v2

Les éléments suivants se comportent différemment entre Compose v1 et v2 :

	Compose v1	Compose v2
`--compatibility`	Déprécié. Migre les champs YAML basés sur la version de schéma héritée.	Utilise `_` comme séparateur de mots pour les noms de conteneur au lieu de `-` pour correspondre à v1.
`ps --filter KEY-VALUE`	Non documenté. Permet le filtrage par propriétés de service arbitraires.	Permet seulement le filtrage par propriétés spécifiques, ex. `--filter=status=running`.

Variables d'environnement

Le comportement des variables d'environnement dans Compose v1 n'était pas formellement documenté et se comportait de manière incohérente dans certains cas particuliers.

Pour Compose v2, la section Variables d'environnement couvre à la fois la précédence ainsi que l' interpolation de fichier .env et inclut de nombreux exemples couvrant des situations délicates comme l'échappement de guillemets imbriqués.

Vérifiez si :

Votre projet utilise plusieurs niveaux de surcharge de variables d'environnement, par exemple fichier .env et drapeaux CLI --env.
Toute valeur de fichier .env a des séquences d'échappement ou des guillemets imbriqués.
Toute valeur de fichier .env contient des signes $ littéraux. C'est courant avec les projets PHP.
Toute valeur de variable utilise une syntaxe d'expansion avancée, par exemple ${VAR:?error}.

Tip

Exécutez docker compose config sur le projet pour prévisualiser la configuration après que Compose v2 ait effectué l'interpolation pour vérifier que les valeurs apparaissent comme attendu.

Maintenir la rétrocompatibilité avec Compose v1 est typiquement réalisable en s'assurant que les valeurs littérales (pas d'interpolation) sont entre guillemets simples et les valeurs qui devraient avoir l'interpolation appliquée sont entre guillemets doubles.

Que signifie cela pour mes projets qui utilisent Compose v1 ?

Pour la plupart des projets, passer à Compose v2 ne nécessite aucun changement au YAML Compose ou à votre flux de travail de développement.

Il est recommandé de s'adapter à la nouvelle façon préférée d'exécuter Compose v2, qui est d'utiliser docker compose au lieu de docker-compose. Cela fournit une flexibilité supplémentaire et supprime l'exigence d'un alias de compatibilité docker-compose.

Cependant, Docker Desktop continue de supporter un alias docker-compose pour rediriger les commandes vers docker compose pour la commodité et une meilleure compatibilité avec les outils et scripts tiers.

Y a-t-il autre chose que je dois savoir avant de passer ?

Migrer les projets en cours d'exécution

Dans v1 et v2, exécuter up sur un projet Compose recrée les conteneurs de service selon les besoins. Il compare l'état réel dans le Docker Engine à la configuration de projet résolue, qui inclut le YAML Compose, les variables d'environnement, et les drapeaux de ligne de commande.

Parce que Compose v1 et v2 nomment les conteneurs de service différemment, exécuter up en utilisant v2 la première fois sur un projet avec des services en cours d'exécution lancés à l'origine par v1, résulte en des conteneurs de service étant recréés avec des noms mis à jour.

Notez que même si le drapeau --compatibility est utilisé pour préserver le style de nommage v1, Compose doit encore recréer les conteneurs de service lancés à l'origine par v1 la première fois que up est exécuté par v2 pour migrer l'état interne.

Utiliser Compose v2 avec Docker-in-Docker

Compose v2 est maintenant inclus dans l'image officielle Docker sur Docker Hub.

De plus, une nouvelle image docker/compose-bin sur Docker Hub emballe la dernière version de Compose v2 pour utilisation dans les constructions multi-étapes.

Puis-je encore utiliser Compose v1 si je le veux ?

Oui. Vous pouvez encore télécharger et installer les paquets Compose v1, mais vous n'obtiendrez pas de support de Docker si quelque chose casse.

Warning

La version finale de Compose v1, version 1.29.2, était le 10 mai 2021. Ces paquets n'ont reçu aucune mise à jour de sécurité depuis. Utilisez à vos propres risques.