# Invalidación del caché de compilación


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](/build/builders/) 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:

```console
$ 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`:

```dockerfile
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`](/reference/cli/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é:

```console
$ 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é.

```dockerfile
FROM alpine
ARG CACHEBUST
RUN --mount=type=secret,id=TOKEN,env=TOKEN \
    some-command ...
```

```console
$ 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.