Collecte des déchets de construction

Alors que les commandes docker builder prune ou docker buildx prune s'exécutent en une fois, la Collecte des Déchets (GC) s'exécute périodiquement et suit une liste ordonnée de politiques de nettoyage. Le démon BuildKit nettoie le cache de construction lorsque la taille du cache devient trop grande, ou lorsque l'âge du cache expire.

Pour la plupart des utilisateurs, le comportement par défaut de la GC est suffisant et ne nécessite aucune intervention. Les utilisateurs avancés, en particulier ceux qui travaillent avec des constructions à grande échelle, des constructeurs autogérés ou des environnements de stockage contraints, pourraient bénéficier de la personnalisation de ces paramètres pour mieux s'aligner sur leurs besoins de flux de travail. Les sections suivantes expliquent comment fonctionne la GC et fournissent des conseils pour adapter son comportement grâce à une configuration personnalisée.

Politiques de collecte des déchets

Les politiques de GC définissent un ensemble de règles qui déterminent comment le cache de construction est géré et nettoyé. Ces politiques incluent des critères pour déterminer quand supprimer des entrées de cache, tels que l'âge du cache, la quantité d'espace utilisée et le type d'enregistrements de cache à nettoyer.

Chaque politique de GC est évaluée en séquence, en commençant par les critères les plus spécifiques, et procède à des règles plus larges si les politiques précédentes ne libèrent pas assez de cache. Cela permet à BuildKit de prioriser les entrées de cache, préservant le cache le plus précieux tout en garantissant que le système maintient ses performances et sa disponibilité.

Par exemple, supposons que vous ayez les politiques de GC suivantes :

1. Trouver les enregistrements de cache "périmés" qui n'ont pas été utilisés au cours des dernières 48 heures, et supprimer les enregistrements jusqu'à ce qu'il reste au maximum 5 Go de cache "périmé".
2. Si la taille du cache de construction dépasse 10 Go, supprimer les enregistrements jusqu'à ce que la taille totale du cache ne dépasse pas 10 Go.

La première règle est plus spécifique, priorisant les enregistrements de cache périmés et fixant une limite inférieure pour un type de cache moins précieux. La deuxième règle impose une limite stricte plus élevée qui s'applique à tout type d'enregistrements de cache. Avec ces politiques, si vous avez 11 Go de cache de construction, où :

• 7 Go sont du cache "périmé"
• 4 Go sont d'autres caches plus précieux

Un passage de GC supprimerait 5 Go de cache périmé dans le cadre de la 1ère politique, avec un reste de 6 Go, ce qui signifie que la 2ème politique n'a pas besoin de nettoyer plus de cache.

Les politiques de GC par défaut sont (approximativement) :

1. Supprimer le cache qui peut être facilement régénéré, comme les contextes de construction provenant de répertoires locaux ou de dépôts Git distants, et les montages de cache, s'ils n'ont pas été utilisés depuis plus de 48 heures.
2. Supprimer le cache qui n'a pas été utilisé dans une construction depuis plus de 60 jours.
3. Supprimer le cache non partagé qui dépasse la limite de taille du cache de construction. Les enregistrements de cache non partagés font référence aux blobs de couche qui ne sont pas utilisés par d'autres ressources (généralement, comme couches d'image).
4. Supprimer tout cache de construction qui dépasse la limite de taille du cache de construction.

L'algorithme précis et les moyens de configurer les politiques diffèrent légèrement selon le type de constructeur que vous utilisez. Référez-vous à Configuration pour plus de détails.

Configuration

Note

Si vous êtes satisfait du comportement par défaut de la collecte des déchets et n'avez pas besoin d'affiner ses paramètres, vous pouvez ignorer cette section. Les configurations par défaut fonctionnent bien pour la plupart des cas d'utilisation et ne nécessitent aucune configuration supplémentaire.

Selon le type de pilote de construction que vous utilisez, vous utiliserez différents fichiers de configuration pour modifier les paramètres de GC du constructeur :

• Si vous utilisez le constructeur par défaut pour Docker Engine (le pilote docker), utilisez le fichier de configuration du démon Docker.
• Si vous utilisez un constructeur personnalisé, utilisez un fichier de configuration BuildKit.

Fichier de configuration du démon Docker

Si vous utilisez le pilote docker par défaut, la GC est configurée dans le fichier de configuration daemon.json, ou si vous utilisez Docker Desktop, dans Paramètres > Docker Engine.

L'extrait suivant montre la configuration du constructeur par défaut pour le pilote docker pour les utilisateurs de Docker Desktop :

{
  "builder": {
    "gc": {
      "defaultKeepStorage": "20GB",
      "enabled": true
    }
  }
}

L'option defaultKeepStorage configure la limite de taille du cache de construction, qui influence les politiques de GC. Les politiques par défaut pour le pilote docker fonctionnent comme suit :

1. Supprimer le cache de construction éphémère et inutilisé de plus de 48 heures s'il dépasse 13,8 % de defaultKeepStorage, ou au minimum 512 Mo.
2. Supprimer le cache de construction inutilisé de plus de 60 jours.
3. Supprimer le cache de construction non partagé qui dépasse la limite defaultKeepStorage.
4. Supprimer tout cache de construction qui dépasse la limite defaultKeepStorage.

Étant donné la valeur par défaut de Docker Desktop pour defaultKeepStorage de 20 Go, les politiques de GC par défaut se résolvent en :

{
  "builder": {
    "gc": {
      "enabled": true,
      "policy": [
        {
          "keepStorage": "2.764GB",
          "filter": [
            "unused-for=48h",
            "type==source.local,type==exec.cachemount,type==source.git.checkout"
          ]
        },
        { "keepStorage": "20GB", "filter": ["unused-for=1440h"] },
        { "keepStorage": "20GB" },
        { "keepStorage": "20GB", "all": true }
      ]
    }
  }
}

Le moyen le plus simple d'ajuster la configuration du cache de construction pour le pilote docker est d'ajuster l'option defaultKeepStorage :

• Augmentez la limite si vous pensez que la GC est trop agressive.
• Diminuez la limite si vous devez préserver de l'espace.

Si vous avez besoin de plus de contrôle, vous pouvez définir vos propres politiques de GC directement. L'exemple suivant définit une configuration de GC plus conservatrice avec les politiques suivantes :

1. Supprimer les entrées de cache inutilisées de plus de 1440 heures, soit 60 jours, si le cache de construction dépasse 50 Go.
2. Supprimer les entrées de cache non partagées si le cache de construction dépasse 50 Go.
3. Supprimer toutes les entrées de cache si le cache de construction dépasse 100 Go.

{
  "builder": {
    "gc": {
      "enabled": true,
      "defaultKeepStorage": "50GB",
      "policy": [
        { "keepStorage": "0", "filter": ["unused-for=1440h"] },
        { "keepStorage": "0" },
        { "keepStorage": "100GB", "all": true }
      ]
    }
  }
}

Les politiques 1 et 2 ici définissent keepStorage à 0, ce qui signifie qu'elles retomberont à la limite par défaut de 50 Go comme défini par defaultKeepStorage.

Fichier de configuration BuildKit

Pour les pilotes de construction autres que docker, la GC est configurée à l'aide d'un fichier de configuration buildkitd.toml. Ce fichier utilise les options de configuration de haut niveau suivantes que vous pouvez utiliser pour ajuster les seuils de l'espace disque que BuildKit devrait utiliser pour le cache :

Vous pouvez définir ces options soit en nombre d'octets, une chaîne d'unité (par exemple, 512MB), ou en pourcentage de la taille totale du disque. Modifier ces options influence les politiques de GC par défaut utilisées par le travailleur BuildKit. Avec les seuils par défaut, les politiques de GC se résolvent comme suit :

# Valeurs par défaut globales
[worker.oci]
  gc = true
  reservedSpace = "10GB"
  maxUsedSpace = "100GB"
  minFreeSpace = "20%"

# Politique 1
[[worker.oci.gcpolicy]]
  filters = [ "type==source.local", "type==exec.cachemount", "type==source.git.checkout" ]
  keepDuration = "48h"
  maxUsedSpace = "512MB"

# Politique 2
[[worker.oci.gcpolicy]]
  keepDuration = "1440h" # 60 jours
  reservedSpace = "10GB"
  maxUsedSpace = "100GB"

# Politique 3
[[worker.oci.gcpolicy]]
  reservedSpace = "10GB"
  maxUsedSpace = "100GB"

# Politique 4
[[worker.oci.gcpolicy]]
  all = true
  reservedSpace = "10GB"
  maxUsedSpace = "100GB"

En termes pratiques, cela signifie :

• Politique 1 : Si le cache de construction dépasse 512 Mo, BuildKit supprime les enregistrements de cache pour les contextes de construction locaux, les contextes Git distants et les montages de cache qui n'ont pas été utilisés au cours des dernières 48 heures.
• Politique 2 : Si l'utilisation du disque dépasse 100 Go, le cache de construction non partagé de plus de 60 jours est supprimé, garantissant qu'au moins 10 Go d'espace disque sont réservés pour le cache.
• Politique 3 : Si l'utilisation du disque dépasse 100 Go, tout cache non partagé est supprimé, garantissant qu'au moins 10 Go d'espace disque sont réservés pour le cache.
• Politique 4 : Si l'utilisation du disque dépasse 100 Go, tout le cache—y compris les enregistrements partagés et internes—est supprimé, garantissant qu'au moins 10 Go d'espace disque sont réservés pour le cache.

reservedSpace a la priorité la plus élevée pour définir la limite inférieure de la taille du cache de construction. Si maxUsedSpace ou minFreeSpace définiraient une valeur inférieure, la taille minimale du cache ne serait jamais réduite en dessous de reservedSpace.

Si à la fois reservedSpace et maxUsedSpace sont définis, un passage de GC résulte en une taille de cache entre ces seuils. Par exemple, si reservedSpace est défini à 10 Go, et maxUsedSpace est défini à 20 Go, la quantité résultante de cache après une exécution de GC est inférieure à 20 Go, mais au moins 10 Go.

Vous pouvez également définir des politiques de GC complètement personnalisées. Les politiques personnalisées vous permettent également de définir des filtres, ce qui vous permet de cibler précisément les types d'entrées de cache qu'une politique donnée est autorisée à nettoyer.

Politiques de GC personnalisées dans BuildKit

Les politiques de GC personnalisées vous permettent d'affiner la façon dont BuildKit gère son cache, et vous donnent un contrôle total sur la rétention du cache basée sur des critères tels que le type de cache, la durée ou les seuils d'espace disque. Si vous avez besoin d'un contrôle total sur le cache, les politiques de GC personnalisées sont le moyen d'y parvenir.