BuildKit et Buildx : construire des images Docker modernes

Vos builds Docker prennent trop de temps en CI/CD ? Vous devez supporter ARM et x86 avec la même image ? BuildKit est le moteur de construction moderne de Docker, intégré par défaut depuis la version 23.0. Ce guide vous montre comment exploiter ses fonctionnalités avancées : builds parallélisés, images multi-plateformes, cache distribué et secrets sécurisés.

TL;DR — Les 5 points clés

1. BuildKit : moteur de build par défaut depuis Docker 23.0, plus rapide et plus intelligent
2. Buildx : plugin CLI qui expose toutes les fonctionnalités de BuildKit
3. Driver docker-container : indispensable pour multi-plateforme et cache avancé
4. Cache distribué : --cache-to/--cache-from pour partager le cache entre runners CI
5. Secrets au build : --mount=type=secret pour ne jamais exposer de credentials

Nouveauté v0.27.0 : images signées

Depuis BuildKit v0.27.0 (janvier 2026), les images de release officielles sont signées cryptographiquement via Docker GitHub Builder. Vous pouvez vérifier leur provenance avec Cosign :

cosign verify moby/buildkit:v0.27.0 \
  --certificate-identity-regexp=".*" \
  --certificate-oidc-issuer-regexp=".*"

Autres nouveautés : cache GitHub signé (vérification cryptographique à l’import), push parallèle des blobs de cache registry, et Dockerfile frontend v1.21.0 intégré.

Ce que vous allez apprendre

• Architecture BuildKit : comprendre LLB, frontends et drivers
• Gestion des builders : créer, inspecter et basculer entre instances
• Multi-plateforme : construire des images linux/amd64, linux/arm64 en une commande
• Cache avancé : registry, GHA, S3 pour accélérer les builds CI/CD
• Secrets au build : monter des credentials sans les exposer dans l’image

Analogie : l’usine de construction modulaire

Pensez à BuildKit comme une usine de construction modulaire :

Concept BuildKit	Équivalent usine
Frontend (dockerfile:1)	Plan de l’architecte → traduit en instructions usine
LLB (Low-Level Build)	Ordres de fabrication standardisés
DAG Solver	Chef d’atelier qui parallélise les tâches indépendantes
Drivers	Différents sites de production (local, conteneur, Kubernetes)
Cache	Entrepôt de pièces pré-fabriquées pour réutilisation

Glissez pour voir

Prérequis

• Docker 23.0+ (BuildKit activé par défaut) ou Docker Desktop
• Connaissances de base en Dockerfile
• Pour multi-plateforme : QEMU ou accès à des runners ARM natifs

Vérifier votre version :

docker version --format '{{.Server.Version}}'
# 24.0.0 ou supérieur

docker buildx version
# github.com/docker/buildx v0.12.0 ou supérieur

Architecture de BuildKit

Qu’est-ce que BuildKit ?

BuildKit est le moteur de construction d’images de conteneurs développé par le projet Moby. Il remplace l’ancien builder Docker et apporte des améliorations majeures :

Fonctionnalité	Ancien builder	BuildKit
Parallélisation	Séquentiel	✅ Étapes indépendantes en parallèle
Cache	Par couche	✅ Par checksum de contenu
Multi-plateforme	❌ Non	✅ Natif avec --platform
Secrets au build	❌ Impossible	✅ --mount=type=secret
SSH forwarding	❌ Impossible	✅ --mount=type=ssh
Cache distribué	❌ Non	✅ Registry, GHA, S3

Glissez pour voir

Les composants clés

1. Frontend : convertit votre Dockerfile en instructions LLB

   Le frontend par défaut est docker/dockerfile:1. Vous pouvez en utiliser d’autres (comme Buildpacks) en spécifiant # syntax= en première ligne.

2. LLB (Low-Level Build) : format binaire intermédiaire

   C’est le “langage machine” de BuildKit. Chaque opération est un nœud dans un graphe de dépendances (DAG).

3. DAG Solver : optimise l’exécution

   • Détecte les étapes indépendantes pour les paralléliser
   • Skip les étapes dont le résultat est déjà en cache
   • Optimise le transfert des fichiers depuis le contexte

4. Exporters : génèrent la sortie finale

   • image : image OCI vers Docker ou registry
   • local : fichiers vers un dossier local
   • tar : archive tar
   • oci : bundle OCI

Buildx : le plugin CLI

Buildx est le plugin Docker CLI qui expose toutes les fonctionnalités de BuildKit. Il remplace progressivement docker build par docker buildx build.

docker build vs docker buildx build

Depuis Docker 23.0, docker build utilise BuildKit par défaut, mais certaines fonctionnalités avancées (multi-plateforme, cache distribué) ne sont accessibles qu’avec docker buildx build et un driver approprié.

Les 4 drivers Buildx

Driver	Description	Multi-arch	Cache avancé	Cas d’usage
docker	Utilise le daemon Docker local	❌	❌	Développement simple
docker-container	BuildKit dans un conteneur dédié	✅ QEMU	✅	Recommandé pour CI/CD
kubernetes	Pods BuildKit sur un cluster K8s	✅	✅	Builds à grande échelle
remote	Se connecte à un buildkitd distant	✅	✅	Build distribué

Glissez pour voir

Gestion des builders

Lister les builders disponibles

docker buildx ls

Sortie typique :

NAME/NODE           DRIVER/ENDPOINT                   STATUS    BUILDKIT   PLATFORMS
default *           docker
  default             default                         running   v0.27.0    linux/amd64, linux/amd64/v2, linux/amd64/v3, linux/386

L’astérisque * indique le builder actif. Le driver docker par défaut utilise le daemon Docker local et a des limitations (pas de multi-plateforme, pas de cache distribué).

Créer un builder docker-container

Pour débloquer multi-plateforme et cache avancé, créez un builder avec le driver docker-container :

docker buildx create \
  --name mybuilder \
  --driver docker-container \
  --bootstrap \
  --use

Option	Description
--name	Nom du builder
--driver	Type de driver (docker-container recommandé)
--bootstrap	Démarre immédiatement le conteneur BuildKit
--use	Définit ce builder comme défaut

Glissez pour voir

Vérification :

docker buildx inspect mybuilder

Name:          mybuilder
Driver:        docker-container
Last Activity: 2026-01-21 16:57:35 +0000 UTC

Nodes:
Name:                  mybuilder0
Endpoint:              unix:///var/run/docker.sock
Status:                running
BuildKit version:      v0.27.0
Platforms:             linux/amd64, linux/amd64/v2, linux/amd64/v3, linux/386
Labels:
 org.mobyproject.buildkit.worker.executor:         oci
 org.mobyproject.buildkit.worker.snapshotter:      overlayfs

Le builder est maintenant actif et prêt à exécuter des builds multi-plateformes. Notez que sans QEMU installé, seules les architectures compatibles avec votre machine hôte sont disponibles.

Basculer entre builders

Une fois plusieurs builders créés, vous pouvez basculer entre eux :

# Utiliser un builder spécifique
docker buildx use mybuilder

# Vérifier le builder actif
docker buildx ls

NAME/NODE           DRIVER/ENDPOINT                   STATUS    BUILDKIT   PLATFORMS
mybuilder*          docker-container
  mybuilder0          unix:///var/run/docker.sock     running   v0.26.3    linux/amd64 (+3), linux/386
default             docker
  default             default                         running   v0.26.2    linux/amd64 (+3)

# Revenir au builder par défaut
docker buildx use default

Supprimer un builder

Quand un builder n’est plus nécessaire, vous pouvez le supprimer :

# Supprimer en conservant le cache (volume Docker)
docker buildx rm --keep-state mybuilder

# Supprimer complètement (builder + cache)
docker buildx rm mybuilder

Persistance du cache

Avec --keep-state, le volume Docker contenant le cache est préservé. Si vous recréez un builder avec le même nom, il récupérera automatiquement ce cache. C’est utile pour redémarrer un builder corrompu sans perdre des heures de cache accumulé.

Exemple concret :

# Builder corrompu ou plantage
docker buildx rm --keep-state ci-builder

# Recréer avec le même nom
docker buildx create --name ci-builder --driver docker-container --use

# Le cache est toujours là !

Builds multi-plateformes

L’un des avantages majeurs de BuildKit est la capacité de construire des images pour plusieurs architectures en une seule commande.

Prérequis QEMU (Linux sans Docker Desktop)

Sur Docker Engine Linux, installez QEMU pour l’émulation :

docker run --privileged --rm tonistiigi/binfmt --install all

Vérification :

docker buildx inspect --bootstrap
# Doit lister linux/arm64, linux/arm/v7, etc.

Construire pour plusieurs plateformes

docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --tag mon-registry/mon-app:1.0 \
  --push \
  .

Option	Description
--platform	Liste des architectures cibles
--push	Pousse directement vers la registry (obligatoire pour multi-arch)
--load	Charge dans Docker local (impossible en multi-arch)

Glissez pour voir

--load vs --push en multi-plateforme

L’option --load ne fonctionne pas avec plusieurs plateformes car Docker local ne peut stocker qu’une seule architecture. Utilisez --push pour pousser vers une registry, ou --output type=oci,dest=image.tar pour exporter en fichier.

Les 3 stratégies multi-plateforme

QEMU (émulation)

Le plus simple : BuildKit émule les architectures non-natives via QEMU.

docker buildx build --platform linux/amd64,linux/arm64 -t myapp --push .

Avantages :

• Aucune configuration complexe
• Fonctionne partout

Inconvénients :

• Lent pour les compilations (10-50× plus lent)
• Consomme beaucoup de CPU

Nodes natifs

Le plus rapide : utilisez des runners natifs pour chaque architecture.

# Créer un builder multi-nodes
docker buildx create --name multi --driver docker-container --use node-amd64
docker buildx create --append --name multi node-arm64

docker buildx build --platform linux/amd64,linux/arm64 -t myapp --push .

Avantages :

• Performance native
• Pas d’émulation

Inconvénients :

• Infrastructure plus complexe
• Nécessite des runners ARM

Cross-compilation

Le plus efficace pour les langages compilés (Go, Rust) : compilez depuis l’architecture native vers la cible.

# syntax=docker/dockerfile:1
FROM --platform=$BUILDPLATFORM golang:1.21-alpine AS builder
ARG TARGETOS TARGETARCH
WORKDIR /app
COPY . .
RUN GOOS=${TARGETOS} GOARCH=${TARGETARCH} go build -o /app/main .

FROM alpine:3.19
COPY --from=builder /app/main /main
ENTRYPOINT ["/main"]

docker buildx build --platform linux/amd64,linux/arm64 -t myapp --push .

Avantages :

• Vitesse native
• Pas d’émulation

Inconvénients :

• Requiert un support du langage (Go, Rust)
• Ne fonctionne pas pour tous les projets

Cache avancé

BuildKit supporte plusieurs backends de cache pour partager le cache entre builds, particulièrement utile en CI/CD où chaque job démarre sur un runner frais.

Les backends de cache

Backend	Description	Driver requis	Cas d’usage
inline	Cache embarqué dans l’image	Tous	Simple, image unique
registry	Cache séparé dans une registry	docker-container	CI/CD avec registry privée
local	Fichiers sur le système de fichiers	docker-container	Builds locaux
gha	GitHub Actions cache	docker-container	GitHub Actions
s3	AWS S3 bucket	docker-container	CI/CD multi-cloud
azblob	Azure Blob Storage	docker-container	CI/CD Azure

Glissez pour voir

Cache registry (recommandé pour CI/CD)

Le cache est stocké dans une image séparée sur votre registry :

docker buildx build \
  --cache-from type=registry,ref=mon-registry/myapp:cache \
  --cache-to type=registry,ref=mon-registry/myapp:cache,mode=max \
  --tag mon-registry/myapp:1.0 \
  --push \
  .

Paramètre	Description
mode=min	Cache uniquement les couches de l’image finale (défaut)
mode=max	Cache toutes les couches, y compris les stages intermédiaires

Glissez pour voir

mode=max pour multi-stage

Utilisez mode=max si vous avez des builds multi-stage. Sans cela, seul le stage final est mis en cache, perdant le bénéfice du cache pour le stage de build.

Cache GitHub Actions

Idéal pour les workflows GitHub Actions :

.github/workflows/build.yml

name: Build and Push

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Login to Registry
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Build and push
        uses: docker/build-push-action@v6
        with:
          context: .
          push: true
          tags: ghcr.io/${{ github.repository }}:${{ github.sha }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

Importer depuis plusieurs caches

Vous pouvez importer le cache depuis plusieurs sources (branche courante + main) :

docker buildx build \
  --cache-from type=registry,ref=registry/app:cache-$BRANCH \
  --cache-from type=registry,ref=registry/app:cache-main \
  --cache-to type=registry,ref=registry/app:cache-$BRANCH,mode=max \
  --push .

Secrets au build

BuildKit permet de monter des secrets pendant le build sans qu’ils n’apparaissent dans l’image finale.

Pourquoi c’est important ?

# ❌ DANGER : le secret reste dans l'historique des couches
ARG NPM_TOKEN
RUN echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > .npmrc \
    && npm ci \
    && rm .npmrc
# Le secret est visible avec "docker history"

Utiliser —mount=type=secret

# syntax=docker/dockerfile:1
FROM node:20-alpine
WORKDIR /app
COPY package*.json ./

# ✅ Secret monté temporairement, jamais dans l'image
RUN --mount=type=secret,id=npmrc,target=/root/.npmrc \
    npm ci --omit=dev

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

Commande de build :

docker buildx build \
  --secret id=npmrc,src=$HOME/.npmrc \
  -t myapp .

SSH forwarding

Pour cloner des repos privés sans exposer la clé SSH :

# syntax=docker/dockerfile:1
FROM alpine
RUN apk add --no-cache git openssh-client

# Clone avec la clé SSH de l'hôte
RUN --mount=type=ssh \
    git clone git@github.com:org/private-repo.git /app

docker buildx build --ssh default -t myapp .

Dépannage

Le cache n’est jamais utilisé

Symptôme : chaque build recommence de zéro.

Cause	Solution
Driver docker	Passez à docker-container
--no-cache dans la commande	Retirer cette option
--cache-from incorrect	Vérifier le ref de la registry
Registry inaccessible	Vérifier les credentials

Glissez pour voir

# Vérifier le driver actif
docker buildx inspect

# Voir les logs du builder
docker logs buildx_buildkit_mybuilder0

Build multi-plateforme échoue

Symptôme : erreur exec format error ou build qui plante.

Cause	Solution
QEMU non installé	docker run --privileged --rm tonistiigi/binfmt --install all
Image de base non disponible	Vérifier que l’image existe pour la plateforme cible
Commandes incompatibles	Utiliser des images multi-arch ou cross-compiler

Glissez pour voir

Espace disque saturé

BuildKit accumule du cache dans son volume. Sur des builds CI/CD répétés, cela peut rapidement atteindre plusieurs Go. Nettoyez régulièrement :

# Voir l'espace utilisé par builder
docker buildx du

Exemple de sortie :

ID                           RECLAIMABLE   SIZE      LAST ACCESSED
6qz04izv37q7h9bz6swhoguxm    true          0B        2 minutes ago
snf1d9cpv9w1w4p9shvb10niv*   true          8.192kB   2 minutes ago
swr54o7l18c7mp9ik8ckv64wo*   true          8.192kB   2 minutes ago
pqodoch6223u35j2giitjl4vz*   true          20.48kB   2 minutes ago
i47mgx85k11bu1c6trxwykg3e    true          40.97MB   2 minutes ago
Reclaimable:    41.01MB
Total:          41.01MB

Les entrées marquées RECLAIMABLE: true peuvent être supprimées sans impact sur les futurs builds (mais ils seront plus lents sans cache).

# Nettoyer le cache inutilisé (garde les couches récentes)
docker buildx prune

# Nettoyer tout (libère le maximum d'espace)
docker buildx prune --all

# Nettoyer un builder spécifique
docker buildx prune --builder mybuilder

CI/CD : attention à l'espace disque

En CI/CD, si vous construisez beaucoup d’images différentes, le cache peut rapidement saturer les runners. Ajoutez docker buildx prune --all -f en fin de pipeline ou configurez une règle de nettoyage automatique.

Bonnes pratiques

Performance

1. Utilisez mode=max pour le cache en CI/CD avec des builds multi-stage
2. Cross-compilez quand le langage le supporte (Go, Rust)
3. Parallélisez les étapes indépendantes dans le Dockerfile
4. Utilisez les cache mounts pour npm, pip, apt

Sécurité

1. Jamais de secrets en ARG/ENV — utilisez --mount=type=secret
2. Vérifiez les images de base avec un scanner (Trivy, Grype)
3. Utilisez des tags immutables ou des digests pour la reproductibilité
4. Activez la signature d’images avec Docker Content Trust

Organisation

1. Variables d’environnement pour TAG, REGISTRY dans vos scripts CI
2. Targets séparés pour dev/staging/prod si vous utilisez Docker Bake
3. Documentation des commandes de build dans le README du projet

Testez vos connaissances

Vérifiez votre compréhension de BuildKit et Buildx :

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

7 questions

5 min.

80% requis

Informations

• Le chronomètre démarre au clic sur Démarrer
• Questions à choix multiples, vrai/faux et réponses courtes
• Vous pouvez naviguer entre les questions
• Les résultats détaillés sont affichés à la fin

Démarrer le quiz

Lance le quiz et démarre le chronomètre

À retenir

1. BuildKit est le moteur de build par défaut depuis Docker 23.0, avec parallélisation et cache intelligent
2. Buildx est le plugin CLI qui expose toutes les fonctionnalités avancées de BuildKit
3. Driver docker-container est requis pour multi-plateforme et cache distribué
4. 3 stratégies multi-arch : QEMU (simple), nodes natifs (rapide), cross-compilation (optimal)
5. Cache distribué (registry, gha, s3) : essentiel pour accélérer les builds CI/CD
6. Secrets au build : --mount=type=secret pour ne jamais exposer de credentials dans l’image

Questions fréquentes

Quelles sont les nouveautés sécurité de BuildKit v0.27.0 ?

BuildKit v0.27.0 (janvier 2026) introduit les images de release signées cryptographiquement (vérifiables avec Cosign), un cache GitHub signé et vérifié à l'import, et le Dockerfile frontend v1.21.0. Ces fonctionnalités renforcent la sécurité de la supply chain du build.

Quelle est la différence entre BuildKit et Buildx ?

BuildKit est le moteur de construction d'images (backend) développé par Moby. Buildx est le plugin CLI Docker qui expose les fonctionnalités de BuildKit via des commandes comme docker buildx build.

Comment activer BuildKit avec Docker ?

Depuis Docker 23.0, BuildKit est activé par défaut. Pour les versions antérieures, définissez DOCKER_BUILDKIT=1 ou configurez le daemon Docker avec features.buildkit: true.

Quel driver Buildx utiliser pour les builds CI/CD ?

Utilisez le driver docker-container pour la CI/CD. Il supporte les builds multi-plateformes via QEMU, le cache distribué (registry, GHA, S3) et les exports avancés.

Comment construire une image pour ARM et x86 en même temps ?

Créez un builder docker-container, installez QEMU pour l'émulation, puis utilisez docker buildx build avec --platform linux/amd64,linux/arm64 et --push pour pousser vers une registry.

Comment partager le cache Docker entre les jobs CI/CD ?

Utilisez --cache-from et --cache-to avec un backend distribué : registry (image de cache), gha (GitHub Actions), s3 (AWS) ou azblob (Azure). Activez mode=max pour cacher les stages intermédiaires.

Comment utiliser des secrets pendant le build sans les exposer dans l'image ?

Utilisez RUN --mount=type=secret dans le Dockerfile et passez --secret id=...,src=... à docker buildx build. Le secret est monté temporairement pendant le build mais n'apparaît pas dans l'image finale.

Qu'est-ce que Docker Bake et quand l'utiliser ?

Docker Bake permet de définir les builds dans un fichier HCL déclaratif au lieu de longues commandes. Utilisez-le pour plusieurs images, des configurations complexes ou pour versionner la config dans le repo.

Pourquoi mon build multi-plateforme échoue avec 'exec format error' ?

L'erreur exec format error signifie que QEMU n'est pas installé. Sur Linux, exécutez : docker run --privileged --rm tonistiigi/binfmt --install all pour installer les émulateurs.

Comment nettoyer le cache BuildKit pour libérer de l'espace ?

Utilisez docker buildx du pour voir l'espace utilisé, puis docker buildx prune pour nettoyer le cache inutilisé ou docker buildx prune --all pour tout supprimer.

Quelle est la différence entre mode=min et mode=max pour le cache ?

mode=min cache uniquement l'image finale, mode=max cache toutes les couches y compris les stages intermédiaires. Utilisez mode=max pour les builds multi-stage en CI/CD.

Pour aller plus loin

Docker Bake : builds déclaratifs Orchestrer plusieurs builds avec un fichier HCL

Bonnes pratiques Dockerfile Optimiser cache, multi-stage, non-root, healthcheck

CI/CD d'images conteneurs Stratégies de tags, registries, pipelines

Kaniko : builds sans daemon Alternative à BuildKit pour Kubernetes

Sécuriser la supply chain Signatures, SBOM, attestations de build

×

📖 Voir la documentation →