Introducción a las imágenes multi-arquitectura en Docker

En entornos de computación en la nube y en el borde, el despliegue de aplicaciones en diferentes tipos de hardware (como x86_64, ARM64) requiere imágenes de contenedor que se adapten automáticamente. Docker resuelve este desafío mediante imágenes multi-arquitectura, que agrupan variantes específicas de plataforma bajo una única etiqueta. Esto se logra a través de una lista de manifiestos (manifest list), que permite al cliente Docker descargar la versión correcta según su arquitectura de CPU.

El proceso central para crear estas imágenes implica el uso de la herramienta docker buildx. Un ejemplo simplificado de construcción y publicación sería:

# Inicializar un entorno de compilación específico para múltiples plataformas
docker buildx create --name motor_compilacion --driver docker-container --use

# Compilar y enviar imágenes para amd64 y arm64 al registro
docker buildx build --platform linux/amd64,linux/arm64 --push -t ejemplo/mi-aplicacion:1.0 .

Este comando genera las variantes de la imagen y las empaqueta en un índice de imágenes compatible con el estándar OCI, que el registro de contenedores almacena y sirve de forma eficiente.

Componentes técnicos de los manifiestos multi-arquitectura

Una imagen multi-arquitectura se compone de un archivo JSON de índice que actúa como directorio. Este índice lista los "digests" (identificadores únicos) de cada manifiesto de imagen individual, junto con su plataforma objetivo.

{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.index.v1+json",
  "manifests": [
    {
      "digest": "sha256:f47ac10b58...",
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "platform": {
        "architecture": "amd64",
        "os": "linux"
      }
    },
    {
      "digest": "sha256:553e1b9f72...",
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "platform": {
        "architecture": "arm64",
        "os": "linux"
      }
    }
  ]
}

Al hacer docker pull ejemplo/mi-aplicacion:1.0, el demonio Docker examina este índice, compara la arquitectura del host con los campos platform y descarga solo la variante correspondiente, junto con sus capas de sistema de archivos compartidas.

Estrategias de construcción con Buildx y QEMU

Docker Buildx, basado en BuildKit, extiende las capacidades de compilación nativas. Permite la compilación cruzada y la creación de imágenes para arquitecturas que no coinciden con la del host de compilación. Esto se facilita mediente el emulador QEMU, que permite ejecutar binarios de otras arquitecturas.

Para optimizar el proceso de compilación para múltiples arquitecturas, se recomienda utilizar la instrucción --platform en el Dockerfile para separar las etapas de compilación según la arquitectura de destino y la de construcción. Un patrón común es:

# Etapa de compilación: usa la arquitectura del host de compilación
FROM --platform=$BUILDPLATFORM golang:1.21-alpine AS compilador
WORKDIR /fuente
COPY . .
ARG TARGETOS TARGETARCH
RUN CGO_ENABLED=0 GOOS=$TARGETOS GOARCH=$TARGETARCH go build -o ./servidor .

# Etapa final: usa la arquitectura objetivo (seleccionada por el sistema)
FROM alpine:3.18
COPY --from=compilador /fuente/servidor /servidor
CMD ["/servidor"]

Al ejecutar docker buildx build --platform linux/arm64 -t ..., $TARGETARCH se establece automáticamente en arm64, y la compilación de Go se realiza para esa arquitectura específica. La etapa final siempre se construye para la plataforma objetivo, garantizando que las bibliotecas de tiempo de ejecución sean las correctas.

Integración en pipelines de CI/CD y despliegue continuo

La automatización de la construcción de imágenes multi-arquitectura es fundamental para los flujos de trabajo modernos. En GitHub Actions, se puede lograr combinando la configuración de QEMU con la acción oficial de Buildx.

jobs:
  construir-multiples-arquitecturas:
    runs-on: ubuntu-latest
    steps:
      - name: Configurar QEMU para emulación
        uses: docker/setup-qemu-action@v3

      - name: Configurar el motor Buildx
        uses: docker/setup-buildx-action@v3

      - name: Construir y publicar imagen
        uses: docker/build-push-action@v5
        with:
          context: .
          platforms: linux/amd64,linux/arm64
          push: true
          tags: registry.io/app:latest,registry.io/app:${{ github.sha }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

Este flujo de trabajo construye la imagen para ambas arquitecturas en paralelo, la publica en un registro con dos etiquetas y utiliza la caché de GitHub Actions para acelerar compilaciones futuras. El registro resulatnte es una imagen multi-arquitectura lista para ser desplegada en clústeres heterogéneos.

Solución de problemas comunes de compatibilidad

Al desplegar en clústeres con nodos de diferentes arquitecturas (por ejemplo, en Kubernetes), pueden surgir problemas si una imagen no es multi-arquitectura. Kubernetes usa el campo kubernetes.io/arch del nodo para programar pods, pero depende de la etiqueta de la imagen para encontrar la variante correcta.

Un problema común es el fallo de arranque (CrashLoopBackOff) en nodos ARM64 cuando la imagen solo contiene binarios compilados para x86. Para diagnosticar, se puede verificar la arquitectura del nodo y la imagen:

# Verificar la arquitectura de los nodos
kubectl get nodes -o custom-columns='NOMBRE:.metadata.name,ARQUITECTURA:.status.nodeInfo.architecture'

# Inspeccionar la arquitectura del manifiesto de la imagen en el registro
docker manifest inspect registry.io/app:latest

# Comprobar la arquitectura dentro de un contenedor en ejecución
kubectl exec pod-ejemplo -- uname -m

Otra fuente de incompatibilidad son las bibliotecas o binarios estáticos incluidos en la imagen. Herramientas como ldd (en Linux) pueden revelar dependencias dinámicas faltantes para la arquitectura objetivo. A menudo, la solución es usar imágenes base diferentes para cada arquitectura dentro del mismo Dockerfile, o asegurarse de que todas las dependencias se compilen para el objetivo deseado durante la etapa de construcción.