docker buildx bake

Descripción

Bake es un comando de construcción de alto nivel. Cada objetivo (target) especificado se ejecuta en paralelo como parte de la construcción.

Consulta la guía Opciones de construcción de alto nivel con Bake para una introducción a la escritura de archivos bake.

Note

El comando buildx bake podría recibir características incompatibles con versiones anteriores en el futuro si fuera necesario. Buscamos comentarios para mejorar el comando y ampliar su funcionalidad.

Opciones

Ejemplos

Permitir concesiones de privilegios adicionales (--allow)

--allow=ENTITLEMENT[=VALUE]

Las concesiones de privilegios (entitlements) están diseñadas para proporcionar un acceso controlado a operaciones privilegiadas. Por defecto, Buildx y BuildKit operan con permisos restringidos para proteger a los usuarios y sus sistemas de efectos secundarios no deseados o riesgos de seguridad. La bandera --allow otorga explícitamente acceso a concesiones adicionales, dejando claro cuándo una operación de construcción o bake requiere privilegios elevados.

Además de las concesiones network.host y security.insecure de BuildKit (consulta docker buildx build --allow), Bake admite concesiones de sistema de archivos que otorgan un control granular sobre el acceso al sistema de archivos. Esto es especialmente útil cuando se trabaja con construcciones que necesitan acceder a archivos fuera del directorio de trabajo predeterminado.

Bake admite las siguientes concesiones de sistema de archivos:

• --allow fs=<path|*> - Otorga acceso de lectura y escritura a archivos fuera del directorio de trabajo.
• --allow fs.read=<path|*> - Otorga acceso de lectura a archivos fuera del directorio de trabajo.
• --allow fs.write=<path|*> - Otorga acceso de escritura a archivos fuera del directorio de trabajo.

Las concesiones fs toman un valor de ruta (relativa o absoluta) a un directorio en el sistema de archivos. Alternativamente, puedes pasar un comodín (*) para permitir que Bake acceda a todo el sistema de archivos.

Ejemplo: fs.read

Dada la siguiente configuración de Bake, Bake necesitaría acceder al directorio principal, relativo al archivo Bake.

target "app" {
  context = "../src"
}

Suponiendo que docker buildx bake app se ejecute en el mismo directorio que el archivo docker-bake.hcl, tendrías que permitir explícitamente que Bake lea del directorio ../src. En este caso, todas las siguientes invocaciones funcionan:

$ docker buildx bake --allow fs.read=* app
$ docker buildx bake --allow fs.read=../src app
$ docker buildx bake --allow fs=* app

Ejemplo: fs.write

El siguiente archivo docker-bake.hcl requiere acceso de escritura al directorio /tmp.

target "app" {
  output = "/tmp"
}

Suponiendo que docker buildx bake app se ejecute fuera del directorio /tmp, tendrías que permitir la concesión fs.write, ya sea especificando la ruta o utilizando un comodín:

$ docker buildx bake --allow fs=/tmp app
$ docker buildx bake --allow fs.write=/tmp app
$ docker buildx bake --allow fs.write=* app

Sobrescribir la instancia del builder configurada (--builder)

Igual que buildx --builder.

Invocar un método frontend (--call)

Igual que build --call.

Call: check (--check)

Igual que build --check.

Especificar un archivo de definición de construcción (-f, --file)

Utiliza la opción -f / --file para especificar el archivo de definición de construcción a utilizar. El archivo puede ser un archivo HCL, JSON o Compose. Si se especifican múltiples archivos, se leen todos y se combinan las configuraciones de construcción.

Alternativamente, se puede utilizar la variable de entorno BUILDX_BAKE_FILE para especificar la definición de construcción que se va a utilizar. Esto es mutuamente excluyente con -f / --file; si se especifican ambos, se ignora la variable de entorno. Se pueden especificar múltiples definiciones separándolas con el separador de rutas del sistema (normalmente ; en Windows y : en otros sistemas), pero esto se puede cambiar con BUILDX_BAKE_PATH_SEPARATOR.

Puedes pasar los nombres de los objetivos a construir para compilar solo objetivos específicos. El siguiente ejemplo construye los objetivos db y webapp-release definidos en el archivo docker-bake.dev.hcl:

# docker-bake.dev.hcl
group "default" {
  targets = ["db", "webapp-dev"]
}

target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp"]
}

target "webapp-release" {
  inherits = ["webapp-dev"]
  platforms = ["linux/amd64", "linux/arm64"]
}

target "db" {
  dockerfile = "Dockerfile.db"
  tags = ["docker.io/username/db"]
}

$ docker buildx bake -f docker-bake.dev.hcl db webapp-release

Consulta la referencia del archivo Bake para obtener más detalles.

Listar objetivos (targets) y variables (--list)

La bandera --list muestra todos los objetivos o variables disponibles en la configuración de Bake, junto con una descripción (si se estableció mediante la propiedad description en el archivo Bake).

Para listar todos los objetivos:

$ docker buildx bake --list=targets
TARGET              DESCRIPTION
binaries
default             binaries
update-docs
validate
validate-golangci   Validate .golangci.yml schema (does not run Go linter)

Para listar las variables:

$ docker buildx bake --list=variables
VARIABLE      TYPE      VALUE                DESCRIPTION
REGISTRY      string    docker.io/username   Registry and namespace
IMAGE_NAME    string    my-app               Image name
GO_VERSION              <null>
DEBUG         bool      false                Add debug symbols

Los tipos de variables se mostrarán cuando se establezcan utilizando la propiedad type en el archivo Bake.

La opción --list=variables muestra las variables definidas en el archivo Bake, incluyendo sus descripciones y valores predeterminados.

Ejemplo: listar variables con descripciones

variable "GO_VERSION" {
  default     = "1.22"
  description = "Go version used for building the application"
}

$ docker buildx bake --list=variables

NAME          DESCRIPTION                                      DEFAULT
GO_VERSION    Go version used for building the application     1.22

De forma predeterminada, la salida de docker buildx bake --list se presenta en formato de tabla. Alternativamente, puedes utilizar una sintaxis CSV de formato largo y especificar un atributo format para generar la lista en JSON.

$ docker buildx bake --list=type=targets,format=json

Cargar imágenes en Docker (--load)

La bandera --load es un atajo conveniente para añadir una exportación de imagen del tipo docker:

--load   ≈   --set=*.output=type=docker

Sin embargo, su comportamiento es condicional:

• Si la definición de construcción no tiene una salida definida, --load añade type=docker.
• Si las salidas de la definición de construcción son docker, image, registry, oci, --load añadirá una exportación type=docker si una no estuviera ya presente.
• Si la definición de construcción contiene salidas local o tar, --load no realiza ninguna acción. No sobrescribirá esas salidas.

Por ejemplo, con el siguiente archivo bake:

target "default" {
  output = ["type=tar,dest=hi.tar"]
}

Con --load:

$ docker buildx bake --load --print
...
"output": [
  {
    "dest": "hi.tar"
    "type": "tar",
   }
]

La salida tar permanece sin cambios.

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

Similar a buildx build --metadata-file pero escribe un mapa de resultados para cada objetivo como el siguiente:

# docker-bake.hcl
group "default" {
  targets = ["db", "webapp-dev"]
}

target "db" {
  dockerfile = "Dockerfile.db"
  tags = ["docker.io/username/db"]
}

target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp"]
}

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

{
  "buildx.build.warnings": {},
  "db": {
    "buildx.build.provenance": {},
    "buildx.build.ref": "mybuilder/mybuilder0/0fjb6ubs52xx3vygf6fgdl611",
    "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"
  },
  "webapp-dev": {
    "buildx.build.provenance": {},
    "buildx.build.ref": "mybuilder/mybuilder0/kamngmcgyzebqxwu98b4lfv3n",
    "containerimage.config.digest": "sha256:9651cc2b3c508f697c9c43b67b64c8359c2865c019e680aac1c11f4b875b67e0",
    "containerimage.descriptor": {
      "annotations": {
        "config.digest": "sha256:9651cc2b3c508f697c9c43b67b64c8359c2865c019e680aac1c11f4b875b67e0",
        "org.opencontainers.image.created": "2022-02-08T21:28:15Z"
      },
      "digest": "sha256:6d9ac9237a84afe1516540f40a0fafdc86859b2141954b4d643af7066d598b74",
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "size": 506
    },
    "containerimage.digest": "sha256:6d9ac9237a84afe1516540f40a0fafdc86859b2141954b4d643af7066d598b74"
  }
}

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.

No usar caché al construir la imagen (--no-cache)

Igual que build --no-cache. No utiliza la caché al construir la imagen.

Imprimir las opciones sin construir (--print)

Imprime las opciones resultantes de los objetivos que se desean construir, en formato JSON, sin iniciar una construcción.

$ docker buildx bake -f docker-bake.hcl --print db
{
  "group": {
    "default": {
      "targets": [
        "db"
      ]
    }
  },
  "target": {
    "db": {
      "context": "./",
      "dockerfile": "Dockerfile",
      "tags": [
        "docker.io/tiborvass/db"
      ]
    }
  }
}

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

Igual que build --progress.

Crear atestaciones de procedencia (--provenance)

Igual que build --provenance.

Intentar siempre descargar una versión más reciente de la imagen (--pull)

Igual que build --pull.

Subir imágenes a un registro (--push)

La bandera --push sigue la misma lógica que --load:

• Si no se definen salidas, añade una exportación type=image,push=true.
• Para las salidas image existentes, establece push=true.
• Si las salidas están configuradas como local o tar, no las sobrescribe.

Crear atestaciones SBOM (--sbom)

Igual que build --sbom.

Sobrescribir las configuraciones de los objetivos desde la línea de comandos (--set)

--set targetpattern.key[.subkey]=value

Sobrescribe las configuraciones de los objetivos desde la línea de comandos. La sintaxis de coincidencia de patrones se define en https://golang.org/pkg/path/#Match.

$ docker buildx bake --set target.args.mybuildarg=value
$ docker buildx bake --set target.platform=linux/arm64
$ docker buildx bake --set foo*.args.mybuildarg=value   # sobrescribe build arg para todos los objetivos que comienzan con 'foo'
$ docker buildx bake --set *.platform=linux/arm64       # sobrescribe plataforma para todos los objetivos
$ docker buildx bake --set foo*.no-cache                # omite la caché solo para los objetivos que comienzan con 'foo'
$ docker buildx bake --set target.platform+=linux/arm64 # añade 'linux/arm64' a la lista de plataformas
$ docker buildx bake --set target.contexts.bar=../bar   # sobrescribe el contexto con nombre 'bar'

Note

--set es una bandera repetible. Para campos de matriz como tags, repite --set para proporcionar múltiples valores o utiliza el operador += para añadirlos sin reemplazarlos. No se admite la sintaxis literal de matriz como --set target.tags=[a,b].

Puedes sobrescribir los siguientes campos:

• annotations
• attest
• args
• cache-from
• cache-to
• call
• context
• contexts
• dockerfile
• entitlements
• extra-hosts
• labels
• load
• no-cache
• no-cache-filter
• output
• platform
• pull
• push
• secrets
• ssh
• tags
• target

Puedes añadir elementos utilizando el operador += para los siguientes campos:

• annotations¹
• attest¹
• cache-from
• cache-to
• entitlements¹
• no-cache-filter
• output
• platform
• secrets
• ssh
• tags

Note

¹ Estos campos ya añaden elementos de forma predeterminada.