⚠️ Traduction non officielle - Cette documentation est une traduction communautaire non officielle de Docker.

Backends de stockage de cache

Table des matières

Pour garantir des constructions rapides, BuildKit met automatiquement en cache le résultat de la construction dans son propre cache interne. De plus, BuildKit prend également en charge l'exportation du cache de construction vers un emplacement externe, ce qui permet de l'importer dans des constructions futures.

Un cache externe devient presque essentiel dans les environnements de construction CI/CD. Ces environnements ont généralement peu ou pas de persistance entre les exécutions, mais il est toujours important de maintenir le temps d'exécution des constructions d'images aussi bas que possible.

Le pilote docker par défaut prend en charge les backends de cache inline, local, registry et gha, mais uniquement si vous avez activé le magasin d'images containerd. D'autres backends de cache nécessitent que vous sélectionniez un pilote différent.

Warning

Si vous utilisez des secrets ou des identifiants dans votre processus de construction, assurez-vous de les manipuler en utilisant l'option dédiée --secret. Gérer manuellement les secrets en utilisant COPY ou ARG pourrait entraîner des fuites d'identifiants.

Backends

Buildx prend en charge les backends de stockage de cache suivants :

  • inline : intègre le cache de construction dans l'image.

    Le cache inline est poussé vers le même emplacement que le résultat de sortie principal. Cela ne fonctionne qu'avec l'exportateur image.

  • registry : intègre le cache de construction dans une image séparée, et le pousse vers un emplacement dédié distinct du résultat de sortie principal.

  • local : écrit le cache de construction dans un répertoire local sur le système de fichiers.

  • gha : téléverse le cache de construction vers le cache GitHub Actions (bêta).

  • s3 : téléverse le cache de construction vers un bucket AWS S3 (non publié).

  • azblob : téléverse le cache de construction vers Azure Blob Storage (non publié).

Syntaxe de commande

Pour utiliser l'un des backends de cache, vous devez d'abord le spécifier lors de la construction avec l'option --cache-to pour exporter le cache vers votre backend de stockage de choix. Ensuite, utilisez l'option --cache-from pour importer le cache depuis le backend de stockage dans la construction actuelle. Contrairement au cache local de BuildKit (qui est toujours activé), tous les backends de stockage de cache doivent être explicitement exportés vers, et explicitement importés depuis.

Exemple de commande buildx utilisant le backend registry, avec importation et exportation de cache :

$ docker buildx build --push -t <registry>/<image> \
  --cache-to type=registry,ref=<registry>/<cache-image>[,parameters...] \
  --cache-from type=registry,ref=<registry>/<cache-image>[,parameters...] .
Warning

En règle générale, chaque cache écrit à un certain emplacement. Aucun emplacement ne peut être écrit deux fois, sans écraser les données précédemment mises en cache. Si vous voulez maintenir plusieurs caches délimités (par exemple, un cache par branche Git), alors assurez-vous d'utiliser différents emplacements pour le cache exporté.

Caches multiples

BuildKit prend en charge plusieurs exportateurs de cache, vous permettant de pousser le cache vers plus d'une destination. Vous pouvez également importer depuis autant de caches distants que vous le souhaitez. Par exemple, un modèle courant consiste à utiliser le cache à la fois de la branche courante et de la branche principale. L'exemple suivant montre l'importation de cache depuis plusieurs emplacements en utilisant le backend de cache registry :

$ docker buildx build --push -t <registry>/<image> \
  --cache-to type=registry,ref=<registry>/<cache-image>:<branch> \
  --cache-from type=registry,ref=<registry>/<cache-image>:<branch> \
  --cache-from type=registry,ref=<registry>/<cache-image>:main .

Options de configuration

Cette section décrit certaines options de configuration disponibles lors de la génération d'exportations de cache. Les options décrites ici sont communes à au moins deux ou plus types de backend. De plus, les différents types de backend prennent en charge des paramètres spécifiques également. Consultez la page détaillée sur chaque type de backend pour plus d'informations sur les paramètres de configuration qui s'appliquent.

Les paramètres communs décrits ici sont :

Mode de cache

Lors de la génération d'une sortie de cache, l'argument --cache-to accepte une option mode pour définir quelles couches inclure dans le cache exporté. Ceci est pris en charge par tous les backends de cache sauf pour le cache inline.

Le mode peut être défini sur l'une des deux options : mode=min ou mode=max. Par exemple, pour construire le cache avec mode=max avec le backend registry :

$ docker buildx build --push -t <registry>/<image> \
  --cache-to type=registry,ref=<registry>/<cache-image>,mode=max \
  --cache-from type=registry,ref=<registry>/<cache-image> .

Cette option n'est définie que lors de l'exportation d'un cache, en utilisant --cache-to. Lors de l'importation d'un cache (--cache-from), les paramètres pertinents sont automatiquement détectés.

En mode de cache min (par défaut), seules les couches qui sont exportées dans l'image résultante sont mises en cache, tandis qu'en mode de cache max, toutes les couches sont mises en cache, même celles des étapes intermédiaires.

Bien que le cache min soit généralement plus petit (ce qui accélère les temps d'importation/exportation et réduit les coûts de stockage), le cache max est plus susceptible d'obtenir plus de hits de cache. Selon la complexité et l'emplacement de votre construction, vous devriez expérimenter avec les deux paramètres pour trouver les résultats qui vous conviennent le mieux.

Compression de cache

Les options de compression de cache sont les mêmes que les options de compression de l'exportateur. Ceci est pris en charge par les backends de cache local et registry.

Par exemple, pour compresser le cache registry avec la compression zstd :

$ docker buildx build --push -t <registry>/<image> \
  --cache-to type=registry,ref=<registry>/<cache-image>,compression=zstd \
  --cache-from type=registry,ref=<registry>/<cache-image> .

Types de média OCI

Les options OCI du cache sont les mêmes que les options OCI de l'exportateur. Celles-ci sont prises en charge par les backends de cache local et registry.

Par exemple, pour exporter un cache de type média OCI, utilisez la propriété oci-mediatypes :

$ docker buildx build --push -t <registry>/<image> \
  --cache-to type=registry,ref=<registry>/<cache-image>,oci-mediatypes=true \
  --cache-from type=registry,ref=<registry>/<cache-image> .

Cette propriété n'a de sens qu'avec l'indicateur --cache-to. Lors de la récupération du cache, BuildKit détectera automatiquement les types de média corrects à utiliser.

Par défaut, le type de média OCI génère un index d'image pour l'image de cache. Certains registres OCI, comme Amazon ECR, ne prennent pas en charge le type de média d'index d'image : application/vnd.oci.image.index.v1+json. Si vous exportez des images de cache vers ECR, ou tout autre registre qui ne prend pas en charge les index d'images, définissez le paramètre image-manifest à true pour générer un manifeste d'image unique au lieu d'un index d'image pour l'image de cache :

$ docker buildx build --push -t <registry>/<image> \
  --cache-to type=registry,ref=<registry>/<cache-image>,oci-mediatypes=true,image-manifest=true \
  --cache-from type=registry,ref=<registry>/<cache-image> .
Note

Depuis BuildKit v0.21, image-manifest est activé par défaut.