Compilaciones Docker Multi-Etapa para Go

Los Dockerfiles multi-etapa compilan Go en una imagen SDK completa, luego copian solo el binario (y las raíces de confianza necesarias) en una etapa de tiempo de ejecución mínima.

El resultado son imágenes pequeñas que se descargan rápidamente y con menos paquetes del sistema para parchear.

Resumen

Los binarios estáticos de Go se combinan de forma natural con tiempos de ejecución distroless o scratch.

Una canalización típica utiliza una etapa de compilación golang, emite salida CGO_ENABLED=0 y copia el ejecutable en gcr.io/distroless/static o una imagen scratch personalizada con certificados CA.

Los clientes HTTPS necesitan el paquete de certificados del sistema a menos que incrustes las raíces de otra manera.

Las monturas de caché de BuildKit para go mod download reducen el tiempo de CI sin hinchar las capas.

Receta

Tarjeta de receta de referencia rápida, lista para copiar y pegar.

# 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"]

Cuándo usar esto:

• Para enviar microservicios donde el tiempo de descarga de la imagen afecta la escalada de HPA.
• Para reducir la superficie de CVE evitando shells y gestores de paquetes en imágenes de producción.
• Para construir artefactos reproducibles en CI con digests de imágenes base fijados.

Ejemplo de Trabajo

Dockerfile orientado a producción con certificados CA para TLS saliente:

# 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 .

Lo que esto demuestra:

• La montura de caché de BuildKit acelera las descargas repetidas de go mod download en CI.
• Una etapa certs dedicada copia solo ca-certificates.crt en distroless.
• El usuario nonroot evita ejecutarse como UID 0 dentro del contenedor.
• Los argumentos de compilación inyectan metadatos de versión sin editar el código fuente antes de la compilación.

Análisis Profundo

Cómo Funciona

• Aislamiento de etapas: solo los artefactos que copias con COPY --from= aparecen en el historial de la imagen final.
• Enlazado estático: CGO_ENABLED=0 evita los requisitos del cargador dinámico de glibc en Linux amd64/arm64.
• Bases distroless: imágenes mantenidas por Google con libc y certificados pero sin shell ni apt.
• Variante scratch: sistema de archivos vacío más tu binario; debes añadir el archivo CA manualmente para HTTPS.

Opciones de Imagen Base

Notas de Go

# Verifica que el binario sea estático antes de elegir scratch
CGO_ENABLED=0 go build -o api ./cmd/api
file api   # espera "statically linked"
ldd api    # espera "not a dynamic executable" en Linux

• Alpine basado en Musl puede romper algunas compilaciones con CGO_ENABLED=1; prefiere constructores de debian bookworm para cgo.
• -trimpath elimina $PWD de los binarios para auditorías de cadena de suministro.
• Usa GOAMD64=v3 solo cuando controles la línea base de la CPU y quieras instrucciones SIMD más nuevas.

BuildKit y CI

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

• Las monturas de caché no son capas; persisten entre ejecuciones de CI en el mismo constructor.
• Fija las imágenes base por digest en las canalizaciones de producción: golang:1.26-bookworm@sha256:....
• Ejecuta docker scout cves o tu escáner en la etiqueta de la etapa final, no en la del constructor.

Trampas Comunes

• HTTPS sin certificados: las imágenes distroless/static fallan los handshakes TLS hasta que copias ca-certificates.crt.
• Sorpresas de CGO: importar paquetes que usan cgo habilita silenciosamente el enlazado dinámico a menos que establezcas CGO_ENABLED=0.
• Datos de zona horaria: las imágenes scratch carecen de /usr/share/zoneinfo; establece TZ o copia zoneinfo si los logs necesitan la hora local.
• Depuración: no hay shell kubectl exec en distroless; confía en logs, métricas y pods de depuración efímeros con herramientas.
• Directiva USER: asegúrate de que el binario escuche en puertos >= 1024 o concede CAP_NET_BIND_SERVICE deliberadamente.

Alternativas

• ko / buildpacks: compila y envía imágenes sin mantener un Dockerfile; bueno para plataformas estandarizadas.
• Bazel rules_oci: compilaciones herméticas para monorepos ya en Bazel.
• Imagen de una sola etapa "gorda": aceptable para clústeres de desarrollo; evita para registros de producción.
• Binario puro en VM: omite Docker por completo cuando la orquestación es systemd y las imágenes son innecesarias.

Preguntas Frecuentes

Relacionado

• Despliegue de Go: Binario Único como Superpoder - por qué importan los binarios estáticos
• Conceptos Básicos de Despliegue - primer Dockerfile y kubectl apply
• Despliegues, Servicios e Ingress de Kubernetes - ejecutando imágenes mínimas en clústeres
• Canalizaciones CI/CD para Servicios Go - compila y envía en la canalización
• Mejores Prácticas de Despliegue - etiquetas inmutables y firma de imágenes

Versiones de Stack: Esta página fue escrita para Go 1.26.x (predeterminado Green Tea GC, go fix modernizers - verifica el parche en la compilación), chi (última versión - verifica en la compilación), gin (última versión - verifica en la compilación), echo (última versión - verifica en la compilación), google.golang.org/grpc (última versión - verifica en la compilación), sigs.k8s.io/controller-runtime (última versión - verifica en la compilación), kubebuilder (última versión - verifica en la compilación), tinygo (última versión - verifica los objetivos de placa en la compilación), wazero (última versión - verifica en la compilación) y golangci-lint (última versión - verifica el conjunto de linters en la compilación).