Vista general de los exportadores

Los exportadores guardan los resultados de tu compilación en un tipo de salida específico. Especificas el exportador a utilizar con la opción de CLI --output. Buildx admite los siguientes exportadores:

• image: exporta el resultado de la compilación a una imagen de contenedor.
• registry: exporta el resultado de la compilación a una imagen de contenedor y la sube al registro especificado.
• local: exporta el sistema de archivos raíz de la compilación a un directorio local.
• tar: empaqueta el sistema de archivos raíz de la compilación en un archivo tar local.
• oci: exporta el resultado de la compilación al sistema de archivos local en el formato distribución de imagen OCI (OCI image layout).
• docker: exporta el resultado de la compilación al sistema de archivos local en el formato Especificación de Imagen de Docker v1.2.0 (Docker Image Specification v1.2.0).
• cacheonly: no exporta una salida de compilación, sino que ejecuta la compilación y crea una caché.

Uso de exportadores

Para especificar un exportador, utiliza la siguiente sintaxis de comando:

$ docker buildx build --tag <registry>/<image> \
  --output type=<TYPE> .

Los casos de uso más comunes no requieren que especifiques explícitamente qué exportador utilizar. Solo necesitas especificar el exportador si deseas personalizar la salida o si quieres guardarla en el disco. Las opciones --load y --push permiten que Buildx infiera las configuraciones de exportación a utilizar.

Por ejemplo, si utilizas la opción --push en combinación con --tag, Buildx utiliza automáticamente el exportador image y lo configura para subir los resultados al registro especificado.

Para obtener la máxima flexibilidad de los diversos exportadores que ofrece BuildKit, utilizas la bandera --output que te permite configurar las opciones del exportador.

Casos de uso

Cada tipo de exportador está diseñado para diferentes casos de uso. Las siguientes secciones describen algunos escenarios comunes y cómo puedes utilizar los exportadores para generar la salida que necesitas.

Cargar al almacenamiento de imágenes (image store)

Buildx se utiliza a menudo para compilar imágenes de contenedor que se pueden cargar en un almacenamiento de imágenes. Ahí es donde entra el exportador docker. El siguiente ejemplo muestra cómo compilar una imagen utilizando el exportador docker y cargarla en el almacenamiento de imágenes local mediante la opción --output:

$ docker buildx build \
  --output type=docker,name=<registry>/<image> .

La CLI de Buildx utilizará automáticamente el exportador docker y lo cargará en el almacenamiento de imágenes si proporcionas las opciones --tag y --load:

$ docker buildx build --tag <registry>/<image> --load .

Las imágenes compiladas utilizando el controlador docker se cargan automáticamente en el almacenamiento de imágenes local.

Las imágenes cargadas en el almacenamiento de imágenes están disponibles para docker run inmediatamente después de que finalice la compilación, y las verás en la lista de imágenes al ejecutar el comando docker images.

Subir a un registro

Para subir una imagen compilada a un registro de contenedores, puedes utilizar los exportadores registry o image.

Al pasar la opción --push a la CLI de Buildx, indicas a BuildKit que suba la imagen compilada al registro especificado:

$ docker buildx build --tag <registry>/<image> --push .

Internamente, esto utiliza el exportador image y establece el parámetro push. Es equivalente a utilizar el siguiente comando en su forma larga mediante la opción --output:

$ docker buildx build \
  --output type=image,name=<registry>/<image>,push=true .

También puedes utilizar el exportador registry, que hace lo mismo:

$ docker buildx build \
  --output type=registry,name=<registry>/<image> .

Exportar la distribución de la imagen (image layout) a un archivo

Puedes utilizar los exportadores oci o docker para guardar los resultados de la compilación en una distribución de imagen en tu sistema de archivos local. Ambos exportadores generan un archivo de archivo tar que contiene la distribución de imagen correspondiente. El parámetro dest define la ruta de salida de destino para el archivo tar.

$ docker buildx build --output type=oci,dest=./image.tar .
[+] Building 0.8s (7/7) FINISHED
 ...
 => exporting to oci image format                                                                     0.0s
 => exporting layers                                                                                  0.0s
 => exporting manifest sha256:c1ef01a0a0ef94a7064d5cbce408075730410060e253ff8525d1e5f7e27bc900        0.0s
 => exporting config sha256:eadab326c1866dd247efb52cb715ba742bd0f05b6a205439f107cf91b3abc853          0.0s
 => sending tarball                                                                                   0.0s
$ mkdir -p out && tar -C out -xf ./image.tar
$ tree out
out
├── blobs
│   └── sha256
│       ├── 9b18e9b68314027565b90ff6189d65942c0f7986da80df008b8431276885218e
│       ├── c78795f3c329dbbbfb14d0d32288dea25c3cd12f31bd0213be694332a70c7f13
│       ├── d1cf38078fa218d15715e2afcf71588ee482352d697532cf316626164699a0e2
│       ├── e84fa1df52d2abdfac52165755d5d1c7621d74eda8e12881f6b0d38a36e01775
│       └── fe9e23793a27fe30374308988283d40047628c73f91f577432a0d05ab0160de7
├── index.json
├── manifest.json
└── oci-layout

Exportar el sistema de archivos

Si no deseas compilar una imagen a partir de los resultados de tu compilación, sino exportar el sistema de archivos que se compiló, puedes utilizar los exportadores local y tar.

El exportador local desempaqueta el sistema de archivos en una estructura de directorios en la ubicación especificada. El exportador tar crea un archivo tar.

$ docker buildx build --output type=local,dest=<path/to/output> .

El exportador local es útil en compilaciones multi-etapa (multi-stage builds) ya que te permite exportar una cantidad mínima de artefactos de compilación, como binarios autocontenidos.

Exportación solo de caché

El exportador cacheonly se puede utilizar para ejecutar una compilación sin exportar ninguna salida. Esto puede resultar útil si, por ejemplo, deseas ejecutar una compilación de prueba. O si deseas ejecutar la compilación primero y crear las exportaciones mediante comandos posteriores. El exportador cacheonly crea una caché de compilación, por lo que las compilaciones sucesivas son instantáneas.

$ docker buildx build --output type=cacheonly

Si no especificas un exportador y no proporcionas opciones abreviadas como --load (que selecciona automáticamente el exportador adecuado), Buildx utiliza por defecto el exportador cacheonly. La excepción es si compilas utilizando el controlador docker, en cuyo caso se utiliza el exportador docker.

Buildx registra un mensaje de advertencia cuando utiliza cacheonly por defecto:

$ docker buildx build .
WARNING: No output specified with docker-container driver.
         Build result will only remain in the build cache.
         To push result image into registry use --push or
         to load image into docker use --load

Múltiples exportadores

Puedes utilizar múltiples exportadores para cualquier compilación especificando la bandera --output varias veces. Esto requiere tanto Buildx como BuildKit versión 0.13.0 o posterior.

El siguiente ejemplo ejecuta una sola compilación utilizando tres exportadores diferentes:

• El exportador registry para subir la imagen a un registro
• El exportador local para extraer los resultados de la compilación al sistema de archivos local
• La bandera --load (una abreviatura del exportador image) para cargar los resultados en el almacenamiento de imágenes local.

$ docker buildx build \
  --output type=registry,tag=<registry>/<image> \
  --output type=local,dest=<path/to/output> \
  --load .

Opciones de configuración

Esta sección describe algunas opciones de configuración disponibles para los exportadores.

Las opciones descritas aquí son comunes para al menos dos o más tipos de exportadores. Además, los diferentes tipos de exportadores también admiten parámetros específicos. Consulta la página detallada de cada exportador para obtener más información sobre qué parámetros de configuración se aplican.

Los parámetros comunes descritos aquí son:

• Compresión
• Tipos de medio OCI (OCI media types)

Compresión

Al exportar una salida comprimida, puedes configurar el algoritmo y el nivel de compresión exactos a utilizar. Aunque los valores predeterminados proporcionan una buena experiencia inicial, puedes ajustar los parámetros para optimizar los costos de almacenamiento frente a los de procesamiento. Cambiar los parámetros de compresión puede reducir el espacio de almacenamiento requerido y mejorar los tiempos de descarga de las imágenes, pero aumentará los tiempos de compilación.

Para seleccionar el algoritmo de compresión, puedes utilizar la opción compression. Por ejemplo, para compilar una image con compression=zstd:

$ docker buildx build \
  --output type=image,name=<registry>/<image>,push=true,compression=zstd .

Utiliza la opción compression-level=<valor> junto con el parámetro compression para elegir un nivel de compresión para los algoritmos que lo admiten:

• 0-9 para gzip y estargz
• 0-22 para zstd

Como regla general, cuanto mayor sea el número, más pequeño será el archivo resultante y más tiempo tardará en ejecutarse la compresión.

Utiliza la opción force-compression=true para forzar la recompresión de las capas importadas de una imagen anterior, si el algoritmo de compresión solicitado es diferente del algoritmo de compresión anterior.

Note

Los métodos de compresión gzip y estargz utilizan el paquete compress/gzip, mientras que zstd utiliza el paquete github.com/klauspost/compress/zstd.

Niveles de compresión zstd

Al especificar compression=zstd, el parámetro compression-level acepta valores de 0 a 22. BuildKit mapea estos valores a cuatro niveles de compresión internos:

Por ejemplo, establecer compression-level=5 y compression-level=6 produce el mismo resultado de compresión, ya que ambos se mapean al nivel interno "Predeterminado".

Tipos de medio OCI

Los exportadores image, registry, oci y docker crean imágenes de contenedor. Estos exportadores admiten tanto los tipos de medio de Docker (predeterminado) como los tipos de medio de OCI.

Para exportar imágenes con los tipos de medio de OCI establecidos, utiliza la propiedad oci-mediatypes.

$ docker buildx build \
  --output type=image,name=<registry>/<image>,push=true,oci-mediatypes=true .

Qué sigue

Lee sobre cada uno de los exportadores para aprender cómo funcionan y cómo utilizarlos:

• Exportadores de imagen y de registro (Image and registry exporters)
• Exportadores OCI y Docker (OCI and Docker exporters)
• Exportadores local y tar (Local and tar exporters)