Compartir comentarios
Las respuestas se generan en base a la documentación.

Invalidación del caché de compilación

Tabla de contenidos

Al compilar una imagen, Docker recorre las instrucciones de tu Dockerfile y ejecuta cada una de ellas en el orden especificado. Para cada instrucción, el builder comprueba si puede reutilizar la instrucción a partir del caché de compilación.

Reglas generales

Las reglas básicas para la invalidación del caché de compilación son las siguientes:

  • El builder comienza comprobando si la imagen base ya está almacenada en caché. Cada instrucción posterior se compara con las capas almacenadas en caché. Si ninguna capa almacenada en caché coincide exactamente con la instrucción, el caché se invalida.

  • En la mayoría de los casos, comparar la instrucción del Dockerfile con la correspondiente capa almacenada en caché es suficiente. Sin embargo, algunas instrucciones requieren comprobaciones y explicaciones adicionales.

  • Para las instrucciones ADD y COPY, y para las instrucciones RUN con montajes bind (RUN --mount=type=bind), el builder calcula una suma de verificación (checksum) del caché a partir de los metadatos del archivo para determinar si el caché es válido. Durante la búsqueda en el caché, este se invalida si los metadatos del archivo han cambiado para cualquiera de los archivos involucrados.

    El tiempo de modificación de un archivo (mtime) no se tiene en cuenta al calcular la suma de verificación del caché. Si solo ha cambiado el mtime de los archivos copiados, el caché no se invalida.

  • Aparte de los comandos ADD y COPY, la comprobación de caché no analiza los archivos en el contenedor para determinar una coincidencia de caché. Por ejemplo, al procesar un comando RUN apt-get -y update, no se examinan los archivos actualizados en el contenedor para determinar si existe un acierto (hit) de caché. En ese caso, solo se utiliza la propia cadena del comando para encontrar una coincidencia.

Una vez que el caché se invalida, todos los comandos posteriores del Dockerfile generan nuevas imágenes y el caché deja de utilizarse.

Si tu compilación contiene varias capas y deseas asegurarte de que el caché de compilación sea reutilizable, ordena las instrucciones de las que cambian con menos frecuencia a las que cambian con más frecuencia siempre que sea posible.

WORKDIR y SOURCE_DATE_EPOCH

La instrucción WORKDIR respeta el argumento de compilación SOURCE_DATE_EPOCH al determinar la validez del caché. Cambiar SOURCE_DATE_EPOCH entre compilaciones invalida el caché para WORKDIR y todas las instrucciones posteriores.

SOURCE_DATE_EPOCH establece marcas de tiempo para los archivos creados durante la compilación. Si estableces esto en un valor dinámico como una marca de tiempo de commit de Git, el caché se romperá con cada commit. Este es el comportamiento esperado al realizar el seguimiento de la procedencia de la compilación.

Para obtener compilaciones reproducibles sin invalidaciones frecuentes de caché, utiliza una marca de tiempo fija:

$ docker build --build-arg SOURCE_DATE_EPOCH=0 .

Instrucciones RUN

El caché para las instrucciones RUN no se invalida automáticamente entre compilaciones. Supongamos que tienes un paso en tu Dockerfile para instalar curl:

FROM alpine:3.23 AS install
RUN apk add curl

Esto no significa que la versión de curl en tu imagen esté siempre actualizada. Volver a compilar la imagen una semana después seguirá obteniendo los mismos paquetes que antes. Para forzar una nueva ejecución de la instrucción RUN, puedes:

  • Asegurarte de que una capa anterior haya cambiado
  • Limpiar el caché de compilación antes de la compilación utilizando docker builder prune
  • Utilizar las opciones --no-cache o --no-cache-filter

La opción --no-cache-filter te permite especificar una etapa de compilación específica para la cual invalidar el caché:

$ docker build --no-cache-filter install .

Secretos de compilación

El contenido de los secretos de compilación no forma parte del caché de compilación. Cambiar el valor de un secreto no da como resultado la invalidación del caché.

Si deseas forzar la invalidación del caché después de cambiar el valor de un secreto, puedes pasar un argumento de compilación con un valor arbitrario que también cambies al cambiar el secreto. Los argumentos de compilación sí dan como resultado la invalidación del caché.

FROM alpine
ARG CACHEBUST
RUN --mount=type=secret,id=TOKEN,env=TOKEN \
    some-command ...
$ TOKEN="tkn_pat123456" docker build --secret id=TOKEN --build-arg CACHEBUST=1 .

Las propiedades de los secretos, como los IDs y las rutas de montaje, sí participan en la suma de verificación del caché, y dan como resultado la invalidación del caché si cambian.