Dominando o Cache de Camadas do Dockerfile para Builds de Contêineres Ultrarrápidos

O cache de camadas do Dockerfile é a diferença entre um build que termina enquanto você ainda está pensando na mudança e um build que faz cada commit parecer caro. O cache não é complicado, mas é implacável: copie os arquivos errados muito cedo, e o Docker não terá escolha a não ser reexecutar etapas lentas.

O hábito principal é simples. Coloque trabalho estável no início, coloque trabalho que muda com frequência no final e mantenha o contexto do build limpo. Depois de entender isso, a maioria dos problemas de desempenho do Dockerfile se torna visível na saída do build.

Entendendo o Cache de Camadas do Docker

O Docker constrói imagens de contêiner em camadas. Cada instrução no seu Dockerfile (como RUN, COPY, ADD) cria uma nova camada. Quando você constrói uma imagem, o Docker verifica se já executou aquela instrução específica com o mesmo contexto (por exemplo, os mesmos arquivos para COPY) em um build anterior. Se ocorrer um acerto de cache, o Docker reutiliza a camada existente do seu cache em vez de executar a instrução novamente. Isso pode economizar um tempo considerável, especialmente para operações computacionalmente caras ou ao copiar arquivos grandes.

Conceitos-chave:

Camada: Um snapshot imutável do sistema de arquivos criado por uma instrução do Dockerfile.
Acerto de Cache: Quando o Docker encontra uma camada idêntica em seu cache para uma determinada instrução.
Falta de Cache: Quando o Docker não encontra uma camada correspondente e deve executar a instrução, invalidando o cache para todas as instruções subsequentes.

Como o Cache do Docker Funciona: A Mecânica

O Docker determina acertos de cache com base na própria instrução e em quaisquer arquivos envolvidos. Para instruções como RUN echo 'olá', a string da instrução é a chave primária do cache. Para instruções como COPY ou ADD, o Docker não apenas considera a instrução, mas também calcula uma soma de verificação dos arquivos que estão sendo copiados. Se a instrução ou a soma de verificação dos arquivos mudar, resulta em uma falta de cache.

Isso significa que qualquer alteração em uma instrução do Dockerfile ou nos arquivos associados invalidará o cache para essa instrução e todas as instruções subsequentes. Este é um ponto crucial para a otimização.

Otimizando Dockerfiles para Utilização Máxima do Cache

A arte de aproveitar o cache de build do Docker está em estruturar seu Dockerfile para minimizar a invalidação do cache, especialmente para instruções que mudam com frequência. O princípio geral é colocar instruções com menor probabilidade de mudança no início do Dockerfile e aquelas que mudam com mais frequência no final.

1. Ordene Suas Instruções Estrategicamente

A Regra de Ouro: Coloque instruções estáveis primeiro.

Considere um Dockerfile típico de aplicação web. Você pode ter etapas para instalar dependências, copiar o código da aplicação e, em seguida, executar um build ou iniciar um servidor.

Exemplo Ineficiente (Invalidação de Cache):

FROM ubuntu:latest

# Instala pacotes do sistema (muda raramente)
RUN apt-get update && apt-get install -y --no-install-recommends \
    python3 \
    python3-pip \
    && rm -rf /var/lib/apt/lists/*

# Copia o código da aplicação (muda MUITO frequentemente)
COPY . .

# Instala dependências Python (muda frequentemente)
RUN pip install --no-cache-dir -r requirements.txt

# ... outras instruções

Neste exemplo, toda vez que você altera uma única linha do código da aplicação (porque COPY . . é executado), o cache para COPY . . e todas as instruções subsequentes (RUN pip install ...) serão invalidadas. Isso significa que pip install será executado novamente mesmo se requirements.txt não tiver mudado, levando a tempos de build mais longos.

Exemplo Otimizado (Maximizando o Cache):

FROM ubuntu:latest

# Instala pacotes do sistema (muda raramente)
RUN apt-get update && apt-get install -y --no-install-recommends \
    python3 \
    python3-pip \
    && rm -rf /var/lib/apt/lists/*

# Copia APENAS os arquivos de dependência primeiro (muda com menos frequência)
COPY requirements.txt .

# Instala dependências Python (armazena em cache se requirements.txt não mudou)
RUN pip install --no-cache-dir -r requirements.txt

# Copia o resto do código da aplicação (muda MUITO frequentemente)
COPY . .

# ... outras instruções

Ao copiar requirements.txt primeiro e executar pip install imediatamente depois, o Docker pode armazenar em cache a camada de instalação de dependências. Se apenas o código da aplicação mudar (e requirements.txt permanecer o mesmo), a etapa pip install será armazenada em cache, acelerando significativamente o build.

2. Aproveite Builds Multi-Estágio

Builds multi-estágio são uma técnica poderosa para reduzir o tamanho da imagem, mas também beneficiam indiretamente os tempos de build ao manter ambientes de build intermediários separados. Cada estágio pode ter suas próprias camadas em cache.

# Estágio 1: Construtor
FROM golang:1.20 AS builder
WORKDIR /app
COPY go.mod ./ 
COPY go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -o myapp

# Estágio 2: Imagem final
FROM alpine:latest
WORKDIR /root/
COPY --from=builder /app/myapp .
CMD ["./myapp"]

Neste cenário, se apenas o código fonte da aplicação mudar (mas go.mod e go.sum não), a etapa go mod download no estágio construtor será armazenada em cache. Mesmo que o estágio construtor precise reexecutar a compilação, o estágio final ainda será baseado na imagem alpine:latest, que provavelmente está em cache, e apenas a instrução COPY --from=builder será reexecutada se o artefato myapp tiver mudado.

3. Use `ADD` e `COPY` com Sabedoria

COPY é geralmente preferido para copiar arquivos locais para a imagem. É direto e previsível.
ADD tem mais recursos, como a capacidade de extrair tarballs e buscar URLs remotas. No entanto, esses recursos extras podem, às vezes, levar a comportamentos inesperados e podem afetar a invalidação do cache de forma diferente. Use COPY a menos que você precise explicitamente dos recursos avançados de ADD.

Ao usar COPY, seja granular. Em vez de COPY . ., considere copiar diretórios ou arquivos específicos que mudam em taxas diferentes, como mostrado no exemplo otimizado acima.

4. Limpe na Mesma Instrução `RUN`

Para evitar inchaço do cache e reduzir o tamanho da imagem, sempre limpe os artefatos (como caches do gerenciador de pacotes) dentro da mesma instrução RUN em que foram criados.

Má Prática:

RUN apt-get update && apt-get install -y some-package
RUN rm -rf /var/lib/apt/lists/*

Aqui, o comando rm é uma instrução RUN separada. Se some-package foi atualizado (causando uma falta de cache para o primeiro RUN), o segundo RUN ainda seria executado, mesmo que a limpeza não fosse estritamente necessária para a nova camada. Mais importante, a camada de cache intermediária criada pelo primeiro RUN ainda pode conter as listas de pacotes baixadas antes de serem limpas pelo segundo RUN.

Boa Prática:

RUN apt-get update && apt-get install -y some-package && rm -rf /var/lib/apt/lists/*

Isso garante que quaisquer arquivos temporários criados durante a instalação do pacote sejam removidos imediatamente, e a camada de cache criada representa um estado do sistema de arquivos mais limpo.

5. Evite Instalar Dependências Toda Vez

Como demonstrado, copiar arquivos de definição de dependências (requirements.txt, package.json, Gemfile, etc.) e instalar dependências antes de copiar o código fonte da sua aplicação é uma otimização fundamental de cache.

6. Quebra de Cache (Quando Necessário)

Embora o objetivo seja maximizar o cache, às vezes você quer forçar uma reconstrução do cache. Isso é conhecido como quebra de cache. Técnicas comuns incluem:

Alterar um comentário: Comentários do Dockerfile (#) são ignorados, então isso não funcionará.
Adicionar um argumento fictício: Você pode usar ARG para introduzir uma variável que você altera para quebrar o cache.
```
ARG CACHEBUST=1
RUN echo "Quebra de cache: ${CACHEBUST}" # Esta instrução será reexecutada se CACHEBUST mudar
```
Você então construiria com docker build --build-arg CACHEBUST=$(date +%s) .
Modificar um comando RUN anterior: Se você alterar um comando que está no início do Dockerfile, ele quebrará o cache para todas as instruções subsequentes.

A quebra de cache deve ser usada com moderação, tipicamente quando você precisa garantir um download novo de recursos externos ou um build limpo de algo que não é bem tratado pelo mecanismo de cache padrão.

Docker BuildKit e Cache Aprimorado

Versões recentes do Docker introduziram o BuildKit como o mecanismo de builder padrão. O BuildKit oferece melhorias significativas no cache, incluindo:

Cache Remoto: A capacidade de compartilhar o cache de build entre diferentes máquinas e runners de CI/CD.
Cache mais granular: Melhor identificação do que mudou.
Execução paralela de build: Acelera os builds mesmo sem acertos de cache.

O BuildKit geralmente está habilitado por padrão e frequentemente oferece melhor cache pronto para uso. No entanto, entender os princípios descritos acima ainda permitirá que você otimize seus Dockerfiles também para o BuildKit.

Dicas para um Cache Eficaz do Dockerfile

Mantenha os Dockerfiles limpos e organizados: A legibilidade ajuda a identificar oportunidades de otimização.
Teste seu cache: Após fazer alterações, observe a saída do seu build Docker. Procure por tags [internal] ou CACHED para confirmar acertos de cache.
Use .dockerignore: Evite que arquivos desnecessários (como node_modules, .git, artefatos de build) sejam copiados para o contexto do build, o que pode acelerar as instruções COPY e reduzir a chance de invalidação não intencional do cache.
Pode seu cache Docker regularmente: Com o tempo, seu cache pode crescer muito. Use docker builder prune para remover camadas de cache de build não utilizadas.

Um Exemplo Real com Node.js

O problema de cache é mais fácil de ver em um projeto Node.js. Este Dockerfile funciona, mas perde tempo:

FROM node:22-slim
WORKDIR /app
COPY . .
RUN npm ci
RUN npm run build
CMD ["npm", "start"]

Cada alteração no código fonte invalida COPY . ., o que significa que npm ci é executado novamente. Uma versão melhor separa os metadados de dependência do código da aplicação:

FROM node:22-slim
WORKDIR /app

COPY package.json package-lock.json ./
RUN npm ci

COPY . .
RUN npm run build

CMD ["npm", "start"]

Agora, uma alteração em src/routes/account.ts não invalida a camada de instalação de dependências. Uma alteração em package-lock.json ainda invalida, que é exatamente o que você deseja.

Para imagens de produção, combine isso com um build multi-estágio:

FROM node:22-slim AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci

FROM node:22-slim AS build
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build

FROM node:22-slim AS runtime
WORKDIR /app
ENV NODE_ENV=production
COPY package.json package-lock.json ./
RUN npm ci --omit=dev
COPY --from=build /app/dist ./dist
CMD ["node", "dist/server.js"]

Isso é mais longo, mas separa três preocupações: download de dependências, build da aplicação e conteúdo do runtime. Runners de CI podem armazenar em cache as partes caras, e a imagem final não precisa de toda a árvore de código fonte ou dependências de desenvolvimento.

Use `.dockerignore` como Parte da Estratégia de Cache

O cache de camadas não é apenas sobre a ordem das instruções do Dockerfile. O contexto do build também importa. Se você enviar .git, saída de teste local, capturas de tela, relatórios de cobertura ou node_modules para o contexto do build, o Docker terá mais arquivos para verificar e mais chances de invalidar um COPY.

Um .dockerignore típico para uma aplicação pode incluir:

.git
node_modules
dist
coverage
.env
*.log
tmp
.DS_Store

Tenha cuidado com .env. Você geralmente quer excluí-lo da imagem por segurança e reprodutibilidade. A configuração de runtime deve ser passada quando o contêiner inicia, não incorporada no build, a menos que seja uma configuração de build-time verdadeiramente não sensível.

Saiba Quando o Cache Está Mentindo para Você

O cache pode esconder erros. O exemplo comum são comandos de gerenciadores de pacotes que dependem de repositórios externos. Se você escrever:

RUN apt-get update
RUN apt-get install -y curl

a camada em cache apt-get update pode se tornar obsoleta enquanto a etapa de instalação posterior espera metadados de pacotes atuais. Mantenha update e install juntos:

RUN apt-get update \
  && apt-get install -y --no-install-recommends curl \
  && rm -rf /var/lib/apt/lists/*

A mesma ideia se aplica a dependências de linguagem. Arquivos de lock tornam os builds mais reproduzíveis e ajudam o cache a se comportar de forma previsível. Use package-lock.json, pnpm-lock.yaml, poetry.lock, Gemfile.lock, go.sum, ou o equivalente para sua stack. Se o seu Dockerfile instala versões flutuantes de dependências da rede, os acertos de cache podem ser rápidos, mas as reconstruções podem surpreendê-lo mais tarde.

Cache Mounts do BuildKit para Gerenciadores de Pacotes

O BuildKit suporta cache mounts que aceleram os gerenciadores de pacotes sem colocar seus caches na camada final da imagem. Por exemplo, npm:

# syntax=docker/dockerfile:1.7
FROM node:22-slim
WORKDIR /app
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm npm ci
COPY . .
RUN npm run build

Para Python:

# syntax=docker/dockerfile:1.7
FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN --mount=type=cache,target=/root/.cache/pip \
  pip install --no-cache-dir -r requirements.txt
COPY . .

Se isso ajuda depende da sua configuração de CI. Um runner de curta duração sem cache remoto ainda começará frio. Um runner que preserva o cache do BuildKit entre jobs pode economizar muito tempo.

Cache Remoto em CI

Cache local é fácil; cache em CI precisa de configuração deliberada. Com docker buildx, você pode enviar e puxar metadados de cache de um registro:

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

Isso permite que um novo runner reutilize camadas construídas por um runner anterior. É especialmente útil para instalação de dependências e grandes etapas de compilação. Mantenha os controles de acesso em mente: o cache de build pode conter snapshots do sistema de arquivos de estágios intermediários, então trate o cache do registro privado como parte da sua infraestrutura de build, não como espaço público de rascunho.

Depure um Build Docker Lento

Quando um build está inesperadamente lento, leia a saída em vez de adivinhar. O BuildKit imprime quais etapas estão em cache e quais são executadas. Se uma etapa de instalação de dependências não está em cache, olhe para a linha COPY ou RUN anterior. Algo antes dela mudou.

Verificações úteis:

docker build --progress=plain .
docker buildx du
docker builder prune --filter until=24h

Não pode cegamente em um host de build compartilhado se outros jobs dependem do cache. Podar é útil quando o uso do disco está alto, mas pode tornar o próximo build mais lento.

A Lista de Verificação Prática de Revisão

Ao revisar um Dockerfile para builds mais rápidos, vá de cima para baixo e pergunte:

As etapas de configuração base estáveis estão antes dos arquivos fonte que mudam com frequência?
Os manifestos de dependências são copiados antes da aplicação completa?
O .dockerignore está excluindo ruídos locais e segredos?
Os caches do gerenciador de pacotes são tratados na mesma camada ou com cache mounts do BuildKit?
A imagem final contém apenas o que precisa para executar?
O CI usa um cache remoto se os runners são descartáveis?

Builds Docker rápidos são geralmente o resultado de muitas pequenas escolhas simples. Coloque o trabalho lento e estável no início. Coloque o trabalho que muda com frequência no final. Mantenha o contexto do build limpo. Em seguida, verifique com a saída do build em vez de assumir que o cache está sendo usado.