docker buildx build

Descripción

El comando docker buildx build inicia una construcción utilizando BuildKit.

Opciones

Ejemplos

Añadir entradas al archivo hosts del contenedor (--add-host)

Puedes añadir otros hosts al archivo /etc/hosts de un contenedor de construcción utilizando una o más banderas --add-host. Este ejemplo añade direcciones estáticas para los hosts llamados my-hostname y my_hostname_v6:

$ docker buildx build --add-host my_hostname=8.8.8.8 --add-host my_hostname_v6=2001:4860:4860::8888 .

Si necesitas que tu construcción se conecte a servicios que se ejecutan en el host, puedes usar el valor especial host-gateway para --add-host. En el siguiente ejemplo, los contenedores de construcción resuelven host.docker.internal a la IP de la puerta de enlace (gateway) del host.

$ docker buildx build --add-host host.docker.internal=host-gateway .

Puedes envolver una dirección IPv6 entre corchetes. = y : son separadores válidos. Ambos formatos en el siguiente ejemplo son válidos:

$ docker buildx build --add-host my-hostname:10.180.0.1 --add-host my-hostname_v6=[2001:4860:4860::8888] .

Crear anotaciones (--annotation)

--annotation="key=value"
--annotation="[type:]key=value"

Añade anotaciones OCI al índice de la imagen, al manifiesto o al descriptor. El siguiente ejemplo añade la anotación foo=bar a los manifiestos de la imagen:

$ docker buildx build -t TAG --annotation "foo=bar" --push .

Opcionalmente, puedes añadir un prefijo de tipo para especificar el nivel de la anotación. De forma predeterminada, se anota el manifiesto de la imagen. El siguiente ejemplo añade la anotación foo=bar al índice de la imagen en lugar de a los manifiestos:

$ docker buildx build -t TAG --annotation "index:foo=bar" --push .

Puedes especificar múltiples tipos, separados por una coma (,), para añadir la anotación a varios componentes de la imagen. El siguiente ejemplo añade la anotación foo=bar al índice de imagen, a los descriptores y a los manifiestos:

$ docker buildx build -t TAG --annotation "index,manifest,manifest-descriptor:foo=bar" --push .

También puedes especificar un calificador de plataforma entre corchetes ([os/arch]) en el prefijo de tipo, para aplicar la anotación a un subconjunto de manifiestos con la plataforma correspondiente. El siguiente ejemplo añade la anotación foo=bar únicamente al manifiesto con la plataforma linux/amd64:

$ docker buildx build -t TAG --annotation "manifest[linux/amd64]:foo=bar" --push .

No se admiten comodines en el calificador de plataforma; no puedes especificar un prefijo de tipo como manifest[linux/*] para añadir anotaciones solo a los manifiestos que tengan linux como plataforma del sistema operativo.

Para obtener más información sobre las anotaciones, consulta Anotaciones.

Crear atestaciones (--attest)

--attest=type=sbom,...
--attest=type=provenance,...

Crea atestaciones de imagen. BuildKit admite actualmente:

• sbom - Lista de materiales de software (Software Bill of Materials).

  Utiliza --attest=type=sbom para generar un SBOM para una imagen en tiempo de construcción. Alternativamente, puedes usar el atajo --sbom.

  Para obtener más información, consulta aquí.

• provenance - Procedencia (SLSA Provenance)

  Utiliza --attest=type=provenance para generar la procedencia de una imagen en tiempo de construcción. Alternativamente, puedes usar el atajo --provenance.

  De forma predeterminada, se creará una atestación de procedencia mínima para el resultado de la construcción, que solo se adjuntará para las imágenes subidas a los registros.

  Para obtener más información, consulta aquí.

Permitir concesiones de privilegios adicionales (--allow)

--allow=ENTITLEMENT

Permite concesiones de privilegios adicionales. Lista de concesiones:

• network.host - Permite ejecuciones con la red del host.
• security.insecure - Permite ejecuciones sin sandbox. Consulta las extensiones de Dockerfile relacionadas.
• device - Permite el acceso a dispositivos de la Interfaz de Dispositivos de Contenedor (CDI).
  • --allow device - Otorga acceso a todos los dispositivos.
  • --allow device=kind|name - Otorga acceso a un dispositivo específico.
  • --allow device=kind|name,alias=kind|name - Otorga acceso a un dispositivo específico, con alias opcional.

Para que se habiliten las concesiones, el demonio de BuildKit también debe permitirlas con --allow-insecure-entitlement (consulta create --buildkitd-flags).

$ docker buildx create --use --name insecure-builder --buildkitd-flags '--allow-insecure-entitlement security.insecure'
$ docker buildx build --allow security.insecure .

Establecer variables en tiempo de construcción (--build-arg)

Puedes usar las instrucciones ENV en un Dockerfile para definir valores de variables. Estos valores persisten en la imagen construida. A menudo, la persistencia no es lo que deseas. Los usuarios quieren especificar variables de manera diferente según el host en el que construyan la imagen.

Un buen ejemplo es http_proxy o las versiones de origen para descargar archivos intermedios. La instrucción ARG permite a los autores de Dockerfile definir valores que los usuarios pueden establecer en tiempo de construcción utilizando la bandera --build-arg:

$ docker buildx build --build-arg HTTP_PROXY=http://10.20.30.2:1234 --build-arg FTP_PROXY=http://40.50.60.5:4567 .

Esta bandera te permite pasar las variables en tiempo de construcción que se acceden como variables de entorno normales en la instrucción RUN del Dockerfile. Estos valores no persisten en las imágenes intermedias o finales como lo hacen los valores ENV. Debes añadir --build-arg para cada argumento de construcción.

El uso de esta bandera no altera la salida que ves cuando el proceso de construcción muestra las líneas ARG del Dockerfile.

Para obtener información detallada sobre el uso de las instrucciones ARG y ENV, consulta la referencia de Dockerfile.

También puedes usar la bandera --build-arg sin un valor, en cuyo caso el demonio propaga el valor del entorno local al contenedor de Docker que está construyendo:

$ export HTTP_PROXY=http://10.20.30.2:1234
$ docker buildx build --build-arg HTTP_PROXY .

Este ejemplo es similar a cómo funciona docker run -e. Consulta la documentación de docker run para obtener más información.

También existen argumentos de construcción integrados muy útiles, tales como:

• BUILDKIT_CONTEXT_KEEP_GIT_DIR=<bool>: activa el contexto de git para conservar el directorio .git
• BUILDKIT_INLINE_CACHE=<bool>: inserta o no los metadatos de la caché en la configuración de la imagen
• BUILDKIT_MULTI_PLATFORM=<bool>: opta por una salida determinante independientemente de si es multiplataforma o no

$ docker buildx build --build-arg BUILDKIT_MULTI_PLATFORM=1 .

Obtén más información sobre los argumentos de construcción integrados en la documentación de referencia de Dockerfile.

Contextos de construcción adicionales (--build-context)

--build-context=name=VALUE

Define un contexto de construcción adicional con el contenido especificado.

En un Dockerfile:

• se puede acceder al contexto cuando se utiliza FROM nombre o --from=nombre
• el contexto sobrescribe una etapa llamada nombre cuando se usa como FROM ... AS nombre
• el contexto sobrescribe una directiva #syntax cuando se usa como #syntax=nombre

El valor puede ser:

• un directorio de origen local
• un directorio local compatible con el diseño (layout) OCI
• una imagen de contenedor
• una URL de Git
• una URL HTTP

Usar una ruta local

Expone un directorio de origen local secundario:

$ docker buildx build --build-context project=path/to/project/source .
# docker buildx build --build-context project=https://github.com/myuser/project.git .

Usar una imagen de contenedor

Usa el esquema docker-image://.

Reemplaza alpine:latest por uno específico:

$ docker buildx build --build-context alpine=docker-image://alpine@sha256:0123456789 .

# syntax=docker/dockerfile:1
FROM alpine
COPY --from=project myfile /

Usar un directorio de diseño OCI como contexto de construcción

Usa el esquema oci-layout:///.

Obtén una imagen desde un directorio local compatible con el diseño (layout) OCI, ya sea por etiqueta (tag) o por digest:

$ docker buildx build --build-context foo=oci-layout:///path/to/local/layout:<tag>
$ docker buildx build --build-context foo=oci-layout:///path/to/local/layout@sha256:<digest>

# syntax=docker/dockerfile:1
FROM alpine
RUN apk add git
COPY --from=foo myfile /

FROM foo

El directorio de diseño OCI debe ser compatible con la especificación de diseño OCI.

Sobrescribir la instancia del builder configurada (--builder)

Igual que buildx --builder.

Usar una fuente de caché externa para una construcción (--cache-from)

--cache-from=[NAME|type=TYPE[,KEY=VALUE]]

Usa una fuente de caché externa para una construcción. Los tipos admitidos son:

• registry puede importar la caché desde un manifiesto de caché o desde una configuración de imagen (especial) en el registro.
• local puede importar la caché desde archivos locales exportados previamente con --cache-to.
• gha puede importar la caché desde una caché exportada previamente con --cache-to en tu repositorio de GitHub.
• s3 puede importar la caché desde una caché exportada previamente con --cache-to en tu cubo (bucket) S3.
• azblob puede importar la caché desde una caché exportada previamente con --cache-to en tu contenedor (bucket) de Azure.

Si no se especifica ningún tipo, se utiliza el exportador registry con la referencia especificada.

$ docker buildx build --cache-from=user/app:cache .
$ docker buildx build --cache-from=user/app .
$ docker buildx build --cache-from=type=registry,ref=user/app .
$ docker buildx build --cache-from=type=local,src=path/to/cache .
$ docker buildx build --cache-from=type=gha .
$ docker buildx build --cache-from=type=s3,region=eu-west-1,bucket=mybucket .

Note

Se puede encontrar más información sobre los exportadores de caché y los atributos disponibles en la documentación de backends de almacenamiento de caché.

Exportar la caché de construcción a un destino de caché externo (--cache-to)

--cache-to=[NAME|type=TYPE[,KEY=VALUE]]

Exporta la caché de construcción a un destino de caché externo. Los tipos admitidos son:

• registry exporta la caché de construcción a un manifiesto de caché en el registro.
• local exporta la caché a un directorio local en el cliente.
• inline escribe los metadatos de la caché en la configuración de la imagen.
• gha exporta la caché a través de la API del servicio de caché de GitHub Actions.
• s3 exporta la caché a un cubo (bucket) S3.
• azblob exporta la caché a un contenedor (bucket) de Azure.

$ docker buildx build --cache-to=user/app:cache .
$ docker buildx build --cache-to=type=inline .
$ docker buildx build --cache-to=type=registry,ref=user/app .
$ docker buildx build --cache-to=type=local,dest=path/to/cache .
$ docker buildx build --cache-to=type=gha .
$ docker buildx build --cache-to=type=s3,region=eu-west-1,bucket=mybucket .

Note

Se puede encontrar más información sobre los exportadores de caché y los atributos disponibles en la documentación de backends de almacenamiento de caché.

Invocar un método frontend (--call)

--call=[build|check|outline|targets]

Los frontends de BuildKit pueden admitir modos de ejecución alternativos para las construcciones, utilizando métodos frontend. Los métodos frontend son una forma de cambiar o ampliar el comportamiento de una invocación de construcción, lo que te permite, por ejemplo, inspeccionar, validar o generar salidas alternativas a partir de una construcción.

La bandera --call para docker buildx build te permite especificar el método frontend que deseas ejecutar. Si esta bandera no se especifica, se ejecuta la construcción y se evalúan las comprobaciones de construcción de forma predeterminada.

Para Dockerfiles, los métodos disponibles son:

Ten en cuenta que otros frontends pueden implementar estos u otros métodos. Para ver la lista de métodos disponibles para el frontend que estás utilizando, usa --call=subrequests.describe.

$ docker buildx build -q --call=subrequests.describe .

NAME                 VERSION DESCRIPTION
outline              1.0.0   List all parameters current build target supports
targets              1.0.0   List all targets current build supports
subrequests.describe 1.0.0   List available subrequest types

Descripciones

Los métodos --call=targets y --call=outline incluyen descripciones para los objetivos y argumentos de construcción, si están disponibles. Las descripciones se generan a partir de los comentarios en el Dockerfile. Un comentario en la línea anterior a una instrucción FROM se convierte en la descripción de un objetivo de construcción, y un comentario anterior a una instrucción ARG en la descripción de un argumento de construcción. El comentario debe comenzar con el nombre de la etapa o argumento, por ejemplo:

# syntax=docker/dockerfile:1

# GO_VERSION sets the Go version for the build
ARG GO_VERSION=1.22

# base-builder is the base stage for building the project
FROM golang:${GO_VERSION} AS base-builder

Al ejecutar docker buildx build --call=outline, la salida incluye las descripciones, de la siguiente manera:

$ docker buildx build -q --call=outline .

TARGET:      base-builder
DESCRIPTION: is the base stage for building the project

BUILD ARG    VALUE   DESCRIPTION
GO_VERSION   1.22    sets the Go version for the build

Para ver más ejemplos sobre cómo escribir cadenas de documentación (docstrings) en un Dockerfile, consulta el Dockerfile para las páginas de documentación de Docker.

Call: check (--check)

El método check evalúa las comprobaciones de construcción sin ejecutar la construcción. La bandera --check es un atajo conveniente para --call=check. Utiliza el método check para validar la configuración de la construcción antes de iniciarla.

$ docker buildx build -q --check https://github.com/docker/docs.git

WARNING: InvalidBaseImagePlatform
Base image wjdp/htmltest:v0.17.0 was pulled with platform "linux/amd64", expected "linux/arm64" for current build
Dockerfile:43
--------------------
  41 |         "#content/desktop/previous-versions/*.md"
  42 |
  43 | >>> FROM wjdp/htmltest:v${HTMLTEST_VERSION} AS test
  44 |     WORKDIR /test
  45 |     COPY --from=build /out ./public
--------------------

El uso de --check sin especificar un objetivo evalúa todo el Dockerfile. Si deseas evaluar un objetivo específico, utiliza la bandera --target.

Call: outline

El método outline imprime el nombre del objetivo especificado (o el objetivo predeterminado, si no se especifica --target), y los argumentos de construcción que consume el objetivo, junto con sus valores predeterminados, si están establecidos.

El siguiente ejemplo muestra el objetivo predeterminado release y sus argumentos de construcción:

$ docker buildx build -q --call=outline https://github.com/docker/docs.git

TARGET:      release
DESCRIPTION: is an empty scratch image with only compiled assets

BUILD ARG          VALUE     DESCRIPTION
GO_VERSION         1.22      sets the Go version for the base stage
HUGO_VERSION       0.127.0
HUGO_ENV                     sets the hugo.Environment (production, development, preview)
DOCS_URL                     sets the base URL for the site
PAGEFIND_VERSION   1.1.0

Esto significa que el objetivo release es configurable utilizando estos argumentos de construcción:

$ docker buildx build \
  --build-arg GO_VERSION=1.22 \
  --build-arg HUGO_VERSION=0.127.0 \
  --build-arg HUGO_ENV=production \
  --build-arg DOCS_URL=https://example.com \
  --build-arg PAGEFIND_VERSION=1.1.0 \
  --target release https://github.com/docker/docs.git

Call: targets

El método targets lista todos los objetivos de construcción en el Dockerfile. Estas son las etapas que puedes construir utilizando la bandera --target. También indica el objetivo predeterminado, que es el objetivo que se construirá cuando no especifiques uno.

$ docker buildx build -q --call=targets https://github.com/docker/docs.git

TARGET            DESCRIPTION
base              is the base stage with build dependencies
node              installs Node.js dependencies
hugo              downloads and extracts the Hugo binary
build-base        is the base stage for building the site
dev               is for local development with Docker Compose
build             creates production builds with Hugo
lint              lints markdown files
test              validates HTML output and checks for broken links
update-modules    downloads and vendors Hugo modules
vendor            is an empty stage with only vendored Hugo modules
build-upstream    builds an upstream project with a replacement module
validate-upstream validates HTML output for upstream builds
unused-media      checks for unused graphics and other media
pagefind          installs the Pagefind runtime
index             generates a Pagefind index
test-go-redirects checks that the /go/ redirects are valid
release (default) is an empty scratch image with only compiled assets

Usar un cgroup primario personalizado (--cgroup-parent)

Al ejecutar docker buildx build con la opción --cgroup-parent, el demonio ejecuta los contenedores utilizados en la construcción con la bandera de docker run correspondiente.

Especificar un Dockerfile (-f, --file)

$ docker buildx build -f [PATH|URL|-] .

Especifica la ubicación del Dockerfile a utilizar. Si no se especifica, se utiliza por defecto un archivo llamado Dockerfile en la raíz del contexto de construcción.

Los formatos de entrada compatibles son:

• Ruta de archivo local
• URL remota
• Entrada estándar

Ruta de archivo local

Para especificar una ruta a un Dockerfile local:

$ docker buildx build -f path/to/Dockerfile .

URL remota

Para especificar una URL a un Dockerfile remoto:

$ docker buildx build -f https://raw.githubusercontent.com/docker/buildx/refs/tags/v0.29.0/Dockerfile .

Entrada estándar

Para leer un Dockerfile desde stdin, utiliza - como argumento:

$ cat Dockerfile | docker buildx build -f - .

Cargar el resultado de la construcción de una sola plataforma en docker images (--load)

Atajo para --output=type=docker. Cargará automáticamente el resultado de la construcción de una sola plataforma en docker images.

Escribir los metadatos del resultado de la construcción en un archivo (--metadata-file)

Para generar metadatos de construcción como el digest de la imagen, pasa la bandera --metadata-file. Los metadatos se escribirán como un objeto JSON en el archivo especificado. El directorio del archivo especificado debe existir previamente y tener permisos de escritura.

$ docker buildx build --load --metadata-file metadata.json .
$ cat metadata.json

{
  "buildx.build.provenance": {},
  "buildx.build.ref": "mybuilder/mybuilder0/0fjb6ubs52xx3vygf6fgdl611",
  "buildx.build.warnings": {},
  "containerimage.config.digest": "sha256:2937f66a9722f7f4a2df583de2f8cb97fc9196059a410e7f00072fc918930e66",
  "containerimage.descriptor": {
    "annotations": {
      "config.digest": "sha256:2937f66a9722f7f4a2df583de2f8cb97fc9196059a410e7f00072fc918930e66",
      "org.opencontainers.image.created": "2022-02-08T21:28:03Z"
    },
    "digest": "sha256:19ffeab6f8bc9293ac2c3fdf94ebe28396254c993aea0b5a542cfb02e0883fa3",
    "mediaType": "application/vnd.oci.image.manifest.v1+json",
    "size": 506
  },
  "containerimage.digest": "sha256:19ffeab6f8bc9293ac2c3fdf94ebe28396254c993aea0b5a542cfb02e0883fa3"
}

Note

La procedencia (provenance) del registro de construcción ( provenance) (buildx.build.provenance) incluye la procedencia mínima de forma predeterminada. Establece la variable de entorno BUILDX_METADATA_PROVENANCE para personalizar este comportamiento:

• min establece la procedencia mínima (predeterminado).
• max establece la procedencia completa.
• disabled, false o 0 no establece ninguna procedencia.

Note

Las advertencias de construcción (buildx.build.warnings) no se incluyen de forma predeterminada. Establece la variable de entorno BUILDX_METADATA_WARNINGS a 1 o true para incluirlas.

Establecer el modo de red para las instrucciones RUN durante la construcción (--network)

Las opciones disponibles para el modo de red son:

• default (predeterminado): Se ejecuta en la red predeterminada.
• none: Se ejecuta sin acceso a la red.
• host: Se ejecuta en el entorno de red del host.

Encuentra más detalles en la referencia de Dockerfile.

Ignorar la caché de construcción para etapas específicas (--no-cache-filter)

La bandera --no-cache-filter te permite especificar una o más etapas de un Dockerfile multietapa para las cuales se debe ignorar la caché de construcción. Para especificar múltiples etapas, utiliza una sintaxis separada por comas:

$ docker buildx build --no-cache-filter stage1,stage2,stage3 .

Por ejemplo, el siguiente Dockerfile contiene cuatro etapas:

• base
• install
• test
• release

# syntax=docker/dockerfile:1

FROM oven/bun:1 AS base
WORKDIR /app

FROM base AS install
WORKDIR /temp/dev
RUN --mount=type=bind,source=package.json,target=package.json \
    --mount=type=bind,source=bun.lockb,target=bun.lockb \
    bun install --frozen-lockfile

FROM base AS test
COPY --from=install /temp/dev/node_modules node_modules
COPY . .
RUN bun test

FROM base AS release
ENV NODE_ENV=production
COPY --from=install /temp/dev/node_modules node_modules
COPY . .
ENTRYPOINT ["bun", "run", "index.js"]

Para ignorar la caché en la etapa install:

$ docker buildx build --no-cache-filter install .

Para ignorar la caché en las etapas install y release:

$ docker buildx build --no-cache-filter install,release .

Los argumentos para la bandera --no-cache-filter deben ser nombres de etapas.

Establecer la acción de exportación para el resultado de la construcción (-o, --output)

-o, --output=[PATH,-,type=TYPE[,KEY=VALUE]

Establece la acción de exportación para el resultado de la construcción. La salida predeterminada, cuando se utiliza el controlador de construcción (driver) docker, es una imagen de contenedor exportada al almacenamiento de imágenes local. La bandera --output hace que este paso sea configurable, permitiendo la exportación de resultados directamente al sistema de archivos del cliente, a un archivo tarball de imagen OCI, a un registro y más.

Buildx con el controlador docker solo admite los exportadores local, tar e image. El controlador docker-container admite todos los exportadores.

Si solo especificas una ruta de archivo como argumento para --output, Buildx utiliza el exportador local. Si el valor es -, Buildx utiliza el exportador tar y escribe la salida en la salida estándar (stdout).

$ docker buildx build -o . .
$ docker buildx build -o outdir .
$ docker buildx build -o - . > out.tar
$ docker buildx build -o type=docker .
$ docker buildx build -o type=docker,dest=- . > myimage.tar
$ docker buildx build -t tonistiigi/foo -o type=registry

Puedes exportar múltiples salidas repitiendo la bandera.

Los tipos exportados admitidos son:

• local
• tar
• oci
• docker
• image
• registry

local

El tipo de exportación local escribe todos los archivos de resultado en un directorio en el cliente. Los nuevos archivos pertenecerán al usuario actual. En las construcciones multiplataforma, todos los resultados se colocarán en subdirectorios según su plataforma.

Clave de atributo:

• dest - directorio de destino donde se escribirán los archivos

Para obtener más información, consulta Exportadores local y tar.

tar

El tipo de exportación tar escribe todos los archivos de resultado como un único archivo tarball en el cliente. En las construcciones multiplataforma, todos los resultados se colocarán en subdirectorios según su plataforma.

Clave de atributo:

• dest - ruta de destino donde se escribirá el archivo tarball. "-" escribe en la salida estándar (stdout).

Para obtener más información, consulta Exportadores local y tar.

oci

El tipo de exportación oci escribe la imagen resultante o la lista de manifiestos como un archivo tarball de diseño de imagen OCI en el cliente.

Clave de atributo:

• dest - ruta de destino donde se escribirá el archivo tarball. "-" escribe en la salida estándar (stdout).

Para obtener más información, consulta Exportadores OCI y Docker.

docker

El tipo de exportación docker escribe la imagen resultante de una sola plataforma como un archivo tarball de especificación de imagen Docker en el cliente. Los tarballs creados por este exportador también son compatibles con OCI.

El almacenamiento de imágenes predeterminado en Docker Engine no admite la carga de imágenes multiplataforma. Puedes habilitar el almacenamiento de imágenes de containerd, o subir directamente las imágenes multiplataforma a un registro; consulta registry.

Claves de atributo:

• dest - ruta de destino donde se escribirá el archivo tarball. Si no se especifica, el archivo tar se cargará automáticamente en el almacenamiento de imágenes local.
• context - nombre del contexto de Docker donde importar el resultado

Para obtener más información, consulta Exportadores OCI y Docker.

image

El exportador image escribe el resultado de la construcción como una imagen o una lista de manifiestos. Cuando se utiliza el controlador docker, la imagen aparecerá en docker images. Opcionalmente, la imagen se puede subir automáticamente a un registro especificando atributos.

Claves de atributo:

• name - nombre (referencias) de la nueva imagen.
• push - booleano para subir automáticamente la imagen.

Para obtener más información, consulta Exportadores de imágenes y de registros.

registry

El exportador registry es un atajo para type=image,push=true.

Para obtener más información, consulta Exportadores de imágenes y de registros.

Establecer las plataformas de destino para la construcción (--platform)

--platform=value[,value]

Establece la plataforma de destino para la construcción. Todos los comandos FROM dentro del Dockerfile que no tengan su propia bandera --platform descargarán imágenes base para esta plataforma, y este valor también será la plataforma de la imagen resultante.

El valor predeterminado es la plataforma del demonio de BuildKit donde se ejecuta la construcción. El valor toma la forma de sistema_operativo/arquitectura o sistema_operativo/arquitectura/variante. Por ejemplo, linux/amd64 o linux/arm/v7. Además, la bandera --platform también admite el valor especial local, que le indica a BuildKit que utilice la plataforma del cliente de BuildKit que invoca la construcción.

Al usar el controlador docker-container con buildx, esta bandera puede aceptar múltiples valores como entrada separados por una coma. Con múltiples valores, el resultado se construirá para todas las plataformas especificadas y se unirá en una sola lista de manifiestos.

Si el Dockerfile necesita invocar el comando RUN, el builder requiere soporte en tiempo de ejecución para la plataforma especificada. En una instalación limpia, solo puedes ejecutar comandos RUN para la arquitectura de tu sistema. Si tu kernel admite lanzadores binfmt_misc para arquitecturas secundarias, buildx los detectará automáticamente. Las versiones de Docker Desktop vienen con binfmt_misc configurado automáticamente para las arquitecturas arm64 y arm. Puedes ver qué plataformas de tiempo de ejecución admite tu instancia de builder actual ejecutando docker buildx inspect --bootstrap.

Dentro de un Dockerfile, puedes acceder al valor de la plataforma actual a través del argumento de construcción TARGETPLATFORM. Consulta la referencia de Dockerfile para ver la descripción completa de las variantes de argumentos automáticos de plataforma.

Puedes encontrar la definición de formato para el especificador de plataforma en el código fuente de containerd.

$ docker buildx build --platform=linux/arm64 .
$ docker buildx build --platform=linux/amd64,linux/arm64,linux/arm/v7 .
$ docker buildx build --platform=darwin .

Establecer el tipo de salida de progreso (--progress)

--progress=VALUE

Establece el tipo de salida de progreso. Los valores admitidos son:

• auto (predeterminado): Utiliza el modo tty si el cliente es una TTY, o plain en caso contrario.
• tty: Un flujo interactivo de la salida con color y rediseño.
• plain: Imprime el progreso bruto de la construcción en un formato de texto plano.
• quiet: Suprime la salida de la construcción e imprime el ID de la imagen si tiene éxito (lo mismo que --quiet).
• rawjson: Imprime el progreso bruto de la construcción como líneas JSON.

Note

También puedes usar la variable de entorno BUILDKIT_PROGRESS para establecer su valor.

El siguiente ejemplo utiliza la salida plain durante la construcción:

$ docker buildx build --load --progress=plain .

#1 [internal] load build definition from Dockerfile
#1 transferring dockerfile: 227B 0.0s done
#1 DONE 0.1s

#2 [internal] load .dockerignore
#2 transferring context: 129B 0.0s done
#2 DONE 0.0s
...

Note

Consulta también la variable de entorno BUILDKIT_COLORS para modificar los colores de la salida de la terminal.

La salida rawjson formatea (marshals) los eventos de estado de resolución de BuildKit en líneas JSON. Este modo está diseñado para ser leído por un programa externo.

Crear atestaciones de procedencia (--provenance)

Atajo para --attest=type=provenance, utilizado para configurar atestaciones de procedencia (provenance) para el resultado de la construcción. Por ejemplo, --provenance=mode=max se puede utilizar como abreviatura de --attest=type=provenance,mode=max.

Además, --provenance se puede usar con valores booleanos para habilitar o deshabilitar las atestaciones de procedencia. Por ejemplo, --provenance=false deshabilita todas las atestaciones de procedencia, mientras que --provenance=true las habilita todas.

De forma predeterminada, se creará una atestación de procedencia mínima para el resultado de la construcción. Ten en cuenta que el almacenamiento de imágenes predeterminado en Docker Engine no admite atestaciones. Las atestaciones de procedencia solo persisten para las imágenes subidas directamente a un registro si utilizas el almacenamiento de imágenes predeterminado. Alternativamente, puedes cambiar a utilizar el almacenamiento de imágenes de containerd.

Para obtener más información sobre las atestaciones de procedencia, consulta aquí.

Subir el resultado de la construcción a un registro (--push)

Atajo para --output=type=registry. Subirá automáticamente el resultado de la construcción al registro.

Crear atestaciones SBOM (--sbom)

Atajo para --attest=type=sbom, utilizado para configurar las atestaciones SBOM para el resultado de la construcción. Por ejemplo, --sbom=generator=<usuario>/<imagen-generadora> se puede utilizar como abreviatura de --attest=type=sbom,generator=<usuario>/<imagen-generadora>.

Además, --sbom se puede usar con valores booleanos para habilitar o deshabilitar las atestaciones SBOM. Por ejemplo, --sbom=false deshabilita todas las atestaciones SBOM.

Ten en cuenta que el almacenamiento de imágenes predeterminado en Docker Engine no admite atestaciones. Las atestaciones de procedencia solo persisten para las imágenes subidas directamente a un registro si utilizas el almacenamiento de imágenes predeterminado. Alternativamente, puedes cambiar a utilizar el almacenamiento de imágenes de containerd.

Para obtener más información, consulta aquí.

Secreto a exponer en la construcción (--secret)

--secret=[type=TYPE[,KEY=VALUE]

Expone secretos (credenciales de autenticación, tokens) en la construcción. Se puede montar un secreto en la construcción utilizando un montaje RUN --mount=type=secret en el Dockerfile. Para obtener más información sobre cómo utilizar secretos de construcción, consulta Secretos de construcción.

Los tipos admitidos son:

• type=file
• type=env

Buildx intenta detectar el type automáticamente si no está establecido. Si se define una variable de entorno con la misma clave que id, entonces Buildx utiliza type=env y el valor de la variable se convierte en el secreto. Si no se establece dicha variable de entorno, y tampoco se establece type, Buildx recurre a type=file.

type=file

Obtiene un secreto de construcción a partir de un archivo.

Sinopsis de type=file

$ docker buildx build --secret [type=file,]id=<ID>[,src=<FILEPATH>] .

Atributos de type=file

Uso de type=file

En el siguiente ejemplo, type=file se detecta automáticamente porque no se ha establecido ninguna variable de entorno que coincida con aws (el ID).

$ docker buildx build --secret id=aws,src=$HOME/.aws/credentials .

# syntax=docker/dockerfile:1
FROM python:3
RUN pip install awscli
RUN --mount=type=secret,id=aws,target=/root/.aws/credentials \
  aws s3 cp s3://... ...

type=env

Obtiene un secreto de construcción a partir de una variable de entorno.

Sinopsis de type=env

$ docker buildx build --secret [type=env,]id=<ID>[,env=<VARIABLE>] .

Atributos de type=env

Uso de type=env

En el siguiente ejemplo, type=env se detecta automáticamente porque se ha establecido una variable de entorno que coincide con el id.

$ SECRET_TOKEN=token docker buildx build --secret id=SECRET_TOKEN .

# syntax=docker/dockerfile:1
FROM node:alpine
RUN --mount=type=bind,target=. \
  --mount=type=secret,id=SECRET_TOKEN,env=SECRET_TOKEN \
  yarn run test

En el siguiente ejemplo, el argumento de construcción SECRET_TOKEN está configurado para contener el valor de la variable de entorno API_KEY.

$ API_KEY=token docker buildx build --secret id=SECRET_TOKEN,env=API_KEY .

También puedes especificar el nombre de la variable de entorno con src o source:

$ API_KEY=token docker buildx build --secret type=env,id=SECRET_TOKEN,src=API_KEY .

Note

Al especificar el nombre de la variable de entorno con src o source, es necesario configurar explícitamente type=env; de lo contrario, Buildx asumirá que el secreto es de tipo type=file y buscará un archivo con el nombre de src o source (en este caso, un archivo llamado API_KEY relativo al lugar donde se ejecutó el comando docker buildx build).

Tamaño de la memoria compartida para los contenedores de construcción (--shm-size)

Establece el tamaño de la memoria compartida asignada a los contenedores de construcción cuando se utilizan las instrucciones RUN.

El formato es <número><unidad>. El número debe ser mayor que 0. La unidad es opcional y puede ser b (bytes), k (kilobytes), m (megabytes), o g (gigabytes). Si omites la unidad, el sistema utiliza bytes.

Note

En la mayoría de los casos, se recomienda dejar que el builder determine automáticamente las configuraciones adecuadas. Los ajustes manuales solo deben considerarse cuando se requiere una optimización de rendimiento específica para escenarios de construcción complejos.

Socket o claves del agente SSH a exponer en la construcción (--ssh)

--ssh=default|<id>[=<socket>|<key>[,<key>]]

Esto puede ser útil cuando algunos comandos en tu Dockerfile necesitan autenticación SSH específica (por ejemplo, clonar un repositorio privado).

--ssh expone el socket o las claves del agente SSH a la construcción y se puede utilizar con el montaje RUN --mount=type=ssh.

Ejemplo para acceder a Gitlab usando un socket de agente SSH:

# syntax=docker/dockerfile:1
FROM alpine
RUN apk add --no-cache openssh-client
RUN mkdir -p -m 0700 ~/.ssh && ssh-keyscan gitlab.com >> ~/.ssh/known_hosts
RUN --mount=type=ssh ssh -q -T [email protected] 2>&1 | tee /hello
# "Welcome to GitLab, @GITLAB_USERNAME_ASSOCIATED_WITH_SSHKEY" debería imprimirse aquí
# con el tipo de progreso de construcción definido como `plain`.

$ eval $(ssh-agent)
$ ssh-add ~/.ssh/id_rsa
(Introduce tu frase de contraseña aquí)
$ docker buildx build --ssh default=$SSH_AUTH_SOCK .

Etiquetar una imagen (-t, --tag)

$ docker buildx build -t docker/apache:2.0 .

Este ejemplo realiza la construcción de la misma manera que el ejemplo anterior, pero luego etiqueta la imagen resultante. El nombre del repositorio será docker/apache y la etiqueta 2.0.

Obtén más información sobre etiquetas válidas.

Puedes aplicar múltiples etiquetas a una imagen. For ejemplo, puedes aplicar la etiqueta latest a una imagen recién construida y añadir otra etiqueta que haga referencia a una versión específica.

Por ejemplo, para etiquetar una imagen tanto como docker/fedora-jboss:latest como docker/fedora-jboss:v2.1, utiliza lo siguiente:

$ docker buildx build -t docker/fedora-jboss:latest -t docker/fedora-jboss:v2.1 .

Especificar la etapa de construcción de destino (--target)

Al construir un Dockerfile con múltiples etapas de construcción, utiliza la opción --target para especificar una etapa de construcción intermedia por su nombre como la etapa final para la imagen resultante. El builder omitirá los comandos posteriores a la etapa de destino.

FROM debian AS build-env
# ...

FROM alpine AS production-env
# ...

$ docker buildx build -t mybuildimage --target build-env .

Establecer ulimits (--ulimit)

--ulimit sobrescribe los ulimits predeterminados de los contenedores de la construcción cuando se utilizan instrucciones RUN, y se especifican con un límite blando (soft) y duro (hard) de la siguiente manera: <tipo>=<límite blando>[:<límite duro>]; por ejemplo:

$ docker buildx build --ulimit nofile=1024:1024 .

Note

Si no proporcionas un límite duro, el límite blando se utiliza para ambos valores. Si no se establecen ulimits, se heredan de los ulimits predeterminados configurados en el demonio.

Note

En la mayoría de los casos, se recomienda dejar que el builder determine automáticamente las configuraciones adecuadas. Los ajustes manuales solo deben considerarse cuando se requiere una optimización de rendimiento específica para escenarios de construcción complejos.