Docker
Arquitecturas, manifest lists, emulación y builders nativos.
Una imagen multi-platform no es un único filesystem capaz de ejecutarse en cualquier equipo. Es una referencia que agrupa varias imágenes específicas y permite que el cliente seleccione la compatible con su sistema operativo y arquitectura.
registry.example.com/api:1.8.2
→ image index / manifest list
├── linux/amd64 → manifest A → layers A
└── linux/arm64 → manifest B → layers BCada variante puede contener binarios, paquetes y digests distintos. Publicar un índice no demuestra que todas funcionen.
Una plataforma suele expresarse como:
OS / architecture / variantEjemplos:
linux/amd64;linux/arm64;linux/arm/v7;windows/amd64.amd64 es común en servidores x86-64. arm64 aparece en Apple Silicon, servidores ARM y dispositivos edge.
docker pull registry.example.com/api:1.8.2El cliente consulta el índice y solicita el manifest que coincide con la plataforma del daemon.
Para seleccionar explícitamente:
docker pull --platform linux/arm64 registry.example.com/api:1.8.2Inspección:
docker buildx imagetools inspect registry.example.com/api:1.8.2Verifica que estén las plataformas esperadas y sus digests.
docker buildx build \
--platform linux/amd64,linux/arm64 \
--tag registry.example.com/api:1.8.2 \
--push \
.Un resultado multi-platform normalmente se publica directamente en un registry. El image store local y el driver del builder determinan qué outputs pueden cargarse localmente.
docker buildx administra builders con capacidades distintas.
docker buildx ls
docker buildx inspect --bootstrapEl builder puede ejecutarse:
La topología del builder afecta cache, emulación, secrets y plataformas disponibles.
QEMU/binfmt permite ejecutar instrucciones de otra arquitectura.
host amd64
→ emula arm64
→ RUN arm64 durante buildVentajas:
Costes:
Es adecuada para builds ligeros o como respaldo, no siempre para compilación intensiva.
nodo amd64 construye amd64
nodo arm64 construye arm64Ventajas:
Costes:
El builder ejecuta en una arquitectura y produce binario para otra.
Es común en Go, Rust y toolchains compatibles.
FROM --platform=$BUILDPLATFORM golang:1.24 AS build
ARG TARGETOS
ARG TARGETARCH
RUN GOOS=$TARGETOS GOARCH=$TARGETARCH go build -o /out/app ./cmd/appVentajas:
Limitaciones:
ARG BUILDPLATFORM
ARG TARGETPLATFORM
ARG TARGETOS
ARG TARGETARCH
ARG TARGETVARIANTBUILDPLATFORM: donde ejecuta el builder stage.TARGETPLATFORM: plataforma de la imagen producida.Ejemplo:
FROM --platform=$BUILDPLATFORM node:22-bookworm AS build
ARG TARGETPLATFORM
RUN echo "Building for $TARGETPLATFORM"No añadas --platform=linux/amd64 fijo al FROM final si quieres soportar otras variantes.
JavaScript puro suele ser portable, pero node_modules puede incluir:
Cada plataforma debe instalar o compilar sus propias dependencias.
Antipatrón:
FROM --platform=$BUILDPLATFORM node:22 AS deps
RUN npm ci
FROM node:22-slim
COPY --from=deps /app/node_modules ./node_modulesSi build y target difieren, node_modules puede contener binarios de la plataforma del builder.
Diseña stages para que instalación nativa ocurra en target platform, o usa estrategia soportada por cada paquete.
Arquitectura no es la única frontera.
linux/arm64 + glibc
≠
linux/arm64 + muslUn módulo compilado en Alpine puede fallar en Debian aunque ambos sean ARM64.
Mantén familias compatibles entre build y runtime.
La base debe publicar la plataforma objetivo.
Si FROM vendor/image:tag solo existe para amd64, el build ARM64 falla o requiere una alternativa.
Inspecciona:
docker buildx imagetools inspect node:22-bookworm-slimNo asumas soporte porque el tag existe.
Mínimo:
Ejemplo:
docker run --rm \
--platform linux/arm64 \
registry.example.com/api:1.8.2 \
node --versionSi el host usa emulación, no sustituye pruebas periódicas en hardware ARM real.
job amd64 → build/test amd64
job arm64 → build/test arm64
merge manifests → index de releaseO un único buildx multi-platform con builders nativos.
Conserva resultados de cada plataforma antes de publicar el índice. Evita que una variante fallida deje un tag parcial.
La cache puede variar por plataforma.
cache linux/amd64
cache linux/arm64Usa scopes separados cuando los outputs nativos difieren. Capas de source puro pueden compartir metadata, pero no fuerces una cache incompatible.
Verifica builds con cache vacía en ambas plataformas.
Cada manifest contiene paquetes diferentes. Una vulnerabilidad puede afectar solo amd64 o arm64.
index digest
├── amd64 digest + SBOM + scan
└── arm64 digest + SBOM + scanAsocia attestations correctamente y revisa todas las variantes antes de promocionar.
La provenance debe registrar:
Un índice multi-platform agrupa varios subjects. La política debe verificar cada manifest relevante.
Variantes pueden tener tamaños distintos por:
No compares solo el tamaño del índice. Mide pulls y startup en cada plataforma.
La mayoría de amd64/arm64 actuales usan little-endian, pero código nativo, serialización o bindings pueden contener assumptions de arquitectura:
Tests funcionales son obligatorios.
ARM64 no es simplemente “más lento” o “más rápido”. Depende de:
Realiza benchmarks en hardware objetivo. No extrapoles desde emulación.
Docker Desktop ejecuta containers Linux dentro de una VM ARM64. Una image solo amd64 puede ejecutarse mediante emulación, pero:
Publicar ambas variantes mejora experiencia local, pero debe mantenerse con tests.
Un tag multi-platform apunta al digest del índice. Cada plataforma tiene otro digest.
Para reproducibilidad completa registra:
Un deployment por índice permite que cada nodo seleccione su arquitectura, siempre que todas las variantes hayan sido aprobadas.
# syntax=docker/dockerfile:1
FROM node:22-bookworm-slim AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm npm ci
FROM deps AS build
COPY . .
RUN npm test && npm run build
FROM node:22-bookworm-slim AS prod-deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm npm ci --omit=dev
FROM node:22-bookworm-slim AS runtime
WORKDIR /app
ENV NODE_ENV=production
COPY --from=prod-deps --chown=node:node /app/node_modules ./node_modules
COPY --from=build --chown=node:node /app/dist ./dist
USER node
CMD ["node", "dist/server.js"]Build:
docker buildx build \
--platform linux/amd64,linux/arm64 \
--tag registry.example.com/api:git-abc1234 \
--provenance=true \
--sbom=true \
--push .La instalación de dependencias se resuelve por target durante cada build. Confirma el comportamiento con el driver y Dockerfile reales.
El binario o image no coincide con arquitectura y no hay emulación válida.
uname -m
docker image inspect image --format '{{.Architecture}}'El índice no contiene la plataforma del daemon.
Probablemente usa emulación. Revisa builder y nodos.
El manifest existe, pero el artefacto está roto. El índice no valida funcionalidad.
Durante cross-build puede detectar build platform en vez de target. Usa variables explícitas.
x86_64, amd64, aarch64 y arm64 requieren mapeo correcto.
Cross-compilation pura no basta; usa emulación o stage nativo para tests.
Verifica soporte y política de retención.
No se combinan como si fueran variantes Linux ordinarias; requieren hosts y bases compatibles con Windows.
Solo crea metadata/artefactos potencialmente rotos.
Binarios de arquitectura incorrecta.
No detecta todos los problemas de hardware real.
Build falla tarde.
Findings específicos de una variante quedan ocultos.
Rompe portabilidad.
exec format error.node_modules desde BUILDPLATFORM puede fallar?Docker en producción, donde el artefacto entra en un sistema con disponibilidad, seguridad, operación, capacidad y recuperación.