Vue d'ensemble des exportateurs

Table des matières

Les exportateurs sauvegardent vos résultats de build vers un type de sortie spécifié. Vous spécifiez l'exportateur à utiliser avec l'option CLI --output. Buildx prend en charge les exportateurs suivants :

image : exporte le résultat de build vers une image de conteneur.
registry : exporte le résultat de build vers une image de conteneur et la pousse vers le registre spécifié.
local : exporte le système de fichiers racine de build vers un répertoire local.
tar : emballe le système de fichiers racine de build dans une archive tar locale.
oci : exporte le résultat de build vers le système de fichiers local au format OCI image layout.
docker : exporte le résultat de build vers le système de fichiers local au format Docker Image Specification v1.2.0.
cacheonly : n'exporte pas de sortie de build, mais exécute le build et crée un cache.

Utilisation des exportateurs

Pour spécifier un exportateur, utilisez la syntaxe de commande suivante :

$ docker buildx build --tag <registry>/<image> \
  --output type=<TYPE> .

La plupart des cas d'usage courants ne nécessitent pas de spécifier explicitement quel exportateur utiliser. Vous n'avez besoin de spécifier l'exportateur que si vous avez l'intention de personnaliser la sortie, ou si vous voulez la sauvegarder sur disque. Les options --load et --push permettent à Buildx de déduire les paramètres d'exportateur à utiliser.

Par exemple, si vous utilisez l'option --push en combinaison avec --tag, Buildx utilise automatiquement l'exportateur image, et configure l'exportateur pour pousser les résultats vers le registre spécifié.

Pour obtenir la flexibilité complète des différents exportateurs que BuildKit a à offrir, vous utilisez le flag --output qui vous permet de configurer les options d'exportateur.

Cas d'usage

Chaque type d'exportateur est conçu pour différents cas d'usage. Les sections suivantes décrivent quelques scénarios courants, et comment vous pouvez utiliser les exportateurs pour générer la sortie dont vous avez besoin.

Charger vers le magasin d'images

Buildx est souvent utilisé pour construire des images de conteneur qui peuvent être chargées dans un magasin d'images. C'est là qu'intervient l'exportateur docker. L'exemple suivant montre comment construire une image en utilisant l'exportateur docker, et faire en sorte que cette image soit chargée dans le magasin d'images local, en utilisant l'option --output :

$ docker buildx build \
  --output type=docker,name=<registry>/<image> .

La CLI Buildx utilisera automatiquement l'exportateur docker et le chargera dans le magasin d'images si vous fournissez les options --tag et --load :

$ docker buildx build --tag <registry>/<image> --load .

La construction d'images en utilisant le driver docker sont automatiquement chargées dans le magasin d'images local.

Les images chargées dans le magasin d'images sont disponibles pour docker run immédiatement après la fin du build, et vous les verrez dans la liste des images lorsque vous exécutez la commande docker images.

Pousser vers un registre

Pour pousser une image construite vers un registre de conteneurs, vous pouvez utiliser les exportateurs registry ou image.

Lorsque vous passez l'option --push à la CLI Buildx, vous demandez à BuildKit de pousser l'image construite vers le registre spécifié :

$ docker buildx build --tag <registry>/<image> --push .

En interne, cela utilise l'exportateur image, et définit le paramètre push. C'est la même chose qu'utiliser la commande longue suivante en utilisant l'option --output :

$ docker buildx build \
  --output type=image,name=<registry>/<image>,push=true .

Vous pouvez aussi utiliser l'exportateur registry, qui fait la même chose :

$ docker buildx build \
  --output type=registry,name=<registry>/<image> .

Exporter la disposition d'image vers un fichier

Vous pouvez utiliser soit les exportateurs oci soit docker pour sauvegarder les résultats de build vers une disposition d'image sur votre système de fichiers local. Ces deux exportateurs génèrent un fichier d'archive tar contenant la disposition d'image correspondante. Le paramètre dest définit le chemin de sortie cible pour l'archive tar.

$ docker buildx build --output type=oci,dest=./image.tar .
[+] Building 0.8s (7/7) FINISHED
 ...
 => exporting to oci image format                                                                     0.0s
 => exporting layers                                                                                  0.0s
 => exporting manifest sha256:c1ef01a0a0ef94a7064d5cbce408075730410060e253ff8525d1e5f7e27bc900        0.0s
 => exporting config sha256:eadab326c1866dd247efb52cb715ba742bd0f05b6a205439f107cf91b3abc853          0.0s
 => sending tarball                                                                                   0.0s
$ mkdir -p out && tar -C out -xf ./image.tar
$ tree out
out
├── blobs
│   └── sha256
│       ├── 9b18e9b68314027565b90ff6189d65942c0f7986da80df008b8431276885218e
│       ├── c78795f3c329dbbbfb14d0d32288dea25c3cd12f31bd0213be694332a70c7f13
│       ├── d1cf38078fa218d15715e2afcf71588ee482352d697532cf316626164699a0e2
│       ├── e84fa1df52d2abdfac52165755d5d1c7621d74eda8e12881f6b0d38a36e01775
│       └── fe9e23793a27fe30374308988283d40047628c73f91f577432a0d05ab0160de7
├── index.json
├── manifest.json
└── oci-layout

Exporter le système de fichiers

Si vous ne voulez pas construire une image à partir de vos résultats de build, mais plutôt exporter le système de fichiers qui a été construit, vous pouvez utiliser les exportateurs local et tar.

L'exportateur local déballe le système de fichiers dans une structure de répertoires à l'emplacement spécifié. L'exportateur tar crée un fichier d'archive tarball.

$ docker buildx build --output type=local,dest=<path/to/output> .

L'exportateur local est utile dans les builds multi-étapes car il vous permet d'exporter seulement un nombre minimal d'artefacts de build, tels que des binaires autonomes.

Export cache uniquement

L'exportateur cacheonly peut être utilisé si vous voulez juste exécuter un build, sans exporter aucune sortie. Cela peut être utile si, par exemple, vous voulez exécuter un build de test. Ou, si vous voulez d'abord exécuter le build, et créer des exports en utilisant des commandes subséquentes. L'exportateur cacheonly crée un cache de build, donc tous les builds successifs sont instantanés.

$ docker buildx build --output type=cacheonly

Si vous ne spécifiez pas d'exportateur, et que vous ne fournissez pas d'options raccourcies comme --load qui sélectionnent automatiquement l'exportateur approprié, Buildx utilise par défaut l'exportateur cacheonly. Sauf si vous construisez en utilisant le driver docker, auquel cas vous utilisez l'exportateur docker.

Buildx enregistre un message d'avertissement lors de l'utilisation de cacheonly par défaut :

$ docker buildx build .
WARNING: No output specified with docker-container driver.
         Build result will only remain in the build cache.
         To push result image into registry use --push or
         to load image into docker use --load

Exportateurs multiples

Requires: Docker Buildx 0.13.0 and later

Vous pouvez utiliser plusieurs exportateurs pour n'importe quel build donné en spécifiant le flag --output plusieurs fois. Cela nécessite à la fois Buildx et BuildKit version 0.13.0 ou ultérieure.

L'exemple suivant exécute un seul build, en utilisant trois exportateurs différents :

L'exportateur registry pour pousser l'image vers un registre
L'exportateur local pour extraire les résultats de build vers le système de fichiers local
Le flag --load (un raccourci pour l'exportateur image) pour charger les résultats dans le magasin d'images local.

$ docker buildx build \
  --output type=registry,tag=<registry>/<image> \
  --output type=local,dest=<path/to/output> \
  --load .

Options de configuration

Cette section décrit quelques options de configuration disponibles pour les exportateurs.

Les options décrites ici sont communes à au moins deux types d'exportateurs ou plus. De plus, les différents types d'exportateurs prennent également en charge des paramètres spécifiques. Voir la page détaillée sur chaque exportateur pour plus d'informations sur les paramètres de configuration qui s'appliquent.

Les paramètres communs décrits ici sont :

Compression
Type de média OCI

Compression

Lorsque vous exportez une sortie compressée, vous pouvez configurer l'algorithme de compression exact et le niveau à utiliser. Bien que les valeurs par défaut fournissent une bonne expérience prête à l'emploi, vous pouvez souhaiter ajuster les paramètres pour optimiser les coûts de stockage par rapport aux coûts de calcul. Changer les paramètres de compression peut réduire l'espace de stockage requis, et améliorer les temps de téléchargement d'image, mais augmentera les temps de build.

Pour sélectionner l'algorithme de compression, vous pouvez utiliser l'option compression. Par exemple, pour construire une image avec compression=zstd :

$ docker buildx build \
  --output type=image,name=<registry>/<image>,push=true,compression=zstd .

Utilisez l'option compression-level=<value> aux côtés du paramètre compression pour choisir un niveau de compression pour les algorithmes qui le prennent en charge :

0-9 pour gzip et estargz
0-22 pour zstd

En règle générale, plus le nombre est élevé, plus le fichier résultant sera petit, et plus la compression prendra de temps à s'exécuter.

Utilisez l'option force-compression=true pour forcer la recompression des couches importées d'une image précédente, si l'algorithme de compression demandé est différent de l'algorithme de compression précédent.

Note

Les méthodes de compression gzip et estargz utilisent le package compress/gzip, tandis que zstd utilise le package github.com/klauspost/compress/zstd.

Types de média OCI

Les exportateurs image, registry, oci et docker créent des images de conteneur. Ces exportateurs prennent en charge à la fois les types de média Docker (par défaut) et les types de média OCI.

Pour exporter des images avec des types de média OCI définis, utilisez la propriété oci-mediatypes.

$ docker buildx build \
  --output type=image,name=<registry>/<image>,push=true,oci-mediatypes=true .

Prochaines étapes

Lisez à propos de chacun des exportateurs pour apprendre comment ils fonctionnent et comment les utiliser :