Intro
La mise en cache des couches Docker transforme des builds d'images répétitifs de quelques minutes en quelques secondes, mais seulement lorsque les opérateurs savent observer, vérifier et récupérer du comportement du cache. Ce guide fournit des commandes actionnables et des exemples concrets pour les développeurs, les consultants DevOps et les équipes techniques de startups qui ont besoin de construire des images de manière fiable sans gaspiller du temps de calcul ou de débogage.
L'accent est mis sur la sécurité opérationnelle : observer avant de modifier, limiter le rayon d'impact, utiliser des espaces réservés au lieu de secrets, vérifier les résultats et documenter les chemins de récupération. Nous couvrons l'inventaire des versions et de l'environnement, la configuration sécurisée, la vérification et les diagnostics, les modes de défaillance et la récupération, une liste de contrôle opérationnelle et les pièges courants. Chaque section comprend des commandes concrètes, des sorties attendues et des conseils de décision.
À qui s'adresse ce guide : vous exécutez régulièrement docker build, vous avez vu des absences de cache mystérieuses, ou vous devez prouver que la mise en cache fonctionne avant de pousser vers CI. Si vous connaissez déjà les bases de Docker, ce guide affinera vos compétences en mise en cache avec des exemples pratiques et testables.
Inventaire des versions et de l'environnement
Avant de toucher à la mise en cache, confirmez vos versions de Docker et de BuildKit. Docker 18.09+ est livré avec BuildKit en tant que builder optionnel ; Docker 23+ l'active par défaut. Si vous utilisez une version plus ancienne de Docker, de nombreuses fonctionnalités de mise en cache n'existeront pas ou se comporteront différemment.
Observations en lecture seule d'abord :
# Vérifier les versions du client et du serveur Docker
docker version --format '{{.Client.Version}} {{.Server.Version}}'
# Vérifier le support de BuildKit (Docker 18.09+)
docker buildx version
# Lister les builders et voir lequel est actif
docker buildx ls
Sorties attendues :
docker versionaffiche les versions du client et du serveur. Si seul le client apparaît, le démon est inaccessible ou l'utilisateur manque de permissions.docker buildx versionimprime une version commegithub.com/docker/buildx v0.11.2si Buildx est installé.docker buildx lsliste les builders ; celui actif a un astérisque. Le builderdefaultutilise le BuildKit du démon Docker ; un driverdocker-containerséparé est souvent utilisé pour une mise en cache avancée.
Vérifier l'utilisation actuelle du cache de build :
# Afficher l'utilisation du disque par Docker, y compris le cache de build
docker system df
# Afficher l'utilisation détaillée du cache de build (nécessite BuildKit)
docker buildx du
Exemple de docker system df :
TYPE TOTAL ACTIVE SIZE RECLAIMABLE
Images 15 12 3.2GB 1.1GB (34%)
Containers 3 1 100MB 0B (0%)
Local Volumes 5 5 1.2GB 0B (0%)
Build Cache 28 0 2.5GB 2.5GB (100%)
Ici, le cache de build est entièrement récupérable car aucun build actif ne l'utilise. C'est normal après la fin des builds.
Vérification des fonctionnalités dépendantes de la version :
- Si vous avez besoin de montages de cache (
RUN --mount=type=cache), vous devez utiliser BuildKit. Le builder classique les ignore. - Si vous voulez envoyer le cache vers un registre pour CI, vous avez besoin de
docker/build-push-actionavec Buildx et le support du registre.
Impact sur la mise en cache des couches :
- La mise en cache des couches Docker est une fonctionnalité au niveau du builder. La version du démon et le driver de stockage peuvent affecter la recherche de cache, mais le builder détermine comment les couches sont créées et réutilisées.
- Comme BuildKit est maintenant le défaut, de nombreuses hypothèses de guide (comme
--no-cacheou--cache-from) doivent être comprises dans le contexte de BuildKit.
Prérequis pour une expérimentation sûre :
- Un projet de test avec un Dockerfile ayant au moins 4-5 instructions.
- Un compte Docker Hub ou un registre local pour les expériences de push/pull (optionnel mais utile pour
--cache-from). - Docker 23+ ou Docker Desktop dernière version.
Chemin de configuration sécurisé
Un Dockerfile adapté à la mise en cache est le premier changement de configuration. La règle d'or : ordonner les instructions du moins au plus fréquemment modifié. L'image de base, l'installation des dépendances et la copie du code source doivent être des couches séparées.
Plus petit changement justifié : réorganiser les instructions du Dockerfile.
Avant :
FROM node:18-alpine
WORKDIR /app
COPY . .
RUN npm install
CMD ["npm", "start"]
Après :
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
CMD ["npm", "start"]
Pourquoi cela fonctionne : COPY package*.json ./ crée une couche qui ne change que lorsque package.json ou package-lock.json change. La plupart des builds suivants réutiliseront la couche RUN npm install, ce qui économise du temps.
Vérifier le succès du cache avec un build :
# Premier build (pas de cache disponible)
docker build -t myapp:test .
# Deuxième build sans modifications
docker build -t myapp:test .
Lors du deuxième build, cherchez CACHED dans la sortie. Avec BuildKit, vous verrez des lignes comme :
=> [3/5] RUN npm install 0.0s
=> CACHED [4/5] COPY . . 0.0s
Le marqueur CACHED signifie que la couche a été réutilisée depuis le cache local. Si vous voyez RUN npm install se réexécuter et prendre du temps, quelque chose a invalidé la couche de copie.
Options de configuration qui affectent la mise en cache :
--no-cache: force un rebuild complet, en ignorant le cache. Utile pour la vérification CI.--cache-from: permet de spécifier des sources de cache externes, par exemple depuis un registre.--build-arg: les arguments de build deviennent des composants de la clé de cache. Changer un argument de build invalide les couches suivantes.--target: construire une étape spécifique peut limiter l'utilisation du cache à cette étape et ses dépendances.
Exemple avec --cache-from :
# Tirer l'image précédente comme source de cache
docker pull myregistry/myapp:latest || true
# Construire en utilisant l'image du registre comme cache
docker build \
--cache-from myregistry/myapp:latest \
-t myregistry/myapp:latest .
# Pousser pour la prochaine fois
docker push myregistry/myapp:latest
Ce modèle est largement utilisé en CI. Remarque : avec BuildKit, --cache-from ne fonctionne que si le builder le supporte (le driver docker par défaut ne supporte pas l'export de cache ; vous avez besoin de --output type=registry ou du driver docker-container avec export de cache).
Montages de cache pour les gestionnaires de paquets :
Pour les builds de développement, utilisez des montages de cache pour partager les caches des gestionnaires de paquets entre les builds :
# syntax=docker/dockerfile:1.4
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN --mount=type=cache,target=/root/.npm \
npm install
COPY . .
--mount=type=cache stocke /root/.npm entre les builds, accélérant la résolution des dépendances même lorsque package.json change. C'est une fonctionnalité BuildKit ; le builder classique renverra une erreur ou l'ignorera.
Test de redémarrage pour la configuration :
Après avoir modifié un Dockerfile, faites toujours un build propre sans cache pour vous assurer que l'image fonctionne toujours :
docker build --no-cache -t myapp:test .
docker run --rm -p 3000:3000 myapp:test
Si l'application démarre et répond, la configuration est saine. Ensuite, exécutez un build avec cache pour confirmer que le cache fonctionne toujours après le build propre.
Vérification et diagnostics
Diagnostiquer les absences de cache nécessite de savoir ce qui a changé entre les builds. Comme Docker utilise un stockage adressable par contenu, un succès de cache de couche signifie que le même contenu d'entrée et les mêmes instructions ont été utilisés exactement.
Inspecter l'historique de l'image pour voir les couches :
docker history myapp:test
Sortie :
IMAGE CREATED CREATED BY SIZE COMMENT
abc123def456 2 minutes ago CMD ["npm", "start"] 0B buildkit.dockerfile.v0
<missing> 2 minutes ago COPY . . # buildkit 1.2MB buildkit.dockerfile.v0
<missing> 2 minutes ago RUN /bin/sh -c npm install # buildkit 150MB buildkit.dockerfile.v0
<missing> 2 minutes ago COPY package*.json ./ # buildkit 100kB buildkit.dockerfile.v0
<missing> 2 minutes ago WORKDIR /app 0B buildkit.dockerfile.v0
<missing> 2 minutes ago FROM node:18-alpine 150MB buildkit.dockerfile.v0
Chaque ligne est une couche. Si vous modifiez un fichier dans le répertoire source, la couche COPY . . changera, et toutes les couches au-dessus seront invalidées.
Utiliser la progression BuildKit pour voir les décisions de cache :
docker build --progress=plain -t myapp:test . 2>&1 | tee build.log
La sortie de progression simple montre chaque instruction et si elle a été mise en cache. Cherchez CACHED ou DONE vs RUNNING :
#7 [4/5] COPY . .
#7 CACHED
Trouver quels fichiers ont affecté le cache :
Pour une instruction COPY, comparez les empreintes de fichiers entre les builds. Vous pouvez utiliser find avec sha256sum :
find . -type f -not -path './node_modules/*' -exec sha256sum {} + | sort
Exécutez ceci avant et après un changement pour voir quels fichiers diffèrent. Toute différence dans le contexte copié change l'empreinte de la couche.
Diagnostiquer les échecs de --cache-from :
Si vous utilisez --cache-from avec une image de registre et que le build manque toujours le cache, vérifiez :
- L'image tirée existe localement :
docker image inspect myregistry/myapp:latest - L'image a été construite avec BuildKit et a des métadonnées de cache :
docker buildx imagetools inspect myregistry/myapp:latest - Le builder supporte l'import de cache : le driver docker par défaut ne le fait pas ; utilisez le driver
docker-container.
Exemple avec Buildx et cache de registre :
# Créer un builder qui peut exporter le cache
docker buildx create --use --name mybuilder --driver docker-container
# Construire avec export de cache vers le registre
docker buildx build \
--cache-from type=registry,ref=myregistry/myapp:cache \
--cache-to type=registry,ref=myregistry/myapp:cache,mode=max \
-t myregistry/myapp:latest \
--push .
Cela exporte le cache vers une balise d'image séparée ou la même image selon la configuration. Le mode=max exporte toutes les couches intermédiaires, pas seulement les couches de l'image finale.
Vérifier l'utilisation du cache disque et nettoyer en toute sécurité :
# Afficher les détails du cache de build
docker buildx du
# Nettoyer le cache de build plus vieux que 24 heures
docker buildx prune --filter "until=24h"
# Nettoyer tout le cache de build inutilisé
docker builder prune
Ces commandes libèrent de l'espace mais peuvent supprimer des caches que vous vouliez conserver. Utilisez toujours --filter pour limiter la fenêtre.
Modes de défaillance et récupération
Même avec un bon Dockerfile, la mise en cache peut échouer silencieusement ou causer des erreurs de build. Voici les modes de défaillance courants et comment récupérer.
1. Invalidation du cache due aux changements de contexte
Symptôme : Chaque build réexécute RUN npm install même si package.json n'a pas changé.
Pourquoi : L'instruction COPY qui copie tout le contexte (COPY . .) inclut des fichiers qui ont changé, comme les journaux, les fichiers d'environnement locaux ou les artefacts générés.
Diagnostic : Vérifiez la sortie du build : COPY . . n'est pas CACHED, ce qui signifie que l'empreinte du contexte a changé. Utilisez .dockerignore pour exclure les fichiers volatils.
Récupération :
# Créer .dockerignore
cat > .dockerignore << EOF
node_modules
*.log
.env
.git
EOF
Puis reconstruisez. L'empreinte du contexte se stabilise, et la couche reste en cache.
2. Les montages de cache BuildKit ne fonctionnent pas
Symptôme : RUN --mount=type=cache provoque une erreur de build ou n'accélère pas les builds.
Pourquoi : Le Dockerfile peut manquer la directive de syntaxe pour activer les fonctionnalités BuildKit, ou le builder est le classique.
Récupération :
- Ajoutez
# syntax=docker/dockerfile:1.4en haut du Dockerfile. - Assurez-vous que BuildKit est activé :
DOCKER_BUILDKIT=1 docker build ...ou Docker 23+. - Si vous utilisez Buildx, vérifiez le driver du builder :
docker buildx lsdevrait montrerdocker-containeroudefaultavec le support BuildKit.
3. --cache-from ne restaure pas le cache en CI
Symptôme : Les builds CI partent de zéro à chaque fois malgré le tirage de l'image précédente.
Pourquoi : L'image précédente peut ne pas contenir de métadonnées de cache, ou le démon Docker du runner CI n'a pas BuildKit activé.
Récupération :
- En CI, activez BuildKit et Buildx.
- Utilisez
docker/build-push-actionaveccache-from: type=registry,ref=...etcache-to: type=registry,ref=...,mode=max. - Assurez-vous que l'image est poussée avec les métadonnées de cache : avec le builder classique,
--cache-fromne fonctionne que si l'image a été construite normalement et que toutes les couches sont présentes.
4. Le cache de couches croît sans limite
Symptôme : L'utilisation du disque augmente après de nombreux builds ; docker system df montre un grand cache de build.
Pourquoi : Chaque contexte ou instruction unique crée de nouvelles couches ; les anciennes restent jusqu'à ce qu'elles soient nettoyées.
Récupération :
# Nettoyer le cache de build non utilisé depuis 7 jours
docker buildx prune --filter "until=168h"
# Ou supprimer tout le cache de build
docker builder prune -a
Planifiez ceci dans les fenêtres de maintenance ou les tâches de nettoyage CI.
5. Confusion entre les couches d'image et le cache de build
Symptôme : docker images montre des images avec des couches manquantes, mais le cache de build montre de nombreuses couches.
Pourquoi : Le cache de build inclut des couches intermédiaires non référencées par aucune image. Elles sont toujours utiles pour les builds futurs.
Récupération : Aucune action nécessaire. Utilisez docker buildx du pour voir la répartition du cache et nettoyer sélectivement.
6. Builds multi-étapes et fuites de cache
Symptôme : Des secrets ou de gros fichiers apparaissent dans l'image finale malgré le build multi-étapes.
Pourquoi : Une étape qui copie des secrets peut être mise en cache et réutilisée, mais si l'étape finale copie incorrectement depuis cette étape, les secrets peuvent fuiter. De plus, utiliser COPY --from=0 sans limiter peut apporter des fichiers non désirés.
Récupération :
- Nommez explicitement les étapes :
FROM node:18 AS build - Copiez uniquement les artefacts nécessaires :
COPY --from=build /app/dist /app - Utilisez les secrets BuildKit :
RUN --mount=type=secret,id=mysecret ...pour éviter d'intégrer des secrets dans les couches.
Liste de contrôle opérationnelle
Cette liste de contrôle est destinée à l'opérateur qui possède le pipeline de build. Chaque élément a un propriétaire et une fréquence de révision.
| # | Tâche | Commande / Vérification | Attendu / Fait | Propriétaire | Révision |
|---|---|---|---|---|---|
| 1 | Vérifier les versions de Docker et BuildKit | docker version, docker buildx version | Docker 23+, Buildx installé | Chef de développement | Mensuelle |
| 2 | Valider l'ordre du Dockerfile | Révision manuelle ou lint avec hadolint | Instructions du moins au plus changeant | Ingénieur build | Par PR |
| 3 | Confirmer que .dockerignore existe et exclut les fichiers volatils | ls -la .dockerignore, réviser le contenu | Exclut node_modules, .git, journaux | Ingénieur build | Par PR |
| 4 | Exécuter un build de validation avec suivi du cache | docker build --progress=plain | Voir CACHED pour les couches attendues | Pipeline CI | Chaque build |
| 5 | Tester le build --no-cache | docker build --no-cache | Le build réussit sans erreurs | Pipeline CI | Chaque nuit |
| 6 | Tester la restauration du cache depuis le registre | docker buildx build --cache-from type=registry,... | Réutilisation des couches depuis le registre | Pipeline CI | Hebdomadaire |
| 7 | Surveiller l'utilisation du cache disque | docker system df, docker buildx du | Taille du cache dans les limites | Ingénieur opérations | Hebdomadaire |
| 8 | Nettoyer le vieux cache de build | docker buildx prune --filter "until=168h" | Pas de cache plus vieux que 7 jours | Ingénieur opérations | Hebdomadaire |
| 9 | Documenter la stratégie de cache et les étapes de récupération | Wiki ou runbook | Runbook à jour | Chef de développement | Trimestrielle |
Propriété et fréquence :
- Ingénieur build (ou spécialiste DevOps) possède le Dockerfile et
.dockerignorepar pull request. Il approuve les changements qui affectent l'ordre des couches ou le contexte. - Pipeline CI (automatisé) possède les builds nocturnes sans cache et les tests hebdomadaires de restauration du cache. Si le pipeline échoue, l'ingénieur de garde enquête.
- Ingénieur opérations possède l'utilisation du disque et le nettoyage, révisés hebdomadairement. Si le cache croît de manière inattendue, il ajuste la politique de nettoyage.
- Chef de développement révise la stratégie globale de mise en cache mensuellement et met à jour la documentation trimestriellement ou après des changements majeurs.
Vérification de récupération pour les éléments de la liste de contrôle :
Après tout changement qui pourrait affecter la mise en cache, exécutez :
# Construire deux fois : la première remplit le cache, la seconde devrait montrer CACHED
docker build -t myapp:check .
docker build -t myapp:check . | grep CACHED
Si grep ne trouve aucun CACHED, enquêtez avant de fusionner.
Pièges courants et comment les éviter
De nombreux praticiens ont des difficultés avec la mise en cache Docker à cause d'erreurs subtiles. Voici les pièges, pourquoi ils se produisent et comment les éviter ou récupérer.
Piège 1 : Copier tout le contexte trop tôt
Erreur : COPY . . avant RUN npm install ou RUN pip install.
Pourquoi cela arrive : Cela semble naturel de tout copier en une fois.
Conséquence : Tout changement de fichier dans le projet invalide la couche d'installation des dépendances, causant une réinstallation complète à chaque build.
Évitement : Séparez les fichiers de dépendances et le code source :
COPY package*.json ./
RUN npm install
COPY . .
Piège 2 : Ne pas utiliser .dockerignore
Erreur : Le contexte de build inclut des fichiers volumineux ou changeants comme node_modules, .git, les journaux ou .env.
Pourquoi cela arrive : Les développeurs oublient que tout le contexte est envoyé au démon Docker et haché pour le cache.
Conséquence : Le contexte de build devient énorme, les absences de cache sont fréquentes et des secrets peuvent être exposés si .env est copié.
Évitement : Ayez toujours un .dockerignore avec au moins :
.git
node_modules
*.log
.env
Testez son effet avec docker build --progress=plain et observez la taille du contexte (l'étape #1 [internal] load build context montre la taille transférée).
Piège 3 : Mal comprendre --cache-from
Erreur : Supposer que --cache-from fonctionne de la même manière avec tous les builders et que n'importe quelle image peut servir de cache.
Pourquoi cela arrive : Le builder classique et BuildKit gèrent --cache-from différemment. Une image construite sans métadonnées de cache ne peut pas être utilisée comme source de cache.
Conséquence : Les builds CI manquent toujours le cache, menant à des builds plus longs et des ressources gaspillées.
Évitement : Utilisez BuildKit et Buildx avec export de cache explicite :
docker buildx build \
--cache-from type=registry,ref=myregistry/myapp:cache \
--cache-to type=registry,ref=myregistry/myapp:cache,mode=max \
-t myregistry/myapp:latest \
--push .
Piège 4 : Se fier à docker builder prune sans filtres
Erreur : Exécuter docker builder prune -a manuellement et supprimer des caches encore nécessaires pour un travail en cours.
Pourquoi cela arrive : Cela semble sûr, mais des builds en cours ou planifiés bientôt peuvent avoir besoin de ces caches.
Conséquence : Les prochains builds repartent de zéro, ralentissant le développement.
Évitement : Utilisez des filtres basés sur le temps et planifiez le nettoyage pendant les heures creuses :
docker buildx prune --filter "until=168h" --keep-storage 10GB
Piège 5 : Oublier les arguments de build dans la clé de cache
Erreur : Changer un argument de build pendant le build mais s'attendre à ce que le cache fonctionne.
Pourquoi cela arrive : Les développeurs pensent que seuls les changements de fichiers comptent.
Conséquence : Les couches après l'utilisation de ARG sont invalidées, causant des rebuilds.
Évitement : Traitez les valeurs ARG comme faisant partie de la clé de cache. Si un argument change fréquemment (comme les balises de version), placez-le le plus tard possible dans le Dockerfile ou utilisez des builds multi-étapes pour l'isoler.
Piège 6 : Ne pas tester le comportement du cache en CI
Erreur : Tester seulement les builds localement, supposant que la CI mettra en cache de manière similaire.
Pourquoi cela arrive : Les builds locaux ont un cache persistant ; les runners CI peuvent être éphémères.
Conséquence : Les builds CI sont lents, menant à des boucles de rétroaction plus longues.
Évitement : Incluez des tests de restauration du cache en CI, utilisez le cache de registre et surveillez les temps de build.
Conclusion
La mise en cache des couches Docker n'est pas de la magie : c'est un système prévisible qui récompense une conception délibérée du Dockerfile et une observation diligente. En vérifiant les versions, en ordonnant correctement les instructions, en utilisant .dockerignore et en vérifiant avec CACHED dans la sortie du build, vous pouvez réduire considérablement les temps de build.
Les commandes et exemples de ce guide vous donnent une boîte à outils pratique :
docker buildx dupour inspecter l'utilisation du cache.docker build --progress=plainpour voir les succès de cache.docker buildx build --cache-fromavec export vers registre pour CI.--mount=type=cachepour les caches des gestionnaires de paquets.docker buildx prune --filterpour un nettoyage contrôlé.
Commencez par une vérification à faible risque : exécutez un build deux fois sur un petit projet et confirmez que le deuxième build montre CACHED pour l'installation des dépendances. Ensuite, ajoutez un .dockerignore et divisez vos instructions COPY. Documentez ce que vous avez changé et comment cela a affecté le temps de build. À mesure que vous gagnez en confiance, introduisez le cache de registre en CI et surveillez l'utilisation du disque avec un nettoyage hebdomadaire.
Une stratégie de mise en cache fiable rend les échecs visibles, protège les valeurs sensibles, limite les changements aux ressources prévues et définit la récupération avant qu'un incident ne la force. Avec ces pratiques, vos builds Docker seront plus rapides, plus prévisibles et plus faciles à déboguer.