O Que É um Multi-Stage Build? Imagens Menores, Saída Mais Limpa
Um multi-stage build compila em um stage descartável e copia apenas o artifact finalizado para um stage final pequeno - então sua imagem entrega a saída, não os toolchains.
Ferramentas de build, compiladores e dependências de dev são necessárias para produzir um artifact, mas não para executá-lo. Um Dockerfile multi-stage permite usar um stage builder pesado e então iniciar um stage final novo e mínimo que contém apenas o que você entrega. O resultado é uma imagem dramaticamente menor e mais segura.
A ideia central
Você declara múltiplos stages FROM em um único Dockerfile. Os stages iniciais fazem o trabalho pesado; o stage final começa limpo e usa COPY --from=<stage> para puxar apenas a saída compilada. Tudo o que ficou para trás nos stages iniciais é descartado.
Um exemplo em Go
Stage um:
FROM golang:1.22 AS build
WORKDIR /src
COPY . .
RUN go build -o app .
Stage dois:
FROM gcr.io/distroless/static
COPY --from=build /src/app /app
ENTRYPOINT ["/app"]
A imagem final tem o binário e nada mais.
Por que encolhe tanto as imagens
A imagem do toolchain do Go tem centenas de megabytes; a imagem distroless final tem poucos. Como apenas o artifact do COPY --from chega no stage final, todo aquele peso de build nunca é entregue.
Outros ganhos
- Menos pacotes significa menos vulnerabilidades na imagem em execução.
- Secrets usados durante o build podem ficar no stage builder.
- Você pode ter como alvo múltiplos stages finais (ex.: test vs prod) a partir de um único arquivo.
Multi-stage builds em CI
Multi-stage builds cacheiam cada stage, então passos de builder inalterados são pulados. Em runners gerenciados com caches aquecidos, o custoso stage de compilação é reaproveitado entre jobs, e apenas a cópia final re-executa.
Principais conclusões
- Multi-stage builds mantêm as ferramentas de build fora da imagem final.
- COPY --from puxa apenas o artifact finalizado para um stage final limpo.
- O resultado são imagens muito menores e mais seguras, sem o peso do toolchain.