¿Cómo Resolver el Problema de 'docker buildx build' que Requiere Exactamente 1 Argumento?

Introducción

Docker Buildx extiende el comando estándar docker build con características mejoradas para crear imágenes de múltiples arquitecturas. Sin embargo, los usuarios a menudo se encuentran con el error "docker buildx build requires exactly 1 argument" (docker buildx build requiere exactamente 1 argumento) al trabajar con esta herramienta. Este tutorial completo le guiará a través de la comprensión de Docker Buildx, el diagnóstico de este error común y la implementación de soluciones efectivas.

Al final de este laboratorio, tendrá experiencia práctica en la configuración de Docker Buildx, la creación de imágenes Docker, la solución de problemas del error "requires exactly 1 argument" y la construcción de imágenes para múltiples arquitecturas. Estas habilidades son esenciales para el desarrollo y despliegue de aplicaciones modernizadas en contenedores.

Configuración de Docker Buildx

Docker Buildx viene preinstalado con Docker, pero necesita ser configurado correctamente antes de su uso. En este paso, verificaremos que Docker esté instalado, habilitaremos Docker Buildx y crearemos nuestra primera instancia de constructor (builder).

Verificación de la instalación de Docker

Primero, confirmemos que Docker está instalado y en ejecución en nuestro sistema:

docker --version

Debería ver una salida similar a:

Docker version 20.10.21, build baeda1f

Esto confirma que Docker está instalado y listo para usar.

Comprensión de Docker Buildx

Docker Buildx es un plugin de la interfaz de línea de comandos (CLI) que extiende la funcionalidad de Docker con BuildKit. Permite:

• Construir imágenes para múltiples plataformas (como AMD64, ARM64) simultáneamente
• Un almacenamiento en caché de capas (layer caching) más eficiente
• Un rendimiento de construcción mejorado
• Características de construcción avanzadas

Creación de un Constructor Docker Buildx

Creemos y usemos un nuevo constructor Docker Buildx:

docker buildx create --name mybuilder --use

La salida debería ser similar a:

mybuilder

Ahora, verifiquemos que nuestro constructor fue creado y está configurado como el predeterminado:

docker buildx ls

Debería ver una salida similar a:

NAME/NODE    DRIVER/ENDPOINT             STATUS  PLATFORMS
mybuilder *  docker-container
  mybuilder0 unix:///var/run/docker.sock inactive
default      docker
  default    default                     running  linux/amd64, linux/386

El asterisco (*) junto a mybuilder indica que es el constructor actualmente activo.

Inspección del Constructor

Examinemos los detalles de nuestro constructor:

docker buildx inspect mybuilder

Esto le mostrará la configuración del constructor, incluyendo las plataformas soportadas y su estado actual.

Ahora que hemos configurado Docker Buildx con éxito, estamos listos para pasar a la creación de un Dockerfile para usar con nuestro constructor.

Creación de un Dockerfile Simple para Pruebas

Antes de usar Docker Buildx para construir imágenes, necesitamos crear un Dockerfile simple. Esto servirá como nuestro caso de prueba para comprender el error "requires exactly 1 argument" (requiere exactamente 1 argumento).

Comprensión de los Dockerfiles

Un Dockerfile es un documento de texto que contiene instrucciones para construir una imagen Docker. Automatiza el proceso de creación de contenedores con configuraciones específicas.

Creemos un directorio para nuestro proyecto:

mkdir -p ~/project/buildx-test
cd ~/project/buildx-test

Creación de un Dockerfile Básico

Ahora, creemos un Dockerfile simple usando el editor de texto nano:

nano Dockerfile

Copie y pegue el siguiente contenido en el Dockerfile:

FROM ubuntu:22.04

RUN apt-get update && apt-get install -y \
  curl \
  nginx \
  && rm -rf /var/lib/apt/lists/*

EXPOSE 80

CMD ["nginx", "-g", "daemon off;"]

Presione Ctrl+O seguido de Enter para guardar, luego Ctrl+X para salir de nano.

Desglosemos este Dockerfile:

• FROM ubuntu:22.04 - Usa Ubuntu 22.04 como imagen base
• RUN apt-get update... - Actualiza las listas de paquetes e instala curl y nginx
• EXPOSE 80 - Indica que el contenedor escuchará en el puerto 80
• CMD ["nginx", "-g", "daemon off;"] - Ejecuta nginx en primer plano cuando el contenedor se inicia

Creación de un archivo .dockerignore

Un archivo .dockerignore ayuda a excluir archivos y directorios que no son necesarios en el contexto de construcción, haciendo que las construcciones sean más rápidas y eficientes:

nano .dockerignore

Agregue el siguiente contenido:

.git
.gitignore
*.md

Presione Ctrl+O seguido de Enter para guardar, luego Ctrl+X para salir de nano.

Verificación de la estructura del proyecto

Verifiquemos que nuestros archivos se hayan creado correctamente:

ls -la

Debería ver una salida similar a:

total 16
drwxrwxr-x 2 labex labex 4096 Jan 1 00:00 .
drwxr-xr-x 3 labex labex 4096 Jan 1 00:00 ..
-rw-rw-r-- 1 labex labex   21 Jan 1 00:00 .dockerignore
-rw-rw-r-- 1 labex labex  159 Jan 1 00:00 Dockerfile

Ahora que tenemos un Dockerfile básico, estamos listos para probar Docker Buildx y explorar el error "requires exactly 1 argument" en el siguiente paso.

Comprensión y Resolución del Error "Requires Exactly 1 Argument" (Requiere Exactamente 1 Argumento)

En este paso, provocaremos deliberadamente el error "requires exactly 1 argument" (requiere exactamente 1 argumento) para comprender sus causas, y luego aprenderemos a resolverlo.

Provocando el Error

Primero, naveguemos a nuestro directorio del proyecto si aún no estamos allí:

cd ~/project/buildx-test

Ahora, intentemos construir una imagen usando Docker Buildx sin especificar el contexto de construcción:

docker buildx build

Debería ver un mensaje de error similar a:

"docker buildx build" requires exactly 1 argument.
See 'docker buildx build --help'.

Usage:  docker buildx build [OPTIONS] PATH | URL | -

Este error ocurre porque el comando docker buildx build requiere un contexto de construcción (el directorio que contiene el Dockerfile) como argumento.

Comprensión del Error

El error "requires exactly 1 argument" (requiere exactamente 1 argumento) significa que Docker Buildx necesita saber dónde encontrar los archivos necesarios para construir la imagen. Este argumento es típicamente una ruta al directorio que contiene su Dockerfile (el contexto de construcción).

Los escenarios comunes que desencadenan este error incluyen:

1. Olvidar especificar el contexto de construcción
2. Usar una sintaxis de comando incorrecta
3. Colocar opciones en el orden incorrecto

Corrección del Error

Corrijamos el comando agregando el contexto de construcción. La forma más sencilla es usar . para indicar el directorio actual:

docker buildx build .

Esta vez, Docker iniciará el proceso de construcción, pero notaremos que no etiqueta la imagen, lo que dificulta su referencia posterior.

Detengamos la construcción con Ctrl+C si aún se está ejecutando, e intentemos de nuevo con una etiqueta adecuada:

docker buildx build -t nginx-test:latest .

Debería ver una salida que muestra el progreso de la construcción:

[+] Building 12.8s (7/7) FINISHED
 => [internal] load build definition from Dockerfile                          0.0s
 => => transferring dockerfile: 203B                                          0.0s
 => [internal] load .dockerignore                                             0.0s
 => => transferring context: 34B                                              0.0s
 => [internal] load metadata for docker.io/library/ubuntu:22.04               0.5s
 => [1/3] FROM docker.io/library/ubuntu:22.04@sha256:...                      0.0s
 => CACHED [2/3] RUN apt-get update && apt-get install -y     curl     nginx  0.0s
 => CACHED [3/3] EXPOSE 80                                                    0.0s
 => exporting to image                                                        0.0s
 => => exporting layers                                                       0.0s
 => => writing image sha256:...                                               0.0s
 => => naming to docker.io/library/nginx-test:latest                          0.0s

Uso de Diferentes Opciones de Buildx

Exploremos algunas opciones adicionales con Docker Buildx:

1. Construyendo y cargando la imagen en el almacén de imágenes local de Docker:

docker buildx build --load -t nginx-test:local .

2. Construyendo sin usar la caché de construcción (forzando una construcción nueva):

docker buildx build --no-cache -t nginx-test:nocache .

3. Construyendo y generando solo el ID de la imagen final:

docker buildx build -q -t nginx-test:quiet .

Verificación de las Imágenes Construidas

Verifiquemos las imágenes que hemos construido:

docker images | grep nginx-test

Debería ver una salida similar a:

nginx-test     quiet      abcdef123456   5 minutes ago   123MB
nginx-test     nocache    fedcba654321   5 minutes ago   123MB
nginx-test     local      123456abcdef   5 minutes ago   123MB
nginx-test     latest     abcdef123456   5 minutes ago   123MB

Ahora comprende el error común "requires exactly 1 argument" (requiere exactamente 1 argumento) con Docker Buildx y sabe cómo construir imágenes correctamente con varias opciones.

Construyendo Imágenes Multi-Arquitectura con Docker Buildx

Una de las características más poderosas de Docker Buildx es su capacidad para construir imágenes para múltiples arquitecturas simultáneamente. En este paso, aprenderemos a crear imágenes multi-arquitectura.

Comprensión de las Imágenes Multi-Arquitectura

Las imágenes multi-arquitectura permiten que el mismo nombre de imagen funcione en diferentes plataformas (como AMD64, ARM64, etc.). Docker selecciona automáticamente la versión apropiada para la arquitectura del host cuando se extrae la imagen.

Esto es especialmente útil para:

• Soportar dispositivos basados tanto en x86 como en ARM
• Asegurar que sus aplicaciones se ejecuten en varios proveedores de la nube
• Construir para dispositivos IoT con diferentes arquitecturas

Configuración para Construcciones Multi-Arquitectura

Docker Buildx necesita ser configurado para construcciones multi-arquitectura. Primero, asegurémonos de que nuestro constructor soporte esta característica:

docker buildx inspect --bootstrap mybuilder

Si ve un error sobre que el constructor no está disponible, recreémoslo con la configuración correcta:

docker buildx rm mybuilder
docker buildx create --name mybuilder --driver docker-container --bootstrap --use

Creación de una Imagen Multi-Arquitectura

Ahora, construyamos nuestra imagen Nginx para múltiples arquitecturas:

docker buildx build --platform linux/amd64,linux/arm64 -t nginx-test:multi .

Podría ver un mensaje de error similar a:

error: multiple platforms feature is currently not supported for docker driver. Please switch to a different driver (eg. "docker buildx create --use")

Esto sucede porque el controlador Docker predeterminado no admite construcciones multi-arquitectura. Modifiquemos nuestro enfoque.

Para fines de demostración, construiremos para plataformas específicas por separado:

docker buildx build --platform linux/amd64 -t nginx-test:amd64 --load .

Esto construye la imagen específicamente para la arquitectura AMD64 y la carga en el almacén de imágenes local de Docker.

Uso de Argumentos de Construcción

Docker Buildx nos permite usar argumentos de construcción para personalizar nuestras construcciones. Modifiquemos nuestro Dockerfile para usar un argumento de construcción:

nano Dockerfile

Actualice el contenido del Dockerfile a:

FROM ubuntu:22.04

ARG PACKAGE=nginx
RUN apt-get update && apt-get install -y \
  curl \
  ${PACKAGE} \
  && rm -rf /var/lib/apt/lists/*

EXPOSE 80

CMD ["nginx", "-g", "daemon off;"]

Presione Ctrl+O seguido de Enter para guardar, luego Ctrl+X para salir de nano.

Ahora podemos construir la imagen con un paquete personalizado:

docker buildx build --build-arg PACKAGE=nginx-extras -t nginx-extras:latest .

Empujando a un Registro (Opcional)

Para utilizar completamente las imágenes multi-arquitectura, normalmente las empujaría a un registro. Esto requiere credenciales de Docker Hub o un registro privado. En un escenario del mundo real, el comando se vería así:

## Ejemplo solamente - no requerido para este laboratorio
## docker buildx build --platform linux/amd64,linux/arm64 -t username/nginx-test:multi --push .

Inspeccionando Imágenes

Examinemos las imágenes que hemos creado:

docker images | grep nginx

Debería ver una salida similar a:

nginx-extras    latest     abcdef123456   1 minute ago    130MB
nginx-test      amd64      123456abcdef   2 minutes ago   123MB
nginx-test      latest     fedcba654321   10 minutes ago  123MB

Probando Nuestra Imagen

Finalmente, ejecutemos un contenedor usando nuestra imagen para verificar que funcione:

docker run -d --name test-nginx -p 8080:80 nginx-test:latest

Verifique si el contenedor se está ejecutando:

docker ps

Debería ver una salida que indica que su contenedor se está ejecutando:

CONTAINER ID   IMAGE              COMMAND                  CREATED          STATUS          PORTS                  NAMES
abcdef123456   nginx-test:latest  "nginx -g 'daemon of…"   10 seconds ago   Up 10 seconds   0.0.0.0:8080->80/tcp   test-nginx

Hagamos un curl al servidor nginx para asegurarnos de que está respondiendo:

curl http://localhost:8080

Debería ver la página de bienvenida HTML predeterminada de Nginx.

Cuando termine, limpie el contenedor:

docker stop test-nginx
docker rm test-nginx

¡Felicidades! Ha trabajado con éxito con Docker Buildx, ha comprendido y resuelto el error "requires exactly 1 argument" (requiere exactamente 1 argumento), y ha aprendido a crear construcciones especializadas para diferentes arquitecturas.

Resumen

En este laboratorio, obtuvo experiencia práctica con Docker Buildx y aprendió a solucionar el error común "requires exactly 1 argument" (requiere exactamente 1 argumento). Esto es lo que logró:

1. Configurar Docker Buildx y crear una instancia de constructor
2. Crear un Dockerfile básico para pruebas
3. Encontrar, comprender y resolver el error "requires exactly 1 argument" (requiere exactamente 1 argumento)
4. Construir imágenes de Docker con varias opciones y configuraciones
5. Aprender los conceptos básicos de la construcción de imágenes multi-arquitectura

Estas habilidades proporcionan una base sólida para trabajar con Docker en entornos de desarrollo modernos, donde las aplicaciones a menudo necesitan ejecutarse en diversas plataformas de hardware. Ahora puede usar con confianza Docker Buildx para crear imágenes de contenedor eficientes y específicas de la plataforma, evitando errores comunes.

A medida que continúe su viaje con Docker, considere explorar funciones más avanzadas de Buildx, integrarlo en las tuberías de CI/CD y usarlo para construir aplicaciones verdaderamente portátiles que puedan ejecutarse en cualquier lugar.