Comment mettre à niveau vers Docker Compose v2

Après presque un an en version bêta, Docker Compose v2 est généralement disponible en tant que version stable de l'outil de gestion de conteneurs. La plupart des utilisateurs devraient pouvoir effectuer le changement aujourd'hui. Dans ce guide, nous vous montrerons comment préparer et appliquer votre mise à niveau.

Quoi de neuf dans la v2 ?

Docker Compose v2 apporte les fonctionnalités familières de Compose à la CLI docker habituelle. Au lieu d'interagir avec un binaire docker-compose séparé, vous utilisez maintenant docker compose. Compose est intégré à Docker.

Vous pouvez remplacer les commandes comme ceci :

$ docker-compose up -d

Avec l'invocation suivante :

$ docker compose up -d

Compose v2 est également livré avec quelques nouvelles fonctionnalités qui améliorent l'expérience utilisateur :

Vous pouvez utiliser docker compose cp pour copier des fichiers entre votre hôte et vos conteneurs.
Les fournisseurs de cloud sont des cibles valides, vous permettant de composer docker pour déployer des conteneurs sur Amazon ECS ou Microsoft ACI.
Les profils de service sont entièrement pris en charge, ce qui facilite l'inclusion sélective de conteneurs dans une pile.
Gestion de projet simplifiée : exécutez des commandes sans être dans le même répertoire que votre fichier docker-compose.yml avec docker compose --project-name my-project stop . Il existe également une nouvelle commande docker compose ls qui répertorie tous vos projets Compose.
Docker Compose est désormais écrit en Go, comme Docker lui-même, au lieu d'être un utilitaire Python distinct. Cela permet à Compose de réutiliser le code de la CLI Docker principale, créant ainsi un comportement plus cohérent.

Incompatibilités avec la v1

Compose v2 est compatible avec v1 dans presque tous les cas d'utilisation. Vous n'avez pas besoin de modifier vos fichiers docker-compose.yml ou d'apprendre de nouvelles commandes, à l'exception du passage de docker-compose à docker compose. Si vous avez votre propre outil autour de la commande docker-compose, vous pouvez le modifier pour appeler docker compose à la place.

Alors que la plupart des migrations devraient être simples, Compose v2 introduit quelques changements de rupture qui pourraient avoir un impact sur des cas d'utilisation spécifiques :

Les conteneurs sont désormais créés avec des traits d'union dans leurs noms au lieu de traits de soulignement. Cela signifie qu'un service appelé db dans le projet app va maintenant créer un conteneur appelé app-db, au lieu de app_db. Cela pourrait casser les scripts qui s'attendent à ce que l'ancien format de nom de conteneur soit utilisé. La modification peut actuellement être désactivée en incluant l'indicateur --compatibility avec les commandes docker compose.
docker compose build construit avec BuildKit par défaut. BuildKit est le système de construction d'image moderne de Docker qui est capable de construire beaucoup plus rapidement. BuildKit est le système de construction recommandé, mais il reste quelques incompatibilités avec le mécanisme de construction hérité qui pourraient causer des problèmes dans certaines circonstances. Vous pouvez désactiver BuildKit en définissant la variable d'environnement DOCKER_BUILDKIT=0 avant d'exécuter les commandes docker compose.
Certains indicateurs de commande obsolètes ont été supprimés. docker compose rm --all n'est pas pris en charge et la commande docker compose scale est omise dans faveur de docker composer up --scale. Vous devrez modifier tous les scripts qui reposent sur les versions docker-compose de ces commandes.

Mise à niveau sous Linux

Bien que Compose s'intègre désormais à la CLI Docker, il n'est pas activé par défaut dans Docker Engine. Vous pouvez installer Compose v2 en l'ajoutant en tant que plug-in Docker CLI. Vous devez disposer de Docker version v20.10.13 ou ultérieure.

Mettez à jour vos référentiels de packages et installez docker-compose-plugin :

$ sudo apt update
$ sudo apt install docker-compose-plugin

Vérifiez que l'installation a réussi en récupérant la version de Docker Compose :

$ docker compose version
Docker Compose version v2.3.3

Vous pouvez désormais supprimer Docker Compose v1, sauf si vous souhaitez le conserver pour assurer la compatibilité avec les scripts hérités. docker-compose (v1) et docker compose (v2) peuvent coexister si vous en avez besoin. Si vous supprimez la v1, elle se trouve normalement sous la forme d'un binaire unique dans /usr/local/bin/docker-compose :

$ sudo rm /usr/local/bin/docker-compose

Vous pouvez maintenant configurer un alias de shell pour rediriger docker-compose vers docker compose. Cela vous permettrait de continuer à utiliser des scripts qui attendent Compose v1, en utilisant votre nouvelle installation v2.

$ echo 'alias docker-compose="docker compose"' >> ~/.bashrc
$ source ~/.bashrc
$ docker-compose version
Docker Compose version v2.3.3

Vous êtes maintenant prêt à commencer à gérer vos conteneurs avec Compose v2.

Mise à niveau avec Docker Desktop pour Windows et Mac

Compose v2 est inclus avec les versions 3.4 et ultérieures de Docker Desktop. La v2 est devenue la version par défaut de Compose dans la v4.4.2 ; si vous avez déjà effectué la mise à niveau, vous pouvez utiliser docker compose dès aujourd'hui.

La v4.4.2 aliase également docker-compose en docker compose automatiquement. Compose v1 est inaccessible par défaut. Vous pouvez désactiver cet alias en exécutant la commande docker-compose disable-v2 ou en décochant la case Utiliser Docker Compose v2 dans la page des paramètres de Docker Desktop. La commande docker-compose reviendra alors à l'utilisation de Compose v1.

Et après?

Compose v1 reste pris en charge pour les problèmes de sécurité et les corrections de bogues de « gravité élevée » au cours des six prochains mois. Ce support prendra fin en octobre 2022. La v1 sera alors considérée comme en fin de vie, son utilisation doit donc être évitée. À ce stade, Docker Desktop sera mis à jour pour uniquement prendre en charge la v2. Vous devrez utiliser docker compose car l'alias docker-compose sera supprimé. Vous devrez rester sur une version plus ancienne si vous avez toujours besoin de la v1.

Vous pouvez continuer à utiliser v1 indéfiniment en l'installant en tant que binaire autonome. Vous pouvez les trouver publiés pour Windows, Mac et Linux sur la page des versions GitHub du projet. Bien que ces binaires continueront de fonctionner indéfiniment, la plupart des projets devraient viser à passer à la v2 dans un avenir proche. Cela vous donnera accès à toutes les corrections de bogues, mises à jour de sécurité et nouvelles fonctionnalités des versions modernes de Compose v2.

Résumé

Docker Compose v2 est désormais la version stable de Docker Compose. Les utilisateurs de Docker Desktop auront été mis à niveau automatiquement. Les installations Linux de Docker Engine sont prises en charge par le nouveau plugin CLI docker-compose-plugin.

La prise en charge de Compose v1 se termine dans moins de six mois. Vous devez donc vérifier la compatibilité de vos scripts, puis adopter la v2 dans les semaines à venir. Vous pourrez utiliser Compose dans la CLI docker et bénéficier des fonctionnalités v2 telles que les profils de service et la commande docker compose ls.