Syntaxe personnalisée de Dockerfile

Table des matières

Frontend Dockerfile

BuildKit prend en charge le chargement dynamique de frontends à partir d'images de conteneurs. Pour utiliser un frontend Dockerfile externe, la première ligne de votre Dockerfile doit définir la directive syntax pointant vers l'image spécifique que vous souhaitez utiliser :

# syntax=[référence d'image distante]

Par exemple :

# syntax=docker/dockerfile:1
# syntax=docker.io/docker/dockerfile:1
# syntax=example.com/user/repo:tag@sha256:abcdef...

Vous pouvez également utiliser l'argument de build prédéfini BUILDKIT_SYNTAX pour définir la référence de l'image du frontend sur la ligne de commande :

$ docker build --build-arg BUILDKIT_SYNTAX=docker/dockerfile:1 .

Ceci définit l'emplacement de la syntaxe Dockerfile qui est utilisée pour construire le Dockerfile. Le backend BuildKit permet d'utiliser de manière transparente des implémentations externes qui sont distribuées sous forme d'images Docker et s'exécutent dans un environnement de bac à sable de conteneur.

Les implémentations Dockerfile personnalisées vous permettent de :

Obtenir automatiquement des corrections de bugs sans mettre à jour le démon Docker
S'assurer que tous les utilisateurs utilisent la même implémentation pour construire votre Dockerfile
Utiliser les dernières fonctionnalités sans mettre à jour le démon Docker
Essayer de nouvelles fonctionnalités ou des fonctionnalités tierces avant qu'elles ne soient intégrées au démon Docker
Utiliser des définitions de build alternatives, ou créer les vôtres
Construire votre propre frontend Dockerfile avec des fonctionnalités personnalisées

Note

BuildKit est livré avec un frontend Dockerfile intégré, mais il est recommandé d'utiliser une image externe pour s'assurer que tous les utilisateurs utilisent la même version sur le builder et pour récupérer les corrections de bugs automatiquement sans attendre une nouvelle version de BuildKit ou de Docker Engine.

Versions officielles

Docker distribue des versions officielles des images qui peuvent être utilisées pour construire des Dockerfiles sous le dépôt docker/dockerfile sur Docker Hub. Il existe deux canaux où de nouvelles images sont publiées : stable et labs.

Canal stable

Le canal stable suit le versionnement sémantique. Par exemple :

docker/dockerfile:1 - maintenu à jour avec la dernière version mineure et de correctif 1.x.x.
docker/dockerfile:1.2 - maintenu à jour avec la dernière version de correctif 1.2.x, et cesse de recevoir des mises à jour une fois la version 1.3.0 publiée.
docker/dockerfile:1.2.1 - immuable : jamais mis à jour.

Nous recommandons d'utiliser docker/dockerfile:1, qui pointe toujours vers la dernière version stable de la syntaxe version 1, et reçoit à la fois les mises à jour "mineures" et "de correctif" pour le cycle de publication de la version 1. BuildKit vérifie automatiquement les mises à jour de la syntaxe lors d'un build, s'assurant que vous utilisez la version la plus récente.

Si une version spécifique est utilisée, telle que 1.2 ou 1.2.1, le Dockerfile doit être mis à jour manuellement pour continuer à recevoir des corrections de bugs et de nouvelles fonctionnalités. Les anciennes versions du Dockerfile restent compatibles avec les nouvelles versions du builder.

Canal labs

Le canal labs fournit un accès anticipé aux fonctionnalités de Dockerfile qui ne sont pas encore disponibles dans le canal stable. Les images labs sont publiées en même temps que les versions stables, et suivent le même modèle de version, mais utilisent le suffixe -labs, par exemple :

docker/dockerfile:labs - dernière version sur le canal labs.
docker/dockerfile:1-labs - identique à dockerfile:1, avec les fonctionnalités expérimentales activées.
docker/dockerfile:1.2-labs - identique à dockerfile:1.2, avec les fonctionnalités expérimentales activées.
docker/dockerfile:1.2.1-labs - immuable : jamais mis à jour. Identique à dockerfile:1.2.1, avec les fonctionnalités expérimentales activées.

Choisissez le canal qui correspond le mieux à vos besoins. Si vous souhaitez bénéficier de nouvelles fonctionnalités, utilisez le canal labs. Les images du canal labs contiennent toutes les fonctionnalités du canal stable, plus des fonctionnalités en accès anticipé. Les fonctionnalités stables du canal labs suivent le versionnement sémantique, mais les fonctionnalités en accès anticipé ne le font pas, et les nouvelles versions peuvent ne pas être rétrocompatibles. Épinglez la version pour éviter d'avoir à gérer des changements de rupture.

Autres ressources

Pour la documentation sur les fonctionnalités labs, les builds master et les versions de fonctionnalités nocturnes, consultez la description dans le dépôt source de BuildKit sur GitHub. Pour une liste complète des images disponibles, visitez le dépôt docker/dockerfile sur Docker Hub, et le dépôt docker/dockerfile-upstream sur Docker Hub pour les builds de développement.