Builds Docker Multi-Stage para Go

Dockerfiles multi-stage compilam Go em uma imagem SDK completa, depois copiam apenas o binário (e as raízes de confiança necessárias) para um estágio de runtime mínimo.

O resultado são imagens pequenas e de download rápido, com menos pacotes de SO para aplicar patches.

Resumo

Binários estáticos do Go combinam naturalmente com runtimes distroless ou scratch.

Um pipeline típico usa um estágio de build golang, emite saída CGO_ENABLED=0 e copia o executável para gcr.io/distroless/static ou uma imagem scratch personalizada com certificados CA.

Clientes HTTPS precisam do pacote de certificados do sistema, a menos que você incorpore as raízes de outra forma.

Montagens de cache BuildKit para go mod download encurtam o tempo de CI sem inchar as camadas.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

# syntax=docker/dockerfile:1
FROM golang:1.26-bookworm AS build
WORKDIR /src
COPY go.mod go.sum ./
RUN --mount=type=cache,target=/go/pkg/mod \
    go mod download
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -trimpath \
    -ldflags="-s -w" -o /out/api ./cmd/api
 
FROM gcr.io/distroless/static-debian12:nonroot
COPY --from=build /out/api /api
USER nonroot:nonroot
EXPOSE 8080
ENTRYPOINT ["/api"]

Quando usar isso:

• Envio de microsserviços onde o tempo de pull da imagem afeta o scale-out do HPA.
• Redução da superfície de CVE evitando shells e gerenciadores de pacotes em imagens de produção.
• Criação de artefatos reproduzíveis em CI com digests de imagem base fixados.

Exemplo de Trabalho

Dockerfile orientado para produção com certificados CA para TLS de saída:

# syntax=docker/dockerfile:1
FROM golang:1.26-bookworm AS build
WORKDIR /src
COPY go.mod go.sum ./
RUN --mount=type=cache,target=/go/pkg/mod \
    go mod download
COPY . .
ARG VERSION=dev
ARG COMMIT=none
RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath \
    -ldflags="-s -w -X main.version=${VERSION} -X main.commit=${COMMIT}" \
    -o /out/api ./cmd/api
 
FROM debian:bookworm-slim AS certs
RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates \
    && update-ca-certificates
 
FROM gcr.io/distroless/base-debian12:nonroot
COPY --from=build /out/api /api
COPY --from=certs /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
USER nonroot:nonroot
EXPOSE 8080
ENTRYPOINT ["/api"]

docker build \
  --build-arg VERSION=1.0.0 \
  --build-arg COMMIT=$(git rev-parse --short HEAD) \
  -t myorg/api:1.0.0 .

O que isso demonstra:

• Montagem de cache BuildKit acelera downloads repetidos de go mod em CI.
• Um estágio certs dedicado copia apenas ca-certificates.crt para distroless.
• O usuário nonroot evita rodar como UID 0 dentro do contêiner.
• Argumentos de build injetam metadados de versão sem editar o código-fonte antes da compilação.

Análise Profunda

Como Funciona

• Isolamento de estágio: apenas artefatos que você COPY --from= aparecem no histórico da imagem final.
• Linking estático: CGO_ENABLED=0 evita requisitos do carregador dinâmico glibc em Linux amd64/arm64.
• Bases Distroless: imagens mantidas pelo Google com libc e certificados, mas sem shell ou apt.
• Variante Scratch: sistema de arquivos vazio mais seu binário; você deve adicionar o arquivo CA manualmente para HTTPS.

Escolhas de Imagem Base

Notas do Go

# Verifique se o binário é estático antes de escolher scratch
CGO_ENABLED=0 go build -o api ./cmd/api
file api   # espere "statically linked"
ldd api    # espere "not a dynamic executable" no Linux

• Alpine baseado em Musl pode quebrar algumas compilações CGO_ENABLED=1; prefira construtores debian bookworm para cgo.
• -trimpath remove $PWD de binários para auditorias de cadeia de suprimentos.
• Use GOAMD64=v3 apenas quando você controlar a linha de base da CPU e quiser instruções SIMD mais recentes.

BuildKit e CI

RUN --mount=type=cache,target=/root/.cache/go-build \
    CGO_ENABLED=0 go build -o /out/api ./cmd/api

• Montagens de cache não são camadas; elas persistem entre execuções de CI no mesmo construtor.
• Fixe imagens base por digest em pipelines de produção: golang:1.26-bookworm@sha256:....
• Execute docker scout cves ou seu scanner no estágio final, não no construtor.

Armadilhas

• HTTPS sem certificados: imagens distroless/static falham em handshakes TLS até que você copie ca-certificates.crt.
• Surpresas do CGO: importar pacotes que usam cgo habilita silenciosamente o linking dinâmico, a menos que você defina CGO_ENABLED=0.
• Dados de fuso horário: imagens scratch não têm /usr/share/zoneinfo; defina TZ ou copie zoneinfo se os logs precisarem de hora local.
• Depuração: sem shell kubectl exec em distroless; confie em logs, métricas e pods de depuração efêmeros com ferramentas.
• Diretiva USER: certifique-se de que o binário escuta em portas >= 1024 ou conceda CAP_NET_BIND_SERVICE deliberadamente.

Alternativas

• ko / buildpacks: construa e envie imagens sem manter um Dockerfile; bom para plataformas padronizadas.
• Bazel rules_oci: builds herméticos para monorepos já no Bazel.
• Imagem única "gorda": aceitável para clusters de desenvolvimento; evite para registros de produção.
• Binário puro em VM: pule o Docker inteiramente quando a orquestração for systemd e as imagens forem desnecessárias.

FAQs

Relacionados

• Deploying Go: Single Binary as a Superpower - por que binários estáticos importam
• Deployment Basics - primeiro Dockerfile e kubectl apply
• Kubernetes Deployments, Services & Ingress - executando imagens mínimas em clusters
• CI/CD Pipelines for Go Services - construir e enviar em pipeline
• Deployment Best Practices - tags imutáveis e assinatura de imagem

Versões de Stack: Esta página foi escrita para Go 1.26.x (Green Tea GC padrão, go fix modernizers - verifique o patch na compilação), chi (latest - verifique na compilação), gin (latest - verifique na compilação), echo (latest - verifique na compilação), google.golang.org/grpc (latest - verifique na compilação), sigs.k8s.io/controller-runtime (latest - verifique na compilação), kubebuilder (latest - verifique na compilação), tinygo (latest - verifique os alvos de placa na compilação), wazero (latest - verifique na compilação) e golangci-lint (latest - verifique o conjunto de linters na compilação).