Recolección de basura de compilación

Mientras que los comandos docker builder prune o docker buildx prune se ejecutan de forma inmediata, la recolección de basura (Garbage Collection - GC) se ejecuta periódicamente y sigue una lista ordenada de políticas de limpieza (prune). El demonio de BuildKit limpia el caché de compilación cuando el tamaño del caché se vuelve demasiado grande o cuando expira la antigüedad del caché.

Para la mayoría de los usuarios, el comportamiento predeterminado de la GC es suficiente y no requiere ninguna intervención. Los usuarios avanzados, especialmente aquellos que trabajan con compilaciones a gran escala, builders autogestionados o entornos de almacenamiento limitados, podrían beneficiarse de personalizar estos ajustes para alinearlos mejor con las necesidades de su flujo de trabajo. Las siguientes secciones explican cómo funciona la GC y ofrecen orientación sobre cómo adaptar su comportamiento mediante una configuración personalizada.

Políticas de recolección de basura

Las políticas de GC definen un conjunto de reglas que determinan cómo se gestiona y limpia el caché de compilación. Estas políticas incluyen criterios para saber cuándo eliminar entradas del caché, como la antigüedad del caché, la cantidad de espacio utilizado y el tipo de registros de caché a limpiar.

Cada política de GC se evalúa en secuencia, comenzando con los criterios más específicos, y avanza hacia reglas más amplias si las políticas anteriores no liberan suficiente caché. Esto permite que BuildKit priorice las entradas de caché, preservando el caché más valioso mientras se asegura de que el sistema mantenga el rendimiento y la disponibilidad.

Por ejemplo, supongamos que tienes las siguientes políticas de GC:

1. Buscar registros de caché "obsoletos" que no se hayan utilizado en las últimas 48 horas y eliminar registros hasta que quede un máximo de 5 GB de caché "obsoleto".
2. Si el tamaño del caché de compilación supera los 10 GB, eliminar registros hasta que el tamaño total del caché no sea superior a 10 GB.

La primera regla es más específica, priorizando los registros de caché obsoletos y estableciendo un límite más bajo para un tipo de caché menos valioso. La segunda regla impone un límite estricto más alto que se aplica a cualquier tipo de registro de caché. Con estas políticas, si tienes 11 GB de caché de compilación, donde:

• 7 GB corresponden a caché "obsoleto"
• 4 GB corresponden a otro caché más valioso

Un barrido de GC eliminaría 5 GB de caché obsoleto como parte de la primera política, dejando un remanente de 6 GB, lo que significa que la segunda política no necesita limpiar más caché.

Las políticas de GC predeterminadas son (aproximadamente):

1. Eliminar el caché que se puede regenerar fácilmente, como los contextos de compilación de directorios locales o repositorios Git remotos, y los montajes de caché, si no se han utilizado durante más de 48 horas.
2. Eliminar el caché que no se ha utilizado en una compilación durante más de 60 días.
3. Eliminar el caché no compartido que exceda el límite de tamaño del caché de compilación. Los registros de caché no compartidos se refieren a los blobs de capa que no son utilizados por otros recursos (normalmente, como capas de imágenes).
4. Eliminar cualquier caché de compilación que exceda el límite de tamaño del caché de compilación.

El algoritmo preciso y los medios para configurar las políticas difieren ligeramente según el tipo de builder que estés utilizando. Consulta la sección de Configuración para obtener más detalles.

Configuración

Note

Si estás conforme con el comportamiento predeterminado de la recolección de basura y no necesitas ajustar detalladamente sus configuraciones, puedes omitir esta sección. Las configuraciones predeterminadas funcionan bien para la mayoría de los casos de uso y no requieren configuración adicional.

Dependiendo del tipo de controlador de compilación (driver) que utilices, usarás diferentes archivos de configuración para cambiar los ajustes de GC del builder:

• Si utilizas el builder predeterminado para Docker Engine (el controlador docker), utiliza el archivo de configuración del demonio de Docker.
• Si utilizas un builder personalizado, utiliza un archivo de configuración de BuildKit.

Archivo de configuración del demonio de Docker

Si estás utilizando el controlador docker predeterminado, la GC se configura en el archivo de configuración daemon.json, o si utilizas Docker Desktop, en Settings > Docker Engine (Configuración > Motor de Docker) /manuals/desktop/settings-and-maintenance/settings.md.

El siguiente fragmento muestra la configuración predeterminada del builder para el controlador docker para los usuarios de Docker Desktop:

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

La opción defaultKeepStorage configura el límite de tamaño del caché de compilación, lo que influye en las políticas de GC. Las políticas predeterminadas para el controlador docker funcionan de la siguiente manera:

1. Eliminar el caché de compilación efímero y no utilizado con una antigüedad superior a 48 horas si supera el 13.8% de defaultKeepStorage, o como mínimo 512 MB.
2. Eliminar el caché de compilación no utilizado con una antigüedad superior a 60 días.
3. Eliminar el caché de compilación no compartido que exceda el límite de defaultKeepStorage.
4. Eliminar cualquier caché de compilación que exceda el límite de defaultKeepStorage.

Dado el valor predeterminado de Docker Desktop para defaultKeepStorage de 20 GB, las políticas de GC predeterminadas se resuelven como:

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

La forma más sencilla de ajustar la configuración del caché de compilación para el controlador docker es modificar la opción defaultKeepStorage:

• Aumenta el límite si consideras que la GC es demasiado agresiva.
• Disminuye el límite si necesitas ahorrar espacio.

Políticas de GC personalizadas en el archivo de configuración del demonio de Docker

Si necesitas aún más control, puedes definir tus propias políticas de GC directamente. El siguiente ejemplo define una configuración de GC más conservadora con las siguientes políticas:

1. Eliminar entradas de caché no utilizadas con una antigüedad superior a 1440 horas (o 60 días) si el caché de compilación supera los 50 GB.
2. Eliminar entradas de caché no compartidas si el caché de compilación supera los 50 GB.
3. Eliminar cualquier entrada de caché si el caché de compilación supera los 100 GB.

{
  "builder": {
    "gc": {
      "enabled": true,
      "policy": [
        { "reservedSpace": "50GB", "keepDuration": ["1440h"] },
        { "reservedSpace": "50GB" },
        { "reservedSpace": "100GB", "all": true }
      ]
    }
  }
}

Note

En el archivo de configuración del demonio de Docker, el operador de igualdad en los filtros de GC se denota utilizando un solo =, mientras que el archivo de configuración de BuildKit utiliza ==:

daemon.json	buildkitd.toml
type=source.local	type==source.local
private=true	private==true
shared=true	shared==true

Consulta la sección de filtros de prune para obtener información sobre los filtros de GC disponibles. La configuración de GC en daemon.json admite todos los filtros excepto mutable e immutable.

Archivo de configuración de BuildKit

Para controladores de compilación que no sean docker, la GC se configura utilizando un archivo de configuración buildkitd.toml. Este archivo utiliza las siguientes opciones de configuración de alto nivel que puedes usar para ajustar los umbrales de cuánto espacio en disco debe usar BuildKit para el caché:

Puedes establecer estas opciones como número de bytes, una cadena de unidad (por ejemplo, 512MB) o como un porcentaje del tamaño total del disco. Cambiar estas opciones influye en las políticas de GC predeterminadas utilizadas por el worker de BuildKit. Con los umbrales predeterminados, las políticas de GC se resuelven de la siguiente manera:

# Global defaults
[worker.oci]
  gc = true
  reservedSpace = "10GB"
  maxUsedSpace = "100GB"
  minFreeSpace = "20%"

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

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

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

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

En términos prácticos, esto significa:

• Política 1: Si el caché de compilación supera los 512 MB, BuildKit elimina los registros de caché para contextos de compilación locales, contextos Git remotos y montajes de caché que no se hayan utilizado en las últimas 48 horas.
• Política 2: Si el uso de disco supera los 100 GB, se elimina el caché de compilación no compartido con una antigüedad superior a 60 días, asegurando que se reserven al menos 10 GB de espacio en disco para el caché.
• Política 3: Si el uso de disco supera los 100 GB, se elimina cualquier caché no compartido, asegurando que se reserven al menos 10 GB de espacio en disco para el caché.
• Política 4: Si el uso de disco supera los 100 GB, se elimina todo el caché (incluidos los registros internos y compartidos), asegurando que se reserven al menos 10 GB de espacio en disco para el caché.

reservedSpace tiene la prioridad más alta al definir el límite inferior para el tamaño del caché de compilación. Si maxUsedSpace o minFreeSpace definieran un valor menor, el tamaño mínimo del caché nunca se reduciría por debajo de reservedSpace.

Si se configuran tanto reservedSpace como maxUsedSpace, un barrido de GC da como resultado un tamaño de caché entre esos umbrales. Por ejemplo, si reservedSpace se establece en 10 GB y maxUsedSpace se establece en 20 GB, la cantidad resultante de caché después de una ejecución de GC será inferior a 20 GB, pero al menos de 10 GB.

También puedes definir políticas de GC completamente personalizadas. Las políticas personalizadas también te permiten definir filtros, lo que te permite precisar los tipos de entradas de caché que una política determinada tiene permitido limpiar (prune).

Políticas de GC personalizadas en BuildKit

Las políticas de GC personalizadas te permiten ajustar con precisión cómo BuildKit gestiona su caché y te brindan un control total sobre la retención de caché basándose en criterios como el tipo de caché, la duración o los umbrales de espacio en disco. Si necesitas un control total sobre los umbrales del caché y cómo se deben priorizar los registros de caché, la mejor opción es definir políticas de GC personalizadas.

Para definir una política de GC personalizada, utiliza el bloque de configuración [[worker.oci.gcpolicy]] en buildkitd.toml. Cada política define los umbrales que se utilizarán para esa política. Los valores globales para reservedSpace, maxUsedSpace y minFreeSpace no se aplican si utilizas políticas personalizadas.

A continuación, se muestra una configuración de ejemplo:

# Custom GC Policy 1: Remove unused local contexts older than 24 hours
[[worker.oci.gcpolicy]]
  filters = ["type==source.local"]
  keepDuration = "24h"
  reservedSpace = "5GB"
  maxUsedSpace = "50GB"

# Custom GC Policy 2: Remove remote Git contexts older than 30 days
[[worker.oci.gcpolicy]]
  filters = ["type==source.git.checkout"]
  keepDuration = "720h"
  reservedSpace = "5GB"
  maxUsedSpace = "30GB"

# Custom GC Policy 3: Aggressively clean all cache if disk usage exceeds 90GB
[[worker.oci.gcpolicy]]
  all = true
  reservedSpace = "5GB"
  maxUsedSpace = "90GB"

Además de los umbrales reservedSpace, maxUsedSpace y minFreeSpace, al definir una política de GC tienes dos opciones de configuración adicionales:

• all: Por defecto, BuildKit excluirá algunos registros de caché para que no sean eliminados durante la GC. Establecer esta opción en true permitirá que se elimine cualquier registro de caché.
• filters: Los filtros te permiten especificar tipos específicos de registros de caché que una política de GC tiene permitido limpiar.

Consulta la sección de filtros de prune de buildx para obtener información sobre los filtros de GC disponibles.