## Introduction

Le cache de couches peut transformer un build Docker de 12 minutes en une reconstruction de 90 secondes, mais seulement si le cache dispose de suffisamment d'espace, du bon pilote de stockage et d'une configuration BuildKit qui survit au recyclage des runners CI. La planification de capacité du cache de couches Docker consiste à répondre à quelques questions concrètes avant que le premier échec de cache ne force un nettoyage d'urgence :

- Combien d'espace disque le cache consommera-t-il de manière réaliste pour l'historique d'images de ce projet ?
- Quel backend de cache utiliser : un répertoire local, un volume géré par Docker ou un cache de registre distant ?
- Quel signal indique que le cache fonctionne, et quels modes de défaillance produisent silencieusement des reconstructions complètes ?
- Quel est le plus petit changement sûr lorsque le cache dépasse son allocation actuelle ?

Ce guide s'adresse aux développeurs, consultants DevOps et équipes techniques de startups qui exploitent leur propre infrastructure de build. Il relie le dimensionnement du cache, la mise à l'échelle, les limites de ressources et la surveillance à des commandes spécifiques, des résultats attendus et des décisions de récupération. Le principe sous-jacent est la sécurité opérationnelle : observer avant de changer, limiter le rayon d'impact, utiliser des espaces réservés au lieu de secrets, vérifier le résultat et documenter la récupération si l'état attendu n'est pas atteint.

Tout au long de l'article, les exemples supposent Docker Engine 24.0 ou version ultérieure avec BuildKit activé par défaut. Sur Docker Desktop, BuildKit est activé par défaut. Sur Linux, vous pouvez le confirmer avec `docker buildx version` ; si vous voyez une sortie `buildx` plutôt qu'une erreur, BuildKit est disponible. Les commandes sont copiables, mais remplacez les chemins, noms d'images et seuils par les valeurs de votre propre environnement.

## Inventaire des versions et de l'environnement

Avant de régler quoi que ce soit, sachez exactement ce qui tourne et où se trouve le cache. Inventoriez la version de Docker, les plugins buildx, l'utilisation du disque et la configuration du builder. Cette étape est en lecture seule et doit produire des horodatages et des chiffres de référence que vous pourrez comparer après tout changement.

Exécutez les commandes suivantes et enregistrez la sortie :

```bash
# Versions Docker et buildx
docker version --format '{{.Client.Version}} {{.Server.Version}}'
docker buildx version

# Résumé de l'utilisation du disque pour Docker
docker system df

# Détails du builder, y compris l'emplacement du cache et le pilote
docker buildx ls
```

Une sortie typique de `docker system df` ressemble à ceci :

```
TYPE            TOTAL     ACTIVE    SIZE      RECLAIMABLE
Images          12        3         4.213GB   2.111GB (50%)
Containers      8         2         1.02MB    0B (0%)
Local Volumes   5         1         1.89GB    1.34GB (71%)
Build Cache     25        0         15.75GB   15.75GB (100%)
```

La ligne `Build Cache` est celle à surveiller pour la planification de capacité du cache de couches. Si ce nombre est proche de votre limite de disque ou s'il croît sans limite, vous avez un problème de dimensionnement. Notez également la sortie de `docker buildx ls` : le builder par défaut peut avoir un pilote `docker-container` avec un volume de cache dédié, ou il peut retomber sur le pilote docker qui stocke le cache dans `var/lib/docker` de l'hôte. Une surprise courante est qu'un runner CI crée un nouveau builder avec un cache vide à chaque exécution de pipeline, de sorte que le cache de couches n'a jamais l'occasion d'aider.

### Où se trouve réellement le cache

Pour un pilote docker standard, le cache de couches est stocké sous `/var/lib/docker/overlay2` (ou le chemin équivalent pour votre pilote de stockage). Pour un builder `docker-container`, le cache peut résider dans le système de fichiers du conteneur du builder, souvent dans un volume tel que `buildx_buildkit_builder0_state`. Pour voir le montage exact, inspectez le conteneur du builder :

```bash
docker buildx inspect --bootstrap
```

La sortie inclut le nom du builder, le pilote et la plateforme du nœud. Si vous voyez `Driver: docker-container` et `Platforms: linux/amd64, linux/arm64`, le builder est distant et son cache n'est pas directement sur le système de fichiers hôte à moins qu'un montage de cache ne soit configuré.

Pour une vérification simple sur l'hôte, regardez l'utilisation du disque des répertoires overlay :

```bash
sudo du -sh /var/lib/docker/overlay2/* 2>/dev/null | sort -h | tail -5
```

Cela montre quelles couches consomment le plus d'espace. Des couches extrêmement volumineuses proviennent souvent de l'inclusion accidentelle d'artefacts de build, de dépendances vendues ou de caches d'étapes antérieures qui n'ont pas été nettoyés.

### Test local de type production pour la persistance du cache

Un test petit mais critique est de savoir si le cache survit à un redémarrage du builder. Créez un Dockerfile trivial et construisez deux fois avec un horodatage pour vérifier que le second build est rapide :

```bash
# Dockerfile
FROM alpine:3.18
RUN echo "build $(date +%s)" > /tmp/build-time

# Premier build
docker build -t cache-test:first .

# Second build immédiatement après
docker build -t cache-test:second .
```

Dans le second build, BuildKit devrait montrer `[2/2] RUN echo "build ...` comme `CACHED`. Si vous voyez l'étape `RUN` s'exécuter à nouveau, le cache ne persiste pas entre les builds. Le correctif dépend du pilote : pour les builders docker-container, assurez-vous que le builder n'est pas recréé à chaque fois (utilisez `docker buildx create --name mybuilder --use` une fois, et réutilisez ce builder). Pour les runners CI, assurez-vous que le volume de cache du builder n'est pas effacé entre les jobs.

## Dimensionner le cache avec des chiffres pratiques

La planification de capacité commence par mesurer la quantité de cache qu'un build typique produit et la fréquence à laquelle vous construisez. Pour un service Node.js de taille moyenne, le cache de couches après dix builds pourrait ressembler à ceci :

| Composant du build | Taille typique | Reconstruit à chaque fois ? | Utilité du cache |
|---|---|---|---|
| Image de base (node:20-alpine) | 180 Mo | Non, réutilisée | Élevée |
| Couche des dépendances npm | 350 Mo | Seulement quand package.json change | Très élevée |
| Copie du code source | 50 Mo | Oui, sauf si l'outillage utilise un cache de montage | Faible en tant que couche, élevée en tant que montage |
| Artefacts de test | 200 Mo | Oui, mais ne devraient pas être mis en cache | Aucune, crée du désordre |
| Sortie de build (dist) | 120 Mo | Oui, mais peut être mise en cache avec le mode max | Moyenne |

Si une équipe exécute 20 builds par jour sur un seul builder, un cache naïf qui garde tout croîtrait d'environ 20 x (350 Mo + 50 Mo + 200 Mo + 120 Mo) = 14,4 Go par jour. La plupart de cela est inutile car le code source et les artefacts de test changent à chaque build alors que la couche de dépendances ne change qu'occasionnellement. Un cache bien configuré élague agressivement ou utilise un cache de registre distant pour stocker uniquement les couches significatives.

Un budget de cache réaliste pour cette équipe pourrait être de 5 à 10 Go sur disque, avec une politique de rétention basée sur l'âge plutôt que la taille. Utilisez `docker buildx prune` avec un filtre pour ne garder que les entrées de cache consultées au cours des 7 derniers jours :

```bash
docker buildx prune --filter "until=168h" --force
```

C'est un point de départ sûr car cela supprime uniquement les données de cache, pas les images ni les conteneurs. Surveillez l'espace récupéré avec `docker system df` avant et après. Si les builds ralentissent soudainement parce que des dépendances communes sont élaguées, augmentez la fenêtre de rétention à 14 jours et ajustez l'allocation de stockage en conséquence.

### Calculer le budget de cache à partir de l'historique des images

Pour un plan précis, inspectez les tailles réelles des couches d'une image représentative :

```bash
docker history --no-trunc your-image:latest
```

Cela liste chaque couche avec sa taille et la commande qui l'a créée. Identifiez les couches qui changent le moins fréquemment. Ce sont celles qui valent la peine d'être mises en cache. Pour une application Python, la couche d'installation des dépendances (`RUN pip install -r requirements.txt`) est la candidate idéale. Si cette couche fait 800 Mo, vous voulez suffisamment d'espace de cache pour garder au moins une copie par version Python en utilisation active. Réservez 2 copies par branche active ou pipeline de PR, plus une marge pour les mises à jour de l'image de base. La formule est :

```
Cache en Go = (somme des tailles des couches à haute valeur en Go) x (nombre de branches concurrentes) x (facteur de sécurité de 1,5)
```

Comme exemple concret, un monorepo Python avec une couche de dépendances de 800 Mo, une image de base de 500 Mo et 5 branches de fonctionnalités actives aurait besoin d'environ (0,8 + 0,5) x 5 x 1,5 = 9,75 Go d'espace de cache juste pour ces couches. En ajoutant le cache de build éphémère des étapes non montées, cela pourrait atteindre 15 Go. Comparez cela à l'espace disque disponible sur l'hôte du builder.

## Chemin de configuration sûr

Modifier les paramètres de cache est une intervention. Suivez un processus délimité : enregistrez l'état actuel, sauvegardez tout cache qui pourrait être irremplaçable (pour les caches distants, notez l'URL du registre et les identifiants), faites un seul changement et vérifiez le résultat avant de continuer. Pour un builder local, commencez par la configuration du builder plutôt que par les paramètres globaux du démon Docker.

### Utiliser un builder dédié avec des paramètres de cache explicites

Créez un builder nommé avec un pilote docker-container et un répertoire de cache explicite ou une configuration cache-to/cache-from :

```bash
docker buildx create \
  --name mybuilder \
  --driver docker-container \
  --driver-opt env.BUILDKIT_STEP_LOG_MAX_SIZE=10485760 \
  --driver-opt env.BUILDKIT_STEP_LOG_MAX_SPEED=1048576 \
  --use

docker buildx inspect --bootstrap
```

Cela définit des limites de journalisation qui empêchent une croissance illimitée dans le conteneur du builder. Le cache lui-même est stocké dans le volume du builder. Vous pouvez également monter un répertoire hôte dédié pour le cache si vous voulez une sauvegarde plus facile :

```bash
docker buildx create \
  --name mybuilder \
  --driver docker-container \
  --driver-opt env.BUILDKIT_STEP_LOG_MAX_SIZE=10485760 \
  --driver-opt env.BUILDKIT_STEP_LOG_MAX_SPEED=1048576 \
  --config /etc/buildkit/buildkitd.toml \
  --use
```

Avec un `buildkitd.toml` personnalisé, vous pouvez définir des politiques de cache, des seuils de garbage collection et le nombre de workers. Un exemple minimal de `buildkitd.toml` :

```toml
[worker.oci]
  enabled = true
  gc = true
  gckeepstorage = 10737418240  # 10 Gio
  [[worker.oci.gcpolicy]]
    keepBytes = 5368709120     # 5 Gio
    keepDuration = 604800      # 7 jours
    filters = [ "type==source.local", "type==exec.cachemount", "type==source.git.checkout" ]
  [[worker.oci.gcpolicy]]
    all = true
    keepBytes = 1073741824     # 1 Gio
```

Cette configuration exécute le garbage collection automatiquement lorsque le cache dépasse 10 Gio, en conservant au moins 5 Gio des types de cache spécifiquement identifiés pendant 7 jours. Ajustez `gckeepstorage` et `keepBytes` pour correspondre à votre budget calculé. Après avoir créé le builder, exécutez un build de test et vérifiez `docker system df` pour voir si le cache est borné.

### Cache de registre distant pour les environnements CI éphémères

Dans les pipelines CI où les runners sont détruits après chaque job, le cache de build local disparaît. La solution est de pousser et de tirer des images de cache vers un registre de conteneurs. Utilisez les options `cache-to` et `cache-from` dans `docker buildx build` :

```yaml
# Exemple d'étape GitHub Actions
- name: Build and push with cache
  uses: docker/build-push-action@v5
  with:
    context: .
    push: true
    tags: yourrepo/app:latest
    cache-from: type=registry,ref=yourrepo/app:buildcache
    cache-to: type=registry,ref=yourrepo/app:buildcache,mode=max
```

Le `mode=max` exporte le cache pour toutes les couches, y compris les étapes intermédiaires, tandis que le mode `min` par défaut n'exporte le cache que pour les couches de l'image finale. Le mode max utilise plus de stockage dans le registre mais améliore considérablement les hits de cache pour les builds multi-étapes. La planification de capacité du cache de registre est différente : vous payez pour le stockage d'objets par Go-mois. Surveillez la taille de l'image de cache avec `docker manifest inspect` ou en vérifiant l'interface du registre. Une image de cache typique peut faire 1 à 2 Go ; si elle dépasse 5 Go, élaguez ou définissez une règle de rétention dans le registre.

### Garbage collection du démon Docker et pilote de stockage

Sur un hôte Docker autonome, les événements `docker system events` et les journaux du démon révèlent quand le stockage overlay2 se remplit. Activer le garbage collection du démon en définissant `--storage-opt overlay2.size=` n'est pas une option valide ; à la place, comptez sur `docker system prune` périodique ou le GC propre de BuildKit. Pour le constructeur d'images classique, le cache de couches est géré par le démon et peut être élagué avec :

```bash
docker image prune --filter "until=168h" --force
```

Pour les builders BuildKit, utilisez toujours `docker buildx prune` plutôt que `docker image prune`. Ils opèrent sur des magasins de cache différents.

## Vérification et diagnostics

Après avoir configuré les paramètres de cache, vérifiez que les hits de cache se produisent réellement dans vos builds. Le signal le plus direct est la sortie BuildKit. Une étape mise en cache montre `CACHED` à côté de la commande :

```
 => [stage-1 3/5] COPY --from=builder /app/dist ./dist      0.0s
 => [stage-1 4/5] RUN npm install --production              0.0s
 => [stage-1 5/5] CMD ["node", "server.js"]                0.0s
 => exporting to image                                       0.4s
 => => exporting layers                                      0.0s
 => => writing image sha256:...                              0.0s
```

Si vous voyez `RUN npm install` s'exécuter plutôt que `CACHED`, le cache a été manqué pour cette étape. Pour diagnostiquer pourquoi, exécutez le build avec une journalisation BuildKit verbeuse :

```bash
docker buildx build --progress=plain --no-cache-filter=install .
```

L'option `--no-cache-filter` force la reconstruction d'une étape ou d'un stage spécifique, ce qui est utile pour tester. Pour voir les métadonnées de cache d'une image, utilisez :

```bash
docker buildx imagetools inspect yourrepo/app:buildcache
```

Cela montre la liste des manifestes et peut indiquer si l'image de cache a été poussée correctement. Pour le cache local, vous pouvez inspecter les enregistrements de cache avec `docker buildx du` :

```bash
docker buildx du
```

Exemple de sortie :

```
ID                                              RECLAIMABLE  SIZE       LAST ACCESSED
3nq7k9nm0v3w74l0a1e2z7g5e                      true         180MB      2 hours ago
...
Total:                                          15.75GB
```

Utilisez `docker buildx du --verbose` pour voir quelles entrées de cache appartiennent à quel build. C'est utile lorsque vous devez déterminer si une couche de dépendance spécifique est mise en cache.

### Surveiller le taux de hits de cache

Pour une vérification continue, instrumentez les builds avec le support de tracing de BuildKit. Exportez les traces de build vers un collecteur tel que Jaeger ou OpenTelemetry. Ajoutez `--build-arg BUILDKIT_INLINE_CACHE=1` pour inclure les métadonnées de cache dans l'image finale, ce qui permet aux builds suivants d'utiliser l'image elle-même comme source de cache. Pour les métriques CI, analysez le journal de build pour la chaîne `CACHED` et calculez `étapes_mises_en_cache / étapes_totales`. Un taux de hits de cache sain pour les étapes d'installation de dépendances devrait être supérieur à 80 % pour des builds répétés avec des fichiers de dépendances inchangés.

Mettez en place une simple tâche cron ou une vérification CI qui construit un Dockerfile sentinelle et rapporte le statut du cache :

```bash
#!/bin/bash
# cache-health-check.sh
IMAGE=cache-sentinel
OUTPUT=$(docker build -t $IMAGE . 2>&1)
if echo "$OUTPUT" | grep -q "CACHED"; then
  echo "Cache hit detected"
else
  echo "Cache miss or failure; output:"
  echo "$OUTPUT"
  exit 1
fi
```

Exécutez ceci toutes les heures ou après chaque redémarrage du builder. S'il échoue, enquêtez avant de faire confiance au cache dans les builds de production.

## Modes de défaillance et récupération

Le cache de couches échoue silencieusement plus souvent que vous ne le pensez. Le mode de défaillance le plus courant est un cache vide ou incomplet parce que le builder a été recréé, le répertoire de cache effacé ou le runner CI a eu un checkout frais. Les symptômes incluent des augmentations soudaines des temps de build et une sortie de journal qui ne montre jamais `CACHED` pour les étapes précédemment mises en cache. Diagnostic : exécutez `docker buildx ls` pour voir si le builder est toujours présent et `docker buildx du` pour vérifier la taille du cache. Si la taille du cache est 0 ou très petite, le cache a été perdu. La récupération consiste à reconstruire le cache en exécutant un build complet avec `cache-to` activé, puis à mettre à jour la configuration CI pour persister le builder entre les exécutions ou utiliser un cache distant.

Un autre mode de défaillance est l'empoisonnement du cache ou la réutilisation incorrecte de couches lorsqu'une version de dépendance change sans changer le Dockerfile. Par exemple, si vous copiez `package.json` et `package-lock.json` séparément mais les ordonnez incorrectement, le cache peut réutiliser une ancienne couche `npm install` même si `package-lock.json` a changé. Symptômes : les builds réussissent mais avec des dépendances obsolètes. Corrigez le Dockerfile pour copier le fichier de verrouillage avant d'exécuter l'installation, et utilisez `--no-cache-filter=install` pour forcer une installation propre après le changement. Prévenez en vous assurant que la clé de cache de l'étape d'installation inclut le hachage du contenu des deux fichiers.

Le problème opposé est le thrash de cache : le cache croît sans limite et remplit le disque, provoquant des échecs de build avec `no space left on device`. Les symptômes incluent des processus de build tués, des erreurs `docker buildx build` concernant l'impossibilité d'allouer de la mémoire ou d'écrire une couche, et des journaux de démon montrant un disque plein. Étapes de récupération :

1. Libérez de l'espace immédiatement : `docker system prune -af --volumes` (attention : cela supprime toutes les images, conteneurs, volumes et cache inutilisés).
2. Restreignez au cache uniquement : `docker buildx prune --all --force`.
3. Augmentez l'agressivité du GC du builder en modifiant `buildkitd.toml` comme montré précédemment, en abaissant `gckeepstorage` et `keepBytes`.
4. Ajoutez des alertes d'utilisation du disque sur l'hôte, par exemple un seuil `df -h /var/lib/docker` à 80 %.

Pour le cache de registre distant, le mode de défaillance est les limites de capacité du registre ou les coûts de sortie. Si l'image de cache devient trop volumineuse, les poussées peuvent être rejetées. Surveillez le stockage du registre et définissez une politique de rétention. Utilisez `mode=min` au lieu de `mode=max` pour réduire la taille de l'image de cache si les coûts de stockage sont élevés, mais acceptez des taux de hits de cache plus faibles.

Enfin, la fuite de secrets dans les couches de cache est une défaillance de sécurité. Si vous avez accidentellement construit une image avec un secret dans une couche qui a été mise en cache et poussée comme image de cache, vous devez invalider et purger cette entrée de cache. Utilisez `docker buildx prune --filter "ref==yourrepo/app:buildcache"` après avoir supprimé l'image du registre, et faites pivoter le secret exposé.

## Pièges courants et comment les éviter

Piège 1 : Ignorer le contexte du builder. De nombreuses équipes activent BuildKit mais continuent d'utiliser le pilote docker hérité pour les builds locaux, qui ne prend pas en charge toutes les fonctionnalités de cache. Vérifiez `docker buildx ls` et assurez-vous que le builder marqué d'un `*` utilise le pilote `docker-container` ou `remote` pour les capacités avancées cache-to/cache-from. S'il indique `default * docker`, vous n'utilisez pas toutes les capacités de BuildKit.

Piège 2 : Oublier d'ordonner les étapes du Dockerfile du moins au plus fréquemment changeant. Si vous faites `COPY . .` tôt dans le Dockerfile, chaque changement de code invalide toutes les couches suivantes, y compris les installations de dépendances. Placez les copies des manifestes de dépendances et les installations avant de copier l'arborescence source complète.

Piège 3 : Ne pas utiliser de montages de cache pour les caches des gestionnaires de paquets. `RUN --mount=type=cache,target=/root/.npm npm install` permet à BuildKit de réutiliser le cache npm entre les builds même lorsque les dépendances changent. Sans cela, le gestionnaire de paquets télécharge tout à chaque changement de dépendance.

Piège 4 : Élaguer excessivement avec un `docker system prune` large. Cette commande supprime toutes les images et conteneurs inutilisés ainsi que le cache. Si vous élaguez des images utilisées comme sources de cache via le cache inline, vous perdez le cache. Utilisez plutôt `docker buildx prune` avec des filtres.

Piège 5 : Supposer que la taille du cache est égale à l'utilisation du disque sur l'hôte. Avec un builder docker-container, le cache vit dans un volume qui peut ne pas être compté par `df /var/lib/docker`. Utilisez toujours `docker buildx du` et `docker buildx ls` pour voir la taille et l'emplacement réels du cache.

Récupération de l'un de ces pièges : revenez sur le dernier changement de configuration, exécutez un build propre avec un cache-to explicite et vérifiez avec le script de vérification de santé du cache.

## Liste de contrôle opérationnelle

La planification de capacité est une pratique continue. Examinez les performances du cache mensuellement, ou plus fréquemment si les temps de build fluctuent. Attribuez un responsable de l'optimisation du cache, généralement l'ingénieur de plateforme CI/CD ou un développeur senior dans une startup. Le responsable doit :

- Hebdomadairement : vérifier `docker buildx du` et `docker system df` sur chaque builder ; s'assurer que la taille du cache reste dans les 70 % de l'espace disque alloué.
- Mensuellement : examiner le taux de hits de cache à partir des journaux CI ; s'il est inférieur à 80 % pour les couches de dépendances, enquêter sur les causes et ajuster la rétention du cache ou la structure du Dockerfile.
- Trimestriellement : réévaluer le budget de cache en utilisant la formule de la section dimensionnement ; mettre à jour les politiques de rétention et les configurations du builder.
- À chaque changement d'image ou de builder : exécuter le script de vérification de santé du cache et comparer les temps de build à la référence.

Utilisez cette liste de contrôle concrète avant de déployer des changements de cache dans un environnement de type production :

```markdown
- [ ] Nom et pilote du builder actuel enregistrés : `docker buildx ls`
- [ ] Taille du cache avant changement : total de `docker buildx du`
- [ ] Sauvegarde ou note de la référence du cache distant le cas échéant : par exemple, yourrepo/app:buildcache
- [ ] Changement effectué : (par exemple, ajout du cache-to mode max, ajustement de gckeepstorage)
- [ ] Build de test terminé : `docker build .` montre les étapes CACHED attendues
- [ ] Taille du cache après changement : total de `docker buildx du`
- [ ] Temps de build enregistré : avant et après
- [ ] Commande de rollback identifiée : par exemple, restaurer le buildkitd.toml précédent, recréer le builder
```

Lorsqu'une décision de cache implique de dépenser de l'argent (plus de disque ou de stockage de registre), le responsable doit documenter le coût mensuel et la réduction attendue des minutes de build CI. Révisez ce compromis avec le chef d'équipe chaque trimestre.

## Conclusion

La planification de capacité du cache de couches Docker transforme une fonctionnalité de performance invisible en une ressource gérée. Les étapes sont concrètes : inventoriez votre builder et l'emplacement du cache, calculez un budget de cache à partir des tailles réelles des couches, configurez un builder dédié avec des limites GC explicites ou un cache distant pour la CI éphémère, vérifiez les hits de cache avec des commandes journalisées et préparez des procédures de récupération pour les modes de défaillance courants de perte de cache, de thrash et d'empoisonnement.

Commencez par un seul changement à faible risque : créez un builder nommé avec un `buildkitd.toml` qui définit `gckeepstorage` à votre budget calculé, puis exécutez deux builds de votre application et comparez les temps. Enregistrez la taille du cache avant et après, et mettez en place une vérification hebdomadaire `docker buildx du`. N'étendez au cache de registre qu'une fois que le cache local est stable et observé.

Une configuration de cache fiable rend sa propre performance visible. Lorsqu'un build ralentit, vous devriez pouvoir pointer vers le taux de hits de cache, la taille du cache et la politique de rétention, et savoir exactement quel levier tourner.