Invalidation du cache de construction

Table des matières

Lors de la construction d'une image, Docker parcourt les instructions de votre Dockerfile, en les exécutant dans l'ordre spécifié. Pour chaque instruction, le constructeur vérifie s'il peut réutiliser l'instruction depuis le cache de construction.

Règles générales

Les règles de base de l'invalidation du cache de construction sont les suivantes :

Le constructeur commence par vérifier si l'image de base est déjà en cache. Chaque instruction suivante est comparée aux couches mises en cache. Si aucune couche mise en cache ne correspond exactement à l'instruction, le cache est invalidé.
Dans la plupart des cas, la comparaison de l'instruction du Dockerfile avec la couche mise en cache correspondante est suffisante. Cependant, certaines instructions nécessitent des vérifications et des explications supplémentaires.
Pour les instructions ADD et COPY, et pour les instructions RUN avec des montages de type bind (RUN --mount=type=bind), le constructeur calcule une somme de contrôle de cache à partir des métadonnées de fichier pour déterminer si le cache est valide. Lors de la recherche dans le cache, le cache est invalidé si les métadonnées de fichier ont changé pour l'un des fichiers impliqués.

L'heure de modification d'un fichier (mtime) n'est pas prise en compte lors du calcul de la somme de contrôle du cache. Si seul le mtime des fichiers copiés a changé, le cache n'est pas invalidé.
À l'exception des commandes ADD et COPY, la vérification du cache ne regarde pas les fichiers dans le conteneur pour déterminer une correspondance de cache. Par exemple, lors du traitement d'une commande RUN apt-get -y update, les fichiers mis à jour dans le conteneur ne sont pas examinés pour déterminer s'il existe une correspondance de cache. Dans ce cas, seule la chaîne de commande elle-même est utilisée pour trouver une correspondance.

Une fois le cache invalidé, toutes les commandes Dockerfile suivantes génèrent de nouvelles images et le cache n'est pas utilisé.

Si votre construction contient plusieurs couches et que vous souhaitez vous assurer que le cache de construction est réutilisable, ordonnez les instructions des moins fréquemment modifiées aux plus fréquemment modifiées lorsque cela est possible.

Instructions RUN

Le cache pour les instructions RUN n'est pas invalidé automatiquement entre les constructions. Supposons que vous ayez une étape dans votre Dockerfile pour installer curl :

FROM alpine:3.21 AS install
RUN apk add curl

Cela ne signifie pas que la version de curl dans votre image est toujours à jour. Reconstruire l'image une semaine plus tard vous donnera toujours les mêmes paquets qu'auparavant. Pour forcer une ré-exécution de l'instruction RUN, vous pouvez :

Vous assurer qu'une couche précédente a changé
Vider le cache de construction avant la construction en utilisant docker builder prune
Utiliser les options --no-cache ou --no-cache-filter

L'option --no-cache-filter vous permet de spécifier une étape de construction spécifique pour invalider le cache :

$ docker build --no-cache-filter install .

Secrets de construction

Le contenu des secrets de construction ne fait pas partie du cache de construction. Changer la valeur d'un secret n'entraîne pas l'invalidation du cache.

Si vous souhaitez forcer l'invalidation du cache après avoir changé la valeur d'un secret, vous pouvez passer un argument de construction avec une valeur arbitraire que vous changez également lorsque vous changez le secret. Les arguments de construction entraînent l'invalidation du cache.

FROM alpine
ARG CACHEBUST
RUN --mount=type=secret,id=TOKEN,env=TOKEN \
    some-command ...

$ TOKEN="tkn_pat123456" docker build --secret id=TOKEN --build-arg CACHEBUST=1 .

Les propriétés des secrets telles que les ID et les chemins de montage participent à la somme de contrôle du cache, et entraînent l'invalidation du cache si elles sont modifiées.