Docker
Invalidación, orden de capas, cache mounts y builds reproducibles.
La cache de build no es una copia opaca de una imagen anterior. BuildKit representa la construcción como un grafo de operaciones y reutiliza resultados cuando los inputs relevantes de una operación coinciden con un resultado disponible.
Dockerfile + context + args + mounts + base images
→ grafo de operaciones
→ claves de cache
→ resultados reutilizados o ejecutados
→ image finalLa cache debe mejorar velocidad sin cambiar la corrección. Un build limpio y uno con cache deberían producir un artefacto funcional equivalente para los mismos inputs permitidos.
Construir una aplicación puede incluir operaciones costosas:
Repetir todo ante cualquier cambio hace lentos CI, desarrollo y releases. La cache intenta reutilizar únicamente la parte del grafo cuyos inputs no cambiaron.
El reto no consiste en “activar cache”; consiste en diseñar instrucciones con fronteras de inputs correctas.
Considera:
FROM node:22-slim
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY src ./src
RUN npm run buildDependencias conceptuales:
base image
↓
WORKDIR
↓
lockfiles ─→ npm ci
↓
source ─────────→ compileSi cambia src/app.ts:
npm ci puede reutilizarse;COPY src cambia;Si cambia package-lock.json:
COPY;npm ci;Una invalidación no “borra toda la cache”. Hace que una ruta concreta deje de coincidir.
BuildKit es el builder moderno utilizado por Docker para ejecutar construcciones. Entre sus capacidades se encuentran:
La directiva:
# syntax=docker/dockerfile:1indica el frontend Dockerfile que interpreta la sintaxis. Fijar una variante puede ayudar a controlar capacidades; usar un frontend móvil puede introducir cambios. La política depende del entorno y debe probarse.
No existe una regla única resumida en “Docker compara la línea”. Según la operación, pueden influir:
Para RUN, BuildKit no puede saber automáticamente que una URL externa o un repository de paquetes cambió si los inputs declarados permanecen iguales.
RUN apt-get update && apt-get install -y curlLa red puede ofrecer paquetes nuevos, pero un resultado cacheado puede reutilizarse. La cache refleja inputs conocidos, no el estado completo de internet.
La recomendación “de lo estable a lo cambiante” significa colocar operaciones costosas detrás del conjunto mínimo de inputs que realmente necesitan.
COPY . .
RUN npm ci
RUN npm run buildTodo archivo del context consumido por COPY . . puede invalidar dependencias.
COPY package.json package-lock.json ./
RUN npm ci
COPY tsconfig.json ./
COPY src ./src
RUN npm run buildCada operación declara inputs más precisos.
No fragmentes por dogma. Cientos de instrucciones pequeñas pueden volver difícil leer y mantener el Dockerfile. El objetivo es alinear fronteras de cache con fronteras reales de cambio.
Estas dos ideas suelen confundirse.
Si RUN npm ci coincide, BuildKit puede reutilizar el resultado completo y no ejecutar npm.
RUN --mount=type=cache,target=/root/.npm \
npm ciSi el paso debe ejecutarse porque cambió el lockfile, el cache mount conserva descargas reutilizables. npm todavía valida e instala según el lockfile.
operation cache hit
→ no ejecutar npm
operation cache miss + cache mount
→ ejecutar npm
→ reutilizar tarballs disponiblesEl cache mount no se incorpora automáticamente a la imagen final. Es almacenamiento auxiliar del builder.
RUN --mount=type=cache,target=/root/.npm,sharing=locked \
npm ciEl target debe coincidir con el cache utilizado por npm y el usuario de ese paso.
RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
--mount=type=cache,target=/var/lib/apt,sharing=locked \
apt-get update \
&& apt-get install -y --no-install-recommends curlLa estrategia exacta depende del package manager y base. Algunos limpian caches automáticamente o esperan locking específico.
Según el workload, un cache puede ser:
Una cache concurrente mal diseñada puede corromper índices o producir contención.
Una cache puede:
El build debe seguir siendo correcto con cache vacía. Por ejemplo, este patrón es incorrecto si espera que un archivo exista solo en el cache mount:
RUN --mount=type=cache,target=/cache cp /cache/app.bin /app/app.binSi /cache/app.bin no se genera o descarga cuando falta, el build depende de estado oculto.
La cache acelera inputs legítimos; no debe reemplazarlos.
Runners efímeros pierden cache local al terminar. BuildKit puede importar y exportar cache mediante backends compatibles.
Flujo:
pipeline anterior
→ exporta metadata y resultados de cache
→ registry o almacenamiento
pipeline nuevo
→ importa cache
→ resuelve coincidencias
→ ejecuta solo misses
→ exporta cache actualizadaUna estrategia debe decidir:
No permitas que una pull request no confiable publique libremente la cache consumida por releases con secretos o permisos elevados.
Los valores de secret mounts no deberían persistirse en la cache como contenido de layers. Sin embargo, el resultado del comando puede quedar cacheado según sus inputs y comportamiento.
RUN --mount=type=secret,id=npmrc,target=/root/.npmrc npm ciCambiar el valor del secreto no necesariamente invalida el paso por sí solo. Si el secreto cambia qué dependencias puede descargar, puede necesitarse un input de invalidación no sensible, por ejemplo una versión de credencial o argumento de cache bust controlado.
Nunca escribas el secreto en el resultado para forzar invalidación.
ARG CACHE_BUST=1
RUN echo "$CACHE_BUST" >/dev/null && some-commandPuede forzar invalidación, pero debe usarse de forma específica. Cambiarlo en cada build destruye el valor de cache y puede ocultar una dependencia mal declarada.
docker build --no-cache .Evita reutilizar cache de instrucciones para esa construcción. Es útil para:
No es la solución permanente para un Dockerfile que produce resultados incorrectos con cache.
--no-cache no significa necesariamente actualizar todas las bases por sí solo. Utiliza la política de pull correspondiente:
docker build --pull --no-cache .Aun así, para reproducibilidad y auditoría registra el digest resuelto.
Existe una tensión:
Una política madura puede:
No dependas de builds aleatorios para descubrir actualizaciones.
En un multi-stage build, BuildKit puede omitir etapas que no participan en el target solicitado.
FROM base AS lint
RUN npm run lint
FROM base AS test
RUN npm test
FROM base AS build
RUN npm run build
FROM runtime
COPY --from=build /app/dist ./distAl construir el target final, una etapa independiente de lint puede no ejecutarse si no forma parte del grafo. Si CI exige lint y tests, debe solicitarlos como targets o conectarlos explícitamente al workflow. No asumas que aparecer en el Dockerfile garantiza ejecución.
# syntax=docker/dockerfile:1
FROM node:22-slim AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm,sharing=locked \
npm ci
FROM deps AS build
COPY tsconfig.json ./
COPY src ./src
RUN npm run build
FROM node:22-slim AS runtime-deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm,sharing=locked \
npm ci --omit=dev
FROM node:22-slim AS runtime
ENV NODE_ENV=production
WORKDIR /app
COPY --from=runtime-deps /app/node_modules ./node_modules
COPY --from=build /app/dist ./dist
USER node
CMD ["node", "dist/server.js"]deps puede reutilizarse;build copia source y recompila;runtime-deps se reutiliza;dist.Construye con salida legible:
docker build --progress=plain -t my-api:test .Busca:
CACHED;Para depurar un paso:
La instrucción no cambia, por lo que la cache puede ocultar una actualización. Fija versión o modela invalidación explícita.
Generar build-time=$(date) invalida reproducibilidad y puede hacer que cada build cambie aunque el source sea igual.
Binarios nativos para amd64 no deben reutilizarse como si fueran arm64. Incluye plataforma en la frontera o usa caches separadas cuando la herramienta no lo hace correctamente.
Puede introducir resultados o dependencias no autorizadas. Separa scopes y permisos.
Necesita garbage collection y capacidad. Un builder puede quedarse sin disco aun cuando las imágenes finales sean pequeñas.
Puede existir una carrera, cache incompleta o comando que genera y consume estado en orden incorrecto. Un build debe funcionar desde estado limpio.
Consecuencia: cada cambio invalida una operación costosa.
Corrección: separar manifestos, source y outputs.
Consecuencia: CI lento y problema de inputs sin resolver.
Corrección: entender invalidación y reservar builds limpios para validación.
Consecuencia: fallos cuando cambia el builder o se ejecuta limpieza.
Corrección: regenerar todo contenido necesario si falta.
Consecuencia: riesgo de cache poisoning o mezcla de permisos.
Corrección: scopes separados y writers controlados.
Consecuencia: un build parece estable solo porque evita fuentes externas mutables.
Corrección: fijar inputs y probar desde limpio.
Consecuencia: Dockerfile complejo con poca mejora.
Corrección: registrar tiempos por paso, transferencia y hit rate.
Ejecuta builds después de modificar:
Predice antes qué pasos deberían invalidarse y compara con la salida.
docker build --pull --no-cache --progress=plain -t my-api:clean .Compáralo funcionalmente con el build cacheado mediante tests y metadata esperada.
docker buildx du
docker system df -vLos comandos disponibles dependen del builder y versión. Úsalos para localizar cache grande antes de podar.
docker builder pruneRevisa alcance y contexto. Borrar cache puede afectar otros proyectos, pero no debe destruir la capacidad de reconstruir.
--no-cache sirve para verificar, no para ocultar un Dockerfile mal diseñado.RUN npm ci y usar un cache mount de npm.--pull, --no-cache o ambos?Multi-stage builds, donde el grafo se utiliza para separar compilación, pruebas y runtime sin publicar herramientas ni archivos innecesarios.