Docker layer caching no CI: BuildKit, buildx, cache-from e cache-to

Quando um pipeline “demora”, muitas vezes o culpado é um docker build repetindo trabalho.

O objetivo deste post é você sair com um plano claro para:

• deixar seu Dockerfile cache-friendly
• reaproveitar layers entre pipelines (via registry ou runner dedicado)
• evitar armadilhas em ARM64 e x64

Este post faz parte da série:

• Guia de CI/CD no Git para times pequenos: performance, cache e runners

Mapa da série CI/CD

• Guia de CI/CD no Git para times pequenos: performance, cache e runners
• GitLab CI: tags de runner e roteamento de jobs
• Cache no CI/CD: como desenhar keys e evitar cache inválido (GitHub e GitLab)
• Docker layer caching no CI: BuildKit, buildx, cache-from e cache-to
• Runner dedicado no CI/CD: quando vale a pena e como planejar em time pequeno
• Runners macOS no CI: Intel vs Apple Silicon, custos e armadilhas

O básico que resolve 80%: ajuste o Dockerfile

O cache de layers funciona por instrução do Dockerfile.

Se você copia o repositório inteiro antes de instalar dependências, qualquer mudança invalida tudo.

Padrão recomendado:

1. Copiar manifestos/lockfiles.
2. Instalar dependências.
3. Copiar o restante do código.
4. Fazer build.

Exemplo (Node):

FROM node:20 AS build
WORKDIR /app

COPY package*.json ./
RUN npm ci

COPY . .
RUN npm run build

1) O que é “Docker layer caching” no CI (na prática)

Layer caching é reaproveitar resultados de passos anteriores do Docker build.

No CI, você só reaproveita layers de forma consistente quando:

• o runner mantém cache local (runner dedicado)
• ou você usa um cache remoto (registry cache)

2) Estratégia recomendada: cache no registry

A ideia é simples:

• --cache-to publica cache no registry
• --cache-from puxa cache do registry na próxima execução

Exemplo conceitual com BuildKit/buildx:

docker buildx build   --cache-from=type=registry,ref=registry.exemplo.com/app:buildcache   --cache-to=type=registry,ref=registry.exemplo.com/app:buildcache,mode=max   -t registry.exemplo.com/app:${GIT_SHA}   .

3) Em runners dedicados: cache local funciona muito bem

Se você tem runner dedicado (e ele não é efêmero), o daemon Docker pode manter layers localmente.

Vantagens:

• muito rápido
• simples de operar

Riscos:

• runner compartilhado com muitos projetos “enche disco”
• isolamento e segurança precisam ser considerados (principalmente com Docker-in-Docker)

4) ARM64 vs x64 em docker build

Se você constrói images para mais de uma arquitetura:

• build em emulação é mais lento
• caches não são totalmente reaproveitáveis entre arch

Boas práticas:

• separar pipelines (ou matrix) por arquitetura
• usar buildx multi-arch quando fizer sentido
• evitar misturar caches de arch

Checklist final

• Dockerfile copia manifestos antes do código.
• Dependências são instaladas em layer estável (cache reaproveita).
• Existe estratégia de cache (registry ou local).
• Arquitetura faz parte da estratégia (ARM/x64).
• Build é observável: tempo antes/depois e cache hit/miss.

Referências

• GitLab Docs: Make Docker-in-Docker builds faster with Docker layer caching