Dépannage du cache de build Docker pour des pipelines CI plus rapides : guide d'implémentation pratique

Introduction

Les builds Docker lents grèvent les budgets CI et masquent les vrais échecs derrière de longues files d'attente. Le gain le plus rapide vient de la compréhension de la manière dont Docker décide de réutiliser le travail, puis de l'organisation de votre Dockerfile et de votre CI pour toucher le cache de façon prévisible. Ce guide montre comment :

• Diagnostiquer les manques de cache et lire les logs de build
• Ordonner les couches pour la réutilisation
• Utiliser les montages de cache BuildKit pour les caches d'outils spécifiques à chaque langage
• Verrouiller l'installation des dépendances avec des lockfiles
• Persister le cache entre les exécuteurs CI avec docker buildx
• Tester les changements localement avec Docker Compose et déployer en toute sécurité

Vue d'ensemble du flux de travail

Utilisez cette séquence de bout en bout pour garder les changements sûrs et mesurables :

Chronométrez un build propre et un rebuild sans changement. Enregistrez la sortie couche par couche pour la comparaison.

1. Reference

Activez BuildKit localement et dans la CI. Passez aux logs de progression simples pour la visibilité.

1. Activer BuildKit

Réorganisez les instructions pour que les couches stables viennent en premier. Ajoutez un .dockerignore strict pour éviter les invalidations bruyantes.

1. Corriger l'ordre des couches et le contexte

Utilisez RUN --mount=type=cache pour persister les caches d'outils (pip, npm, modules Go, apt).

1. Ajouter des montages de cache pour les dépendances

Utilisez docker buildx avec --cache-to et --cache-from ciblant un registre.

1. Persister le cache entre les exécutions CI

Parcourez une liste de contrôle pour attraper les manques courants.

1. Dépanner les restes

Validez la performance et la correction sur un service d'abord.

1. Piloter localement, puis déployer

Comment fonctionne le cache de build Docker

Chaque instruction du Dockerfile crée une couche. Docker peut réutiliser une couche mise en cache si :

• Le texte de l'instruction est identique
• Les arguments de build et l'environnement qui affectent cette instruction sont identiques
• Tous les fichiers que l'instruction lit depuis le contexte de build sont inchangés

Implications clés :

• COPY/ADD sont sensibles au cache : changer un fichier référencé invalide cette couche et toutes les couches suivantes.
• L'ordre des instructions compte : quand une couche manque, toutes les couches suivantes doivent être reconstruites.
• Un .dockerignore serré réduit les manques de cache accidentels en excluant les logs, builds locaux, venvs, node_modules, couverture, tmp et autres bruits.

Exemple de .dockerignore :

.git
**/__pycache__/
**/*.pyc
node_modules/
.env
build/
dist/
.coverage
coverage/
tmp/
.DS_Store

Ordonner les couches pour une réutilisation maximale

Arrangez votre Dockerfile pour que le travail stable se fasse avant le travail volatile :

• Stable : image de base, paquets OS, runtimes de langage
• Semi-stable : installation des dépendances clé sur les lockfiles
• Volatile : code source de l'application

Schéma général :

# syntax=docker/dockerfile:1.7
FROM python:3.11-slim AS app

# 1) Dépendances système d'abord
RUN apt-get update \
 && apt-get install -y --no-install-recommends build-essential \
 && rm -rf /var/lib/apt/lists/*

# 2) Copier uniquement les lockfiles, puis installer les dépendances
WORKDIR /app
COPY requirements.txt ./
# Installation des dépendances ici (voir montage de cache ci-dessous)

# 3) Copier le reste seulement après l'installation des dépendances
COPY . .

# 4) Commande finale
CMD ["python", "-m", "my_service" ]

Pourquoi cela aide : modifier un fichier source ne force pas la réinstallation des dépendances car la couche de dépendances ne dépend que de requirements.txt.

Évitez les pièges courants :

• Ne placez pas d'ARG ou ENV changeants fréquemment avant les couches lourdes.
• Ne faites pas COPY de tout le dépôt avant d'installer les dépendances clés par les lockfiles.
• Gardez les commandes RUN déterministes (versions épinglées, listes de paquets triées).

Montages de cache BuildKit qui aident

BuildKit peut persister les caches pour les outils sans les cuire dans l'image finale. Activez-le et utilisez --mount=type=cache.

Activer BuildKit et les logs simples :

export DOCKER_BUILDKIT=1
export BUILDKIT_PROGRESS=plain

Exemple Python avec cache de wheels pip

# syntax=docker/dockerfile:1.7
FROM python:3.11-slim AS app
WORKDIR /app

RUN --mount=type=cache,target=/root/.cache/pip \
 pip install --upgrade pip

COPY requirements.txt ./
RUN --mount=type=cache,target=/root/.cache/pip \
 pip install -r requirements.txt

COPY . .
CMD ["python", "-m", "my_service" ]

Exemple Node.js avec cache npm

# syntax=docker/dockerfile:1.7
FROM node:20-alpine AS app
WORKDIR /app

COPY package*.json ./
RUN --mount=type=cache,target=/root/.npm \
 npm ci --prefer-offline --no-audit --no-fund

COPY . .
CMD ["node", "server.js" ]

Exemple Go avec cache de modules

# syntax=docker/dockerfile:1.7
FROM golang:1.22-alpine AS builder
WORKDIR /src

COPY go.mod go.sum ./
RUN --mount=type=cache,target=/go/pkg/mod \
 go mod download

COPY . .
RUN --mount=type=cache,target=/go/pkg/mod \
 CGO_ENABLED=0 go build -o /out/app ./cmd/app

FROM gcr.io/distroless/base
COPY --from=builder /out/app /app
ENTRYPOINT [
/app
]

Exemple de cache apt

# syntax=docker/dockerfile:1.7
FROM debian:stable-slim
RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
 --mount=type=cache,target=/var/lib/apt,sharing=locked \
 apt-get update && apt-get install -y --no-install-recommends curl && rm -rf /var/lib/apt/lists/*

Notes :

• Le montage de cache persiste entre les builds sur la même machine. Pour persister entre les machines CI, exportez/importez le cache via buildx (section suivante).
• Alignez les cibles de cache avec les défauts de vos outils (pip : /root/.cache/pip, npm : /root/.npm, Go : /go/pkg/mod).

Patterns d'installation des dépendances

Suivez ces règles pour une réutilisation fiable :

• Utilisez toujours des lockfiles (requirements.txt, poetry.lock, Pipfile.lock, package-lock.json, yarn.lock, go.sum). Épinglez les versions.
• COPY uniquement les lockfiles d'abord, puis installez les dépendances. COPY le reste du code source après.
• Utilisez des commandes propres et favorables au cache : npm ci pour Node.js ; pip avec cache de wheels ; go mod download avant le build.
• Évitez le travail réseau dans les couches ultérieures. Placez les téléchargements dans des couches précoces et mises en cache.
• Pour les builds multi-étapes, gardez les dépendances de build uniquement dans l'étape builder et copiez seulement les artefacts vers l'étape finale.

Exemple multi-étapes pour un front React derrière une API Python :

# syntax=docker/dockerfile:1.7
FROM node:20-alpine AS ui
WORKDIR /ui
COPY ui/package*.json ./
RUN --mount=type=cache,target=/root/.npm npm ci --prefer-offline
COPY ui/. .
RUN npm run build

FROM python:3.11-slim AS api
WORKDIR /app
COPY requirements.txt ./
RUN --mount=type=cache,target=/root/.cache/pip pip install -r requirements.txt
COPY . .
COPY --from=ui /ui/build ./static
CMD ["python", "-m", "api" ]

Accélérations CI avec cache de registre

Utilisez docker buildx pour persister le cache entre les exécutions CI.

Initialisez buildx localement (les exécuteurs CI le font souvent pour vous) :

docker buildx create --use --name ci-builder || docker buildx use ci-builder
docker buildx inspect --bootstrap

Build avec export de cache vers un registre :

# Build et push de l'image et du cache
IMAGE=registry.example.com/my/app:$(git rev-parse --short HEAD)
CACHE_REF=registry.example.com/my/app:buildcache

docker buildx build \
 --progress=plain \
 --push \
 --tag "$IMAGE" \
 --cache-to type=registry,ref=$CACHE_REF,mode=max \
 --cache-from type=registry,ref=$CACHE_REF \
 -f Dockerfile .

Notes :

• mode=max stocke plus de métadonnées pour une meilleure réutilisation entre les changements.
• Gardez CACHE_REF stable entre les exécutions pour le même repo/service.
• Récupérez cache-from avant de builder pour que les exécuteurs distants en bénéficient immédiatement.

Docker Compose pour les tests locaux (cibles d'étape de build) :

services:
 app:
 build:
 context: .
 dockerfile: Dockerfile
 target: app
 environment:
 - PYTHONUNBUFFERED=1
 ports:
 - "8080:8080"
 command: ["python", "-m", "my_service" ]

Liste de contrôle de dépannage

Parcourez cette liste quand une étape n'est pas mise en cache :

1. Activez les logs simples

export DOCKER_BUILDKIT=1
export BUILDKIT_PROGRESS=plain

Vérifiez quelles étapes disent CACHED et lesquelles se réexécutent.

1. Vérifiez la taille et le bruit du contexte

• Lancez : docker buildx build . --progress=plain 2>&1 | head -n 50
• Assurez-vous que .dockerignore exclut : node_modules, venv, artefacts de build, logs, tmp, .git (sauf si vous en avez besoin).

1. Vérifiez l'ordre des COPY

• COPY les lockfiles d'abord ; lancez les installations ; COPY la source en dernier.
• Si vous COPY . avant d'installer les dépendances, chaque changement de code casse le cache de la couche de dépendances.

1. Stabilisez ARG/ENV

• Les arguments de build qui changent par commit doivent être placés après les couches lourdes.
• Évitez les étapes RUN non déterministes (timestamps, graines aléatoires, curl | sh sans épingler les versions).

1. Alignez les montages de cache

• Confirmez que votre outil utilise le chemin que vous avez monté. Pour pip, vérifiez /root/.cache/pip après un build. Pour npm, /root/.npm.

1. Vérifiez la dérive de l'image de base

• Si le digest FROM change fréquemment, les couches de dépendances peuvent être invalidées. Envisagez d'épingler sur un digest (ex: python:3.11-slim@sha256:...).

1. Multi-étapes et cache-from

• Si vous utilisez le multi-étapes, assurez-vous que cache-from pointe vers la bonne image ou le bon nom d'étape que vous avez poussé précédemment.

1. Reproduisez sur une machine propre

• Récupérez cache-from, puis buildez. Si ça manque encore, les entrées de la clé de cache changent entre les exécutions.

Plan de pilote local

Choisissez un service aux builds lents et lancez cette expérience étroite et mesurable :

Objectif : Réduire le temps de rebuild répété de 40%+ sans changer le comportement à l'exécution.

Périmètre : Uniquement le cache d'installation des dépendances pour un service (par exemple, wheels pip ou cache npm) et le réordonnancement des couches du Dockerfile autour des lockfiles.

Étapes :

Chronométrez deux builds dos à dos :

1. Reference

time docker build -t pilot:baseline .
time docker build -t pilot:rebuild .

Enregistrez le deuxième temps ; c'est la référence de cache hit.

1. Activez BuildKit et réordonnez les couches

• Ajoutez # syntax=docker/dockerfile:1.7
• Exportez DOCKER_BUILDKIT=1 et BUILDKIT_PROGRESS=plain
• COPY les lockfiles d'abord ; installez les dépendances ; puis COPY la source.

1. Ajoutez les montages de cache

• Pour pip : --mount=type=cache,target=/root/.cache/pip
• Pour npm : --mount=type=cache,target=/root/.npm

1. Rebuildez et mesurez à nouveau

time docker build -t pilot:optimized .
time docker build -t pilot:optimized2 .

Attendez-vous à ce que le deuxième build optimisé soit beaucoup plus rapide.

1. Vérification fonctionnelle avec Docker Compose

docker compose up --build
# Visitez le service ou lancez une commande de smoke test rapide

Optionnel : testez le cache distant Poussez --cache-to et rebâtissez sur un exécuteur frais avec --cache-from.

Critères de sortie :

• Le temps de rebuild répété réduit de 40%+
• Le service démarre et passe un smoke test basique

Si le pilote atteint les objectifs, appliquez le pattern aux autres services.

Conclusion

Vous pouvez réduire les temps de build CI en combinant quatre pratiques : le bon ordonnancement des couches, les montages de cache BuildKit pour les dépendances, un .dockerignore strict et un cache de registre pour la réutilisation entre exécuteurs. Commencez par un petit pilote local, mesurez les gains et déployez le pattern service par service.