# docker buildx build **Descripción:** Inicia una construcción **Uso:** `docker buildx build [OPTIONS] PATH | URL | -` **Alias:** `docker build`, `docker builder build`, `docker image build`, `docker buildx b` ## Descripción El comando `docker buildx build` inicia una construcción utilizando BuildKit. ## Opciones | Opción | Predeterminado | Descripción | | ------------------------------------------------------------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | `--add-host` | | Añade un mapeo personalizado de host a IP (formato: `host:ip`) | | `--allow` | | Permite concesiones de privilegios adicionales (por ejemplo, `network.host`, `security.insecure`, `device`)
| | `--annotation` | | Añade una anotación a la imagen | | `--attest` | | Parámetros de atestación (formato: `type=sbom,generator=image`) | | `--build-arg` | | Establece variables en tiempo de construcción | | `--build-context` | | Contextos de construcción adicionales (por ejemplo, name=path) | | `--cache-from` | | Fuentes de caché externas (por ejemplo, `user/app:cache`, `type=local,src=ruta/al/directorio`)
| | `--cache-to` | | Destinos de exportación de caché (por ejemplo, `user/app:cache`, `type=local,dest=ruta/al/directorio`)
| | `--call` | `build` | Establece el método para evaluar la construcción (`check`, `outline`, `targets`) | | `--cgroup-parent` | | Establece el cgroup primario para las instrucciones `RUN` durante la construcción | | `--check` | | Atajo para `--call=check` | | `-f`, `--file` | | Nombre del Dockerfile (predeterminado: `PATH/Dockerfile`) | | `--iidfile` | | Escribe el ID de la imagen en un archivo | | `--label` | | Establece los metadatos de una imagen | | `--load` | | Atajo para `--output=type=docker` | | `--metadata-file` | | Escribe los metadatos del resultado de la construcción en un archivo | | `--network` | | Establece el modo de red para las instrucciones `RUN` durante la construcción | | `--no-cache` | | No utiliza la caché al construir la imagen | | `--no-cache-filter` | | No almacena en caché las etapas especificadas | | `-o`, `--output` | | Destino de salida (formato: `type=local,dest=ruta`) | | `--platform` | | Establece la plataforma de destino para la construcción | | `--policy` | | Configuración de política (formato: `filename=ruta[,filename=ruta][,reset=true|false][,disabled=true|false][,strict=true|false][,log-level=nivel]`)
| | `--progress` | `auto` | Establece el tipo de salida de progreso (`auto`, `none`, `plain`, `quiet`, `rawjson`, `tty`). Usa plain para mostrar la salida del contenedor
| | `--provenance` | | Atajo para `--attest=type=provenance` | | `--pull` | | Intenta siempre descargar (pull) todas las imágenes referenciadas | | `--push` | | Atajo para `--output=type=registry,unpack=false` | | `-q`, `--quiet` | | Suprime la salida de la construcción e imprime el ID de la imagen si tiene éxito | | `--sbom` | | Atajo para `--attest=type=sbom` | | `--secret` | | Secreto a exponer en la construcción (formato: `id=mysecret[,src=/local/secret]`)
| | `--shm-size` | | Tamaño de la memoria compartida para los contenedores de construcción | | `--ssh` | | Socket o claves del agente SSH a exponer en la construcción (formato: `default|[=|[,]]`)
| | `-t`, `--tag` | | Identificador de imagen (formato: `[registry/]repository[:tag]`) | | `--target` | | Establece la etapa de construcción de destino a construir | | `--ulimit` | | Opciones de ulimit | ## Ejemplos ### Añadir entradas al archivo hosts del contenedor (--add-host) {#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`: ```console $ 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. ```console $ 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: ```console $ docker buildx build --add-host my-hostname:10.180.0.1 --add-host my-hostname_v6=[2001:4860:4860::8888] . ``` ### Crear anotaciones (--annotation) {#annotation} ```text --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: ```console $ 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: ```console $ 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: ```console $ 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`: ```console $ 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](/build/building/annotations/). ### Crear atestaciones (--attest) {#attest} ```text --attest=type=sbom,... --attest=type=provenance,... ``` Crea [atestaciones de imagen](/build/metadata/attestations/). 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](#sbom). Para obtener más información, consulta [aquí](/build/metadata/attestations/sbom/). - `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](#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í](/build/metadata/attestations/slsa-provenance/). ### Permitir concesiones de privilegios adicionales (--allow) {#allow} ```text --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](/reference/dockerfile/#run---security). - `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`](/reference/cli/docker/buildx/create/#buildkitd-flags)). ```console $ 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) {#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`: ```console $ 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](/reference/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: ```console $ 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](/reference/cli/docker/container/run/#env) para obtener más información. También existen argumentos de construcción integrados muy útiles, tales como: * `BUILDKIT_CONTEXT_KEEP_GIT_DIR=`: activa el contexto de git para conservar el directorio `.git` * `BUILDKIT_INLINE_CACHE=`: inserta o no los metadatos de la caché en la configuración de la imagen * `BUILDKIT_MULTI_PLATFORM=`: opta por una salida determinante independientemente de si es multiplataforma o no ```console $ 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](/reference/dockerfile/#buildkit-built-in-build-args). ### Contextos de construcción adicionales (--build-context) {#build-context} ```text --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](https://github.com/opencontainers/image-spec/blob/main/image-layout.md) - una imagen de contenedor - una URL de Git - una URL HTTP #### Usar una ruta local {#local-path} Expone un directorio de origen local secundario: ```console $ 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 {#docker-image} Usa el esquema `docker-image://`. Reemplaza `alpine:latest` por uno específico: ```console $ docker buildx build --build-context alpine=docker-image://alpine@sha256:0123456789 . ``` ```dockerfile # syntax=docker/dockerfile:1 FROM alpine COPY --from=project myfile / ``` #### Usar un directorio de diseño OCI como contexto de construcción {#source-oci-layout} 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: ```console $ docker buildx build --build-context foo=oci-layout:///path/to/local/layout: $ docker buildx build --build-context foo=oci-layout:///path/to/local/layout@sha256: ``` ```dockerfile # 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](https://github.com/opencontainers/image-spec/blob/main/image-layout.md). ### Sobrescribir la instancia del builder configurada (--builder) {#builder} Igual que [`buildx --builder`](/reference/cli/docker/buildx/#builder). ### Usar una fuente de caché externa para una construcción (--cache-from) {#cache-from} ```text --cache-from=[NAME|type=TYPE[,KEY=VALUE]] ``` Usa una fuente de caché externa para una construcción. Los tipos admitidos son: - [`registry`](/build/cache/backends/registry/) puede importar la caché desde un manifiesto de caché o desde una configuración de imagen (especial) en el registro. - [`local`](/build/cache/backends/local/) puede importar la caché desde archivos locales exportados previamente con `--cache-to`. - [`gha`](/build/cache/backends/gha/) puede importar la caché desde una caché exportada previamente con `--cache-to` en tu repositorio de GitHub. - [`s3`](/build/cache/backends/s3/) puede importar la caché desde una caché exportada previamente con `--cache-to` en tu cubo (bucket) S3. - [`azblob`](/build/cache/backends/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. ```console $ 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é](/build/cache/backends/). ### Exportar la caché de construcción a un destino de caché externo (--cache-to) {#cache-to} ```text --cache-to=[NAME|type=TYPE[,KEY=VALUE]] ``` Exporta la caché de construcción a un destino de caché externo. Los tipos admitidos son: - [`registry`](/build/cache/backends/registry/) exporta la caché de construcción a un manifiesto de caché en el registro. - [`local`](/build/cache/backends/local/) exporta la caché a un directorio local en el cliente. - [`inline`](/build/cache/backends/inline/) escribe los metadatos de la caché en la configuración de la imagen. - [`gha`](/build/cache/backends/gha/) exporta la caché a través de la API del servicio de caché de GitHub Actions. - [`s3`](/build/cache/backends/s3/) exporta la caché a un cubo (bucket) S3. - [`azblob`](/build/cache/backends/azblob/) exporta la caché a un contenedor (bucket) de Azure. ```console $ 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é](/build/cache/backends/). ### Invocar un método frontend (--call) {#call} ```text --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](/reference/build-checks/) de forma predeterminada. Para Dockerfiles, los métodos disponibles son: | Comando | Descripción | | ------------------------------ | ------------------------------------------------------------------------------------------------------------------- | | `build` (predeterminado) | Ejecuta la construcción y evalúa las comprobaciones de construcción para el objetivo de construcción actual. | | `check` | Evalúa las comprobaciones de construcción para todo el Dockerfile o para el objetivo seleccionado, sin ejecutar una construcción. | | `outline` | Muestra los argumentos de construcción que puedes establecer para un objetivo y sus valores predeterminados. | | `targets` | Lista todos los objetivos de construcción en el Dockerfile. | | `subrequests.describe` | Lista todos los métodos frontend que admite el frontend actual. | 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`. ```console $ 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: ```dockerfile # 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: ```console $ 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](https://github.com/docker/docs/blob/main/Dockerfile). #### Call: check (--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. ```console $ 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: ```console $ 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: ```console $ 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. ```console $ 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) {#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](/reference/cli/docker/container/run/#cgroup-parent). ### Especificar un Dockerfile (-f, --file) {#file} ```console $ 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](#local-file-path) - [URL remota](#remote-url) - [Entrada estándar](#standard-input) #### Ruta de archivo local Para especificar una ruta a un Dockerfile local: ```console $ docker buildx build -f path/to/Dockerfile . ``` #### URL remota Para especificar una URL a un Dockerfile remoto: ```console $ 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: ```console $ cat Dockerfile | docker buildx build -f - . ``` ### Cargar el resultado de la construcción de una sola plataforma en `docker images` (--load) {#load} Atajo para [`--output=type=docker`](#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) {#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. ```console $ docker buildx build --load --metadata-file metadata.json . $ cat metadata.json ``` ```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](/build/metadata/attestations/slsa-provenance/#provenance-attestation-example)) > (`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) {#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](/reference/dockerfile/#run---network). ### Ignorar la caché de construcción para etapas específicas (--no-cache-filter) {#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: ```console $ docker buildx build --no-cache-filter stage1,stage2,stage3 . ``` Por ejemplo, el siguiente Dockerfile contiene cuatro etapas: - `base` - `install` - `test` - `release` ```dockerfile # 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`: ```console $ docker buildx build --no-cache-filter install . ``` Para ignorar la caché en las etapas `install` y `release`: ```console $ 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) {#output} ```text -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](/build/builders/drivers/), 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](/build/exporters/) `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). ```console $ 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`](#local) - [`tar`](#tar) - [`oci`](#oci) - [`docker`](#docker) - [`image`](#image) - [`registry`](#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](/build/exporters/local-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](/build/exporters/local-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](https://github.com/opencontainers/image-spec/blob/v1.0.1/image-layout.md) 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](/build/exporters/oci-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](https://github.com/docker/docker/blob/v20.10.2/image/spec/v1.2.md) 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`](#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](/build/exporters/oci-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](/build/exporters/image-registry/). #### `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](/build/exporters/image-registry/). ### Establecer las plataformas de destino para la construcción (--platform) {#platform} ```text --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`](https://en.wikipedia.org/wiki/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](/reference/dockerfile/#automatic-platform-args-in-the-global-scope) 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](https://github.com/containerd/containerd/blob/v1.4.3/platforms/platforms.go#L63). ```console $ 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} ```text --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: ```console $ 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`](/build/building/variables/#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) {#provenance} Atajo para [`--attest=type=provenance`](#attest), 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í](/build/metadata/attestations/slsa-provenance/). ### Subir el resultado de la construcción a un registro (--push) {#push} Atajo para [`--output=type=registry`](#registry). Subirá automáticamente el resultado de la construcción al registro. ### Crear atestaciones SBOM (--sbom) {#sbom} Atajo para [`--attest=type=sbom`](#attest), utilizado para configurar las atestaciones SBOM para el resultado de la construcción. Por ejemplo, `--sbom=generator=/` se puede utilizar como abreviatura de `--attest=type=sbom,generator=/`. 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í](/build/metadata/attestations/sbom/). ### Secreto a exponer en la construcción (--secret) {#secret} ```text --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](/reference/dockerfile/#run---mounttypesecret). Para obtener más información sobre cómo utilizar secretos de construcción, consulta [Secretos de construcción](/build/building/secrets/). Los tipos admitidos son: - [`type=file`](#typefile) - [`type=env`](#typeenv) 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` ```console $ docker buildx build --secret [type=file,]id=[,src=] . ``` ##### Atributos de `type=file` | Clave | Descripción | Predeterminado | | --------------- | ----------------------------------------------------------------------------------------------------- | -------------------------- | | `id` | ID del secreto. | N/A (esta clave es requerida) | | `src`, `source` | Ruta del archivo que contiene el valor del secreto (absoluta o relativa al directorio de trabajo actual). | `id` si no está configurada. | ###### 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). ```console $ docker buildx build --secret id=aws,src=$HOME/.aws/credentials . ``` ```dockerfile # 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` ```console $ docker buildx build --secret [type=env,]id=[,env=] . ``` ##### Atributos de `type=env` | Clave | Descripción | Predeterminado | | ---------------------- | ----------------------------------------------- | -------------------------- | | `id` | ID del secreto. | N/A (esta clave es requerida) | | `env`, `src`, `source` | Variable de entorno de la cual obtener el secreto. | `id` si no está configurada. | ##### 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`. ```console $ SECRET_TOKEN=token docker buildx build --secret id=SECRET_TOKEN . ``` ```dockerfile # 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`. ```console $ 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`: ```console $ 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) {#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 ``. 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} ```text --ssh=default|[=|[,]] ``` 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](/reference/dockerfile/#run---mounttypessh). Ejemplo para acceder a Gitlab usando un socket de agente SSH: ```dockerfile # 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 git@gitlab.com 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`. ``` ```console $ 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) {#tag} ```console $ 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](/reference/cli/docker/image/tag/). 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: ```console $ docker buildx build -t docker/fedora-jboss:latest -t docker/fedora-jboss:v2.1 . ``` ### Especificar la etapa de construcción de destino (--target) {#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. ```dockerfile FROM debian AS build-env # ... FROM alpine AS production-env # ... ``` ```console $ docker buildx build -t mybuildimage --target build-env . ``` ### Establecer ulimits (--ulimit) {#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: `=[:]`; por ejemplo: ```console $ 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.