docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #18116 from dvdksn/build-tier1-freshness 

build: tier 1 docs freshness
This commit is contained in:
David Karlsson 2023-09-07 17:29:27 +02:00 committed by GitHub
parent 0bd9426372 63fd22cd50
commit b80744c552
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
49 changed files with 1001 additions and 1224 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
content/build/attestations/_index.md
View File

@ -1,16 +1,11 @@
---
title: Build attestations
keywords: build, attestations, sbom, provenance
description: 'Introduction to SBOM and provenance attestations with Docker Build;
what they are and why they exist
'
keywords: build, attestations, sbom, provenance, metadata
description: |
Introduction to SBOM and provenance attestations with Docker Build,
what they are, and why they exist
---
> **Note**
>
> This feature is supported in BuildKit version `>=0.11` and Buildx version `>=0.10`.
Build attestations describe how an image was built, and what it contains. The
attestations are created at build-time by BuildKit, and become attached to the
final image as metadata.
@ -67,11 +62,8 @@ index in a manifest for the final image.
## Storage
<!-- prettier-ignore -->
BuildKit produces attestations in the
[in-toto format](https://github.com/in-toto/attestation),
as defined by the
[in-toto framework](https://in-toto.io/),
BuildKit produces attestations in the [in-toto format](https://github.com/in-toto/attestation),
as defined by the [in-toto framework](https://in-toto.io/),
a standard supported by the Linux Foundation.
Attestations attach to images as a manifest in the image index. The data records
@ -149,7 +141,6 @@ attestation.
}
```
<!-- prettier-ignore -->
To deep-dive into the specifics about how attestations are stored, see
[Image Attestation Storage (BuildKit)](attestation-storage.md).

14
content/build/attestations/sbom.md
View File

@ -1,13 +1,11 @@
---
title: SBOM attestations
keywords: build, attestations, sbom
description: SBOM build attestations
keywords: build, attestations, sbom, spdx, metadata, packages
description: |
SBOM build attestations describe the contents of your image,
and the packages used to build it.
---
> **Note**
>
> This feature is supported in BuildKit version `>=0.11` and Buildx version `>=0.10`.
Software Bill of Materials (SBOM) attestations describe what software artifacts
an image contains, and artifacts used to create the image. Metadata included in
an SBOM for describing software artifacts may include:
@ -178,7 +176,6 @@ Using the `--format` option, you can specify a template for the output. All
SBOM-related data is available under the `.SBOM` attribute. For example, to get
the raw contents of an SBOM in SPDX format:
```console
$ docker buildx imagetools inspect <namespace>/<image>:<version> \
--format "{{ json .SBOM.SPDX }}"
@ -188,12 +185,10 @@ $ docker buildx imagetools inspect <namespace>/<image>:<version> \
}
```
You can also construct more complex expressions using the full functionality
of Go templates. For example, you can list all the installed packages and their
version identifiers:
```console
$ docker buildx imagetools inspect <namespace>/<image>:<version> \
--format "{{ range .SBOM.SPDX.packages }}{{ .name }}@{{ .versionInfo }}{{ println }}{{ end }}"
@ -204,7 +199,6 @@ base-passwd@3.5.47
...
```
## SBOM generator
BuildKit generates the SBOM using a scanner plugin. By default, it uses is the

13
content/build/attestations/slsa-provenance.md
View File

@ -1,13 +1,10 @@
---
title: Provenance attestations
keywords: build, attestations, provenance, slsa
description: Provenance build attestations
keywords: build, attestations, provenance, slsa, git, metadata
description: >
Provenance build attestations describe how and where your image was built.
---
> **Note**
>
> This feature is supported in BuildKit version `>=0.11` and Buildx version `>=0.10`.
The provenance attestations include facts about the build process, including
details such as:
@ -153,7 +150,6 @@ Using the `--format` option, you can specify a template for the output. All
provenance-related data is available under the `.Provenance` attribute. For
example, to get the raw contents of the Provenance in the SLSA format:
```console
$ docker buildx imagetools inspect <namespace>/<image>:<version> \
--format "{{ json .Provenance.SLSA }}"
@ -163,12 +159,10 @@ $ docker buildx imagetools inspect <namespace>/<image>:<version> \
}
```
You can also construct more complex expressions using the full functionality of
Go templates. For example, for provenance generated with `mode=max`, you can
extract the full source code of the Dockerfile used to build the image:
```console
$ docker buildx imagetools inspect <namespace>/<image>:<version> \
--format '{{ range (index .Provenance.SLSA.metadata "https://mobyproject.org/buildkit@v1#metadata").source.infos }}{{ if eq .filename "Dockerfile" }}{{ .data }}{{ end }}{{ end }}' | base64 -d
@ -177,7 +171,6 @@ RUN apt-get update
...
```
## Provenance attestation example
<!-- TODO: add a link to the definitions page, imported from moby/buildkit -->

48
content/build/bake/_index.md
View File

@ -5,37 +5,33 @@ aliases:
- /build/customize/bake/
---
> This command is experimental.
> **Experimental**
>
> The design of bake is in early stages, and we are looking for [feedback from users](https://github.com/docker/buildx/issues).
> Bake is an experimental feature, and we are looking for
> [feedback from users](https://github.com/docker/buildx/issues).
{ .experimental }
Buildx also aims to provide support for high-level build concepts that go beyond
invoking a single build command. We want to support building all the images in
your application together and let the users define project specific reusable
build flows that can then be easily invoked by anyone.
Buildx provides support for high-level build orchestration that goes beyond
invoking a single build command. Bake lets you build all the images in your
application together. You can define all of the build jobs for your projects in
a file that can then be easily invoked by anyone.
[BuildKit](https://github.com/moby/buildkit)
efficiently handles multiple concurrent build requests and de-duplicating work.
The build commands can be combined with general-purpose command runners
(for example, `make`). However, these tools generally invoke builds in sequence
and therefore cannot leverage the full potential of BuildKit parallelization,
or combine BuildKit's output for the user. For this use case, we have added a
command called [`docker buildx bake`](../../engine/reference/commandline/buildx_bake.md).
You can think of Bake as a task runner for Docker builds.
[BuildKit](https://github.com/moby/buildkit) efficiently handles multiple
concurrent build requests and de-duplicating work. You can invoke your builds
using general-purpose task runners, like `make`. However, such tools generally
invoke builds in a sequence. Therefore they aren't leveraging the full
potential of BuildKit parallelization. Bake solves this problem.
The `bake` command supports building images from HCL, JSON and Compose files.
This is similar to [`docker compose build`](../../compose/compose-file/build.md),
but allowing all the services to be built concurrently as part of a single
request. If multiple files are specified they are all read and configurations are
combined.
We recommend using HCL files as its experience is more aligned with buildx UX
and also allows better code reuse, different target groups and extended features.
The `docker buildx bake` command supports building images from a configuration
file in HCL, JSON or YAML format. The YAML format extends the Compose
Specification, and it's similar to `docker compose build`, except it builds all
of your services concurrently as part of a single request.
## Next steps
* [Bake file reference](reference.md)
* [Configuring builds](configuring-build.md)
* [User defined HCL functions](hcl-funcs.md)
* [Defining additional build contexts and linking targets](build-contexts.md)
* [Building from Compose file](compose-file.md)
- [Bake file reference](./reference.md)
- [Configuring builds](./configuring-build.md)
- [User defined HCL functions](./advanced.md)
- [Defining additional build contexts and linking targets](./build-contexts.md)
- [Building from Compose file](./compose-file.md)

115
content/build/bake/hcl-funcs.md → content/build/bake/advanced.md
View File

@ -1,15 +1,35 @@
---
title: User defined HCL functions
title: Advanced Bake patterns and functions
description: Learn about advanced Bake features, like user-defined functions
keywords: build, buildx, bake, buildkit, hcl
aliases:
- /build/customize/bake/hcl-funcs/
- /build/bake/hcl-funcs/
---
## Using interpolation to tag an image with the git sha
HCL functions are great for when you need to manipulate values in more complex ways than just concatenating or appending values.
As shown in the [Bake file reference](reference.md#variable) page, `bake`
The following sections contain some examples on custom functions and other
advanced use cases:
- [Interpolate environment variables](#interpolate-environment-variables)
- [Built-in functions](#built-in-functions)
- [User-defined functions](#user-defined-functions)
- [Ternary operators](#ternary-operators)
- [Variables in functions](#variables-in-functions)
- [Typed variables](#typed-variables)
## Interpolate environment variables
As shown in the [Bake file reference](reference.md#variable) page, Bake
supports variable blocks which are assigned to matching environment variables
or default values:
or default values.
The following example shows how you can interpolate a `TAG` environment
variable to populate a variable in the Bake configuration.
{{< tabs >}}
{{< tab name="HCL" >}}
```hcl
# docker-bake.hcl
@ -26,7 +46,8 @@ target "webapp" {
}
```
alternatively, in json format:
{{< /tab >}}
{{< tab name="JSON" >}}
```json
{
@ -48,6 +69,9 @@ alternatively, in json format:
}
```
{{< /tab >}}
{{< /tabs >}}
```console
$ docker buildx bake --print webapp
```
@ -56,18 +80,14 @@ $ docker buildx bake --print webapp
{
"group": {
"default": {
"targets": [
"webapp"
]
"targets": ["webapp"]
}
},
"target": {
"webapp": {
"context": ".",
"dockerfile": "Dockerfile",
"tags": [
"docker.io/username/webapp:latest"
]
"tags": ["docker.io/username/webapp:latest"]
}
}
}
@ -81,27 +101,23 @@ $ TAG=$(git rev-parse --short HEAD) docker buildx bake --print webapp
{
"group": {
"default": {
"targets": [
"webapp"
]
"targets": ["webapp"]
}
},
"target": {
"webapp": {
"context": ".",
"dockerfile": "Dockerfile",
"tags": [
"docker.io/username/webapp:985e9e9"
]
"tags": ["docker.io/username/webapp:985e9e9"]
}
}
}
```
## Using the `add` function
## Built-in functions
You can use [`go-cty` stdlib functions](https://github.com/zclconf/go-cty/tree/main/cty/function/stdlib).
Here we are using the `add` function.
You can use [`go-cty` standard library functions](https://github.com/zclconf/go-cty/tree/main/cty/function/stdlib).
The following example shows the `add` function.
```hcl
# docker-bake.hcl
@ -128,9 +144,7 @@ $ docker buildx bake --print webapp
{
"group": {
"default": {
"targets": [
"webapp"
]
"targets": ["webapp"]
}
},
"target": {
@ -145,10 +159,13 @@ $ docker buildx bake --print webapp
}
```
## Defining an `increment` function
## User-defined functions
It also supports [user defined functions](https://github.com/hashicorp/hcl/tree/main/ext/userfunc).
The following example defines a simple an `increment` function.
You can create [user-defined functions](https://github.com/hashicorp/hcl/tree/main/ext/userfunc)
that do just what you want, if the built-in standard library functions don't
meet your needs.
The following example defines an `increment` function.
```hcl
# docker-bake.hcl
@ -176,9 +193,7 @@ $ docker buildx bake --print webapp
{
"group": {
"default": {
"targets": [
"webapp"
]
"targets": ["webapp"]
}
},
"target": {
@ -193,10 +208,12 @@ $ docker buildx bake --print webapp
}
```
## Only adding tags if a variable is not empty using an `notequal`
## Ternary operators
Here we are using the conditional `notequal` function which is just for
symmetry with the `equal` one.
You can use ternary operators to conditionally register a value.
The following example adds a tag only when a variable is not empty, using the
`notequal` function.
```hcl
# docker-bake.hcl
@ -226,27 +243,25 @@ $ docker buildx bake --print webapp
{
"group": {
"default": {
"targets": [
"webapp"
]
"targets": ["webapp"]
}
},
"target": {
"webapp": {
"context": ".",
"dockerfile": "Dockerfile",
"tags": [
"my-image:latest"
]
"tags": ["my-image:latest"]
}
}
}
```
## Using variables in functions
## Variables in functions
You can refer variables to other variables like the target blocks can. Stdlib
functions can also be called but user functions can't at the moment.
You can make references to variables and standard library functions inside your
functions.
You can't reference user-defined functions from other functions.
```hcl
# docker-bake.hcl
@ -272,27 +287,23 @@ $ docker buildx bake --print webapp
{
"group": {
"default": {
"targets": [
"webapp"
]
"targets": ["webapp"]
}
},
"target": {
"webapp": {
"context": ".",
"dockerfile": "Dockerfile",
"tags": [
"user/repo:v1"
]
"tags": ["user/repo:v1"]
}
}
}
```
## Using typed variables
## Typed variables
Non-string variables are also accepted. The value passed with env is parsed
into suitable type first.
Non-string variables are supported. Values passed as environment variables are
coerced into suitable types first.
```hcl
# docker-bake.hcl
@ -320,9 +331,7 @@ $ docker buildx bake --print app
{
"group": {
"default": {
"targets": [
"app"
]
"targets": ["app"]
}
},
"target": {

28
content/build/bake/build-contexts.md
View File

@ -1,18 +1,28 @@
---
title: Defining additional build contexts and linking targets
description: |
Additional contexts are useful when you want to pin image versions,
or reference the output of other targets
keywords: build, buildx, bake, buildkit, hcl
aliases:
- /build/customize/bake/build-contexts/
---
In addition to the main `context` key that defines the build context each target
can also define additional named contexts with a map defined with key `contexts`.
These values map to the `--build-context` flag in the [build command](../../engine/reference/commandline/buildx_build.md#build-context).
In addition to the main `context` key that defines the build context, each
target can also define additional named contexts with a map defined with key
`contexts`. These values map to the `--build-context` flag in the [build
command](../../engine/reference/commandline/buildx_build.md#build-context).
Inside the Dockerfile these contexts can be used with the `FROM` instruction or `--from` flag.
Inside the Dockerfile these contexts can be used with the `FROM` instruction or
`--from` flag.
The value can be a local source directory, container image (with `docker-image://` prefix),
Git URL, HTTP URL or a name of another target in the Bake file (with `target:` prefix).
Supported context values are:
- Local filesystem directories
- Container images
- Git URLs
- HTTP URLs
- Name of another target in the Bake file
## Pinning alpine image
@ -74,6 +84,6 @@ target "app" {
}
```
Please note that in most cases you should just use a single multi-stage
Dockerfile with multiple targets for similar behavior. This case is recommended
when you have multiple Dockerfiles that can't be easily merged into one.
In most cases you should just use a single multi-stage Dockerfile with multiple
targets for similar behavior. This case is only recommended when you have
multiple Dockerfiles that can't be easily merged into one.

127
content/build/bake/compose-file.md
View File

@ -1,6 +1,7 @@
---
title: Building from Compose file
keywords: build, buildx, bake, buildkit, compose
title: Building with Bake from a Compose file
description: Build your compose services with Bake
keywords: build, buildx, bake, buildkit, compose, yaml
aliases:
- /build/customize/bake/compose-file/
---
@ -45,50 +46,29 @@ $ docker buildx bake --print
{
"group": {
"default": {
"targets": [
"db",
"webapp-dev",
"webapp-release"
]
"targets": ["db", "webapp-dev", "webapp-release"]
}
},
"target": {
"db": {
"context": ".",
"dockerfile": "Dockerfile.db",
"tags": [
"docker.io/username/db"
]
"tags": ["docker.io/username/db"]
},
"webapp-dev": {
"context": ".",
"dockerfile": "Dockerfile.webapp",
"tags": [
"docker.io/username/webapp:latest"
],
"cache-from": [
"docker.io/username/webapp:cache"
],
"cache-to": [
"docker.io/username/webapp:cache"
]
"tags": ["docker.io/username/webapp:latest"],
"cache-from": ["docker.io/username/webapp:cache"],
"cache-to": ["docker.io/username/webapp:cache"]
},
"webapp-release": {
"context": ".",
"dockerfile": "Dockerfile.webapp",
"tags": [
"docker.io/username/webapp:latest"
],
"cache-from": [
"docker.io/username/webapp:cache"
],
"cache-to": [
"docker.io/username/webapp:cache"
],
"platforms": [
"linux/amd64",
"linux/arm64"
]
"tags": ["docker.io/username/webapp:latest"],
"cache-from": ["docker.io/username/webapp:cache"],
"cache-to": ["docker.io/username/webapp:cache"],
"platforms": ["linux/amd64", "linux/arm64"]
}
}
}
@ -96,9 +76,9 @@ $ docker buildx bake --print
The compose format has some limitations compared to the HCL format:
* Specifying variables or global scope attributes is not yet supported
* `inherits` service field is not supported, but you can use [YAML anchors](../../compose/compose-file/10-fragments.md)
to reference other services like the example above
- Specifying variables or global scope attributes is not yet supported
- `inherits` service field is not supported, but you can use [YAML anchors](../../compose/compose-file/10-fragments.md)
to reference other services, as demonstrated in the previous example with `&build-dev`.
## `.env` file
@ -129,18 +109,14 @@ $ docker buildx bake --print
{
"group": {
"default": {
"targets": [
"webapp"
]
"targets": ["webapp"]
}
},
"target": {
"webapp": {
"context": ".",
"dockerfile": "Dockerfile",
"tags": [
"docker.io/username/webapp:v1.1.0"
]
"tags": ["docker.io/username/webapp:v1.1.0"]
}
}
}
@ -153,9 +129,9 @@ $ docker buildx bake --print
## Extension field with `x-bake`
Even if some fields are not (yet) available in the compose specification, you
can use the [special extension](../../compose/compose-file/11-extension.md)
field `x-bake` in your compose file to evaluate extra fields:
Where some fields are not available in the compose specification, you can use
the [special extension](../../compose/compose-file/11-extension.md) field
`x-bake` in your compose file to evaluate extra fields:
```yaml
# docker-compose.yml
@ -206,10 +182,7 @@ $ docker buildx bake --print
{
"group": {
"default": {
"targets": [
"aws",
"addon"
]
"targets": ["aws", "addon"]
}
},
"target": {
@ -220,21 +193,10 @@ $ docker buildx bake --print
"CT_ECR": "foo",
"CT_TAG": "bar"
},
"tags": [
"ct-addon:foo",
"ct-addon:alp"
],
"cache-from": [
"user/app:cache",
"type=local,src=path/to/cache"
],
"cache-to": [
"type=local,dest=path/to/cache"
],
"platforms": [
"linux/amd64",
"linux/arm64"
],
"tags": ["ct-addon:foo", "ct-addon:alp"],
"cache-from": ["user/app:cache", "type=local,src=path/to/cache"],
"cache-to": ["type=local,dest=path/to/cache"],
"platforms": ["linux/amd64", "linux/arm64"],
"pull": true
},
"aws": {
@ -244,19 +206,10 @@ $ docker buildx bake --print
"CT_ECR": "foo",
"CT_TAG": "bar"
},
"tags": [
"ct-fake-aws:bar"
],
"secret": [
"id=mysecret,src=./secret",
"id=mysecret2,src=./secret2"
],
"platforms": [
"linux/arm64"
],
"output": [
"type=docker"
],
"tags": ["ct-fake-aws:bar"],
"secret": ["id=mysecret,src=./secret", "id=mysecret2,src=./secret2"],
"platforms": ["linux/arm64"],
"output": ["type=docker"],
"no-cache": true
}
}
@ -265,14 +218,14 @@ $ docker buildx bake --print
Complete list of valid fields for `x-bake`:
* `cache-from`
* `cache-to`
* `contexts`
* `no-cache`
* `no-cache-filter`
* `output`
* `platforms`
* `pull`
* `secret`
* `ssh`
* `tags`
- `cache-from`
- `cache-to`
- `contexts`
- `no-cache`
- `no-cache-filter`
- `output`
- `platforms`
- `pull`
- `secret`
- `ssh`
- `tags`

64
content/build/bake/configuring-build.md
View File

@ -1,5 +1,6 @@
---
title: Configuring builds
title: Configure builds with Bake
description: Learn how to create a flexible build configuration with Bake
keywords: build, buildx, bake, buildkit, hcl, json
aliases:
- /build/customize/bake/configuring-build/
@ -43,9 +44,7 @@ $ docker buildx bake --print app
{
"group": {
"default": {
"targets": [
"app"
]
"targets": ["app"]
}
},
"target": {
@ -78,9 +77,7 @@ $ docker buildx bake -f docker-bake.hcl -f env.hcl --print app
{
"group": {
"default": {
"targets": [
"app"
]
"targets": ["app"]
}
},
"target": {
@ -122,26 +119,19 @@ $ docker buildx bake --print foo bar
{
"group": {
"default": {
"targets": [
"foo",
"bar"
]
"targets": ["foo", "bar"]
}
},
"target": {
"foo": {
"context": ".",
"dockerfile": "foo.Dockerfile",
"tags": [
"foo"
]
"tags": ["foo"]
},
"bar": {
"context": ".",
"dockerfile": "foo.Dockerfile",
"tags": [
"bar"
]
"tags": ["bar"]
}
}
}
@ -169,9 +159,7 @@ $ docker buildx bake --set app.args.mybuildarg=bar --set app.platform=linux/arm6
{
"group": {
"default": {
"targets": [
"app"
]
"targets": ["app"]
}
},
"target": {
@ -181,9 +169,7 @@ $ docker buildx bake --set app.args.mybuildarg=bar --set app.platform=linux/arm6
"args": {
"mybuildarg": "bar"
},
"platforms": [
"linux/arm64"
]
"platforms": ["linux/arm64"]
}
}
}
@ -200,20 +186,20 @@ $ docker buildx bake --set foo*.no-cache # bypass caching only for
Complete list of overridable fields:
* `args`
* `cache-from`
* `cache-to`
* `context`
* `dockerfile`
* `labels`
* `no-cache`
* `output`
* `platform`
* `pull`
* `secrets`
* `ssh`
* `tags`
* `target`
- `args`
- `cache-from`
- `cache-to`
- `context`
- `dockerfile`
- `labels`
- `no-cache`
- `output`
- `platform`
- `pull`
- `secrets`
- `ssh`
- `tags`
- `target`
## Using variables in variables across files
@ -258,9 +244,7 @@ $ docker buildx bake -f docker-bake1.hcl -f docker-bake2.hcl --print app
{
"group": {
"default": {
"targets": [
"app"
]
"targets": ["app"]
}
},
"target": {

15
content/build/bake/remote-definition.md
View File

@ -1,6 +1,7 @@
---
title: Remote Bake file definition
keywords: build, buildx, bake, file, remote
description: Build with Bake using a remote file definition using Git or HTTP
keywords: build, buildx, bake, file, remote, git, http
---
You can also build Bake files directly from a remote Git repository or HTTPS URL:
@ -18,9 +19,7 @@ $ docker buildx bake "https://github.com/docker/cli.git#v20.10.11" --print
{
"group": {
"default": {
"targets": [
"binary"
]
"targets": ["binary"]
}
},
"target": {
@ -33,12 +32,8 @@ $ docker buildx bake "https://github.com/docker/cli.git#v20.10.11" --print
"VERSION": ""
},
"target": "binary",
"platforms": [
"local"
],
"output": [
"build"
]
"platforms": ["local"],
"output": ["build"]
}
}
}

8
content/build/building/base-images.md
View File

@ -1,6 +1,6 @@
---
title: Create a base image
description: How to create base images
description: Learn about base images and how they're created
keywords: images, base image, examples
aliases:
- /articles/baseimages/
@ -69,7 +69,7 @@ ADD hello /
CMD ["/hello"]
```
Assuming you built the "hello" executable example by using the source code at
Assuming you built the `hello` executable example by using the source code at
[https://github.com/docker-library/hello-world](https://github.com/docker-library/hello-world),
and you compiled it with the `-static` flag, you can build this Docker
image using this `docker build` command:
@ -81,7 +81,9 @@ $ docker build --tag hello .
Don't forget the `.` character at the end, which sets the [build context](../../build/building/context.md)
to the current directory.
> **Note**: Because Docker Desktop for Mac and Docker Desktop for Windows use a Linux VM,
> **Note**
>
> Because Docker Desktop for Mac and Docker Desktop for Windows use a Linux VM,
> you need a Linux binary, rather than a Mac or Windows binary.
> You can use a Docker container to build it:
>

1
content/build/building/opentelemetry.md
View File

@ -1,5 +1,6 @@
---
title: OpenTelemetry support
description: Analyze telemetry data for builds
keywords: build, buildx buildkit, opentelemetry
---

2
content/build/buildkit/configure.md
View File

@ -144,7 +144,6 @@ The following Dockerfile example shows a custom BuildKit image with CNI support.
It uses the [CNI config for integration tests](https://github.com/moby/buildkit/blob/master//hack/fixtures/cni.json)
in BuildKit as an example. Feel free to include your own CNI configuration.
```dockerfile
# syntax=docker/dockerfile:1
@ -166,7 +165,6 @@ COPY --from=cni-plugins /opt/cni/bin /opt/cni/bin
ADD https://raw.githubusercontent.com/moby/buildkit/${BUILDKIT_VERSION}/hack/fixtures/cni.json /etc/buildkit/cni.json
```
Now you can build this image, and create a builder instance from it using
[the `--driver-opt image` option](../../engine/reference/commandline/buildx_create.md#driver-opt):

55
content/build/cache/_index.md vendored
View File

@ -1,28 +1,20 @@
---
title: Optimizing builds with cache management
description: Improve your build speeds by taking advantage of the builtin cache
keywords: 'build, buildx, buildkit, dockerfile, image layers, build instructions,
build context
'
description: Improve your build speed with effective use of the build cache
keywords: build, buildx, buildkit, dockerfile, image layers, build instructions, build context
aliases:
- /build/building/cache/
---
You will likely find yourself rebuilding the same Docker image over and over
again. Whether it's for the next release of your software, or locally during
development. Because building images is a common task, Docker provides several
tools that speed up builds.
The most important feature for improving build speeds is Docker's build cache.
When you build the same Docker image multiple times, knowing how to optimize
the build cache is a great tool for making sure the builds run fast.
## How does the build cache work?
Understanding Docker's build cache helps you write better Dockerfiles that
result in faster builds.
Have a look at the following example, which shows a simple Dockerfile for a
program written in C.
The following example shows a small Dockerfile for a program written in C.
```dockerfile
# syntax=docker/dockerfile:1
@ -34,9 +26,9 @@ WORKDIR /src/
RUN make build
```
Each instruction in this Dockerfile translates (roughly) to a layer in your
final image. You can think of image layers as a stack, with each layer adding
more content on top of the layers that came before it:
Each instruction in this Dockerfile translates to a layer in your final image.
You can think of image layers as a stack, with each layer adding more content
on top of the layers that came before it:
![Image layer diagram](../images/cache-stack.png)
@ -73,16 +65,16 @@ anything differently, they still need to re-run.
Now that you understand how the cache works, you can begin to use the cache to
your advantage. While the cache will automatically work on any `docker build`
that you run, you can often refactor your Dockerfile to get even better
performance. These optimizations can save precious seconds (or even minutes) off
of your builds.
performance. These optimizations can save precious seconds (or even minutes)
off of your builds.
### Order your layers
Putting the commands in your Dockerfile into a logical order is a great place to
start. Because a change causes a rebuild for steps that follow, try to make
Putting the commands in your Dockerfile into a logical order is a great place
to start. Because a change causes a rebuild for steps that follow, try to make
expensive steps appear near the beginning of the Dockerfile. Steps that change
often should appear near the end of the Dockerfile, to avoid triggering rebuilds
of layers that haven't changed.
often should appear near the end of the Dockerfile, to avoid triggering
rebuilds of layers that haven't changed.
Consider the following example. A Dockerfile snippet that runs a JavaScript
build from the source files in the current directory:
@ -97,8 +89,8 @@ RUN npm build # Run build
```
This Dockerfile is rather inefficient. Updating any file causes a reinstall of
all dependencies every time you build the Docker image even if the
dependencies didn't change since last time!
all dependencies every time you build the Docker image even if the dependencies
didn't change since last time!
Instead, the `COPY` command can be split in two. First, copy over the package
management files (in this case, `package.json` and `yarn.lock`). Then, install
@ -130,7 +122,7 @@ To get started, here are a few tips and tricks:
Be considerate of what files you add to the image.
Running a command like `COPY . /src` will `COPY` your entire [build context](../building/context.md)
Running a command like `COPY . /src` will copy your entire [build context](../building/context.md)
into the image. If you've got logs, package manager artifacts, or even previous
build results in your current directory, those will also be copied over. This
could make your image larger than it needs to be, especially as those files are
@ -214,13 +206,12 @@ by default.
#### Use multi-stage builds
<!-- x-link to multi-stage builds once we have some reworked content for that -->
Multi-stage builds let you split up your Dockerfile into multiple distinct
stages. Each stage completes a step in the build process, and you can bridge the
different stages to create your final image at the end. The Docker builder will
work out dependencies between the stages and run them using the most efficient
strategy. This even allows you to run multiple builds concurrently.
[Multi-stage builds](../building/multi-stage.md) let you split up your
Dockerfile into multiple distinct stages. Each stage completes a step in the
build process, and you can bridge the different stages to create your final
image at the end. The Docker builder will work out dependencies between the
stages and run them using the most efficient strategy. This even allows you to
run multiple builds concurrently.
Multi-stage builds use two or more `FROM` commands. The following example
illustrates building a simple web server that serves HTML from your `docs`

9
content/build/cache/backends/_index.md vendored
View File

@ -1,5 +1,9 @@
---
title: Cache storage backends
descripton: |
Cache backends let you manage your build cache externally.
External cache is useful to create a shared cache that can help
speed up inner loop and CI builds.
keywords: build, buildx, cache, backend, gha, azblob, s3, registry, local
aliases:
- /build/building/cache/backends/
@ -14,7 +18,7 @@ environments usually have little-to-no persistence between runs, but it's still
important to keep the runtime of image builds as low as possible.
The default `docker` driver supports the `inline` and `local` cache backends.
Other cache backends require you to select an alternative
Other cache backends require you to select a different
[driver](../../drivers/index.md).
> **Warning**
@ -24,6 +28,7 @@ Other cache backends require you to select an alternative
> [`--secret` option](../../../engine/reference/commandline/buildx_build/#secret).
> Manually managing secrets using `COPY` or `ARG` could result in leaked
> credentials.
{ .warning }
## Backends
@ -32,7 +37,7 @@ Buildx supports the following cache storage backends:
- `inline`: embeds the build cache into the image.
The inline cache gets pushed to the same location as the main output result.
Note that this only works for the `image` exporter.
This only works with the [`image` exporter](../../exporters/image-registry.md).
- `registry`: embeds the build cache into a separate image, and pushes to a
dedicated location separate from the main output.

25
content/build/cache/backends/azblob.md vendored
View File

@ -1,28 +1,23 @@
---
title: Azure Blob Storage cache
description: Manage build cache with Azure blob storage
keywords: build, buildx, cache, backend, azblob, azure
aliases:
- /build/building/cache/backends/azblob/
---
> **Warning**
> **Experimental**
>
> This cache backend is unreleased. You can use it today, by using the
> `moby/buildkit:master` image in your Buildx driver.
> This is an experimental feature. The interface and behavior are unstable and
> may change in future releases.
{ .restricted }
The `azblob` cache store uploads your resulting build cache to
[Azure's blob storage service](https://azure.microsoft.com/en-us/services/storage/blobs/).
> **Note**
>
> This cache storage backend requires using a different driver than the default
> `docker` driver - see more information on selecting a driver
> [here](../../drivers/index.md). To create a new driver (which can act as a
> simple drop-in replacement):
>
> ```console
> $ docker buildx create --use --driver=docker-container
> ```
This cache storage backend is not supported with the default `docker` driver.
To use this feature, create a new builder using a different driver. See
[Build drivers](../../drivers/_index.md) for more information.
## Synopsis
@ -44,7 +39,7 @@ The following table describes the available CSV parameters that you can pass to
| `ignore-error` | `cache-to` | Boolean | `false` | Ignore errors caused by failed cache exports. |
[1]: #authentication
[2]: index.md#cache-mode
[2]: _index.md#cache-mode
## Authentication
@ -55,7 +50,7 @@ The environment variables are read from the server, not the Buildx client.
## Further reading
For an introduction to caching see [Optimizing builds with cache](../index.md).
For an introduction to caching see [Optimizing builds with cache](../_index.md).
For more information on the `azblob` cache backend, see the
[BuildKit README](https://github.com/moby/buildkit#azure-blob-storage-cache-experimental).

32
content/build/cache/backends/gha.md vendored
View File

@ -1,15 +1,16 @@
---
title: GitHub Actions cache
description: Use the GitHub Actions cache to manage your build cache in CI
keywords: build, buildx, cache, backend, gha, github, actions
aliases:
- /build/building/cache/backends/gha/
---
> **Warning**
> **Experimental**
>
> The GitHub Actions cache is a beta feature. You can use it today, in current
> releases of Buildx and BuildKit. However, the interface and behavior are
> unstable and may change in future releases.
> This is an experimental feature. The interface and behavior are unstable and
> may change in future releases.
{ .restricted }
The GitHub Actions cache utilizes the
[GitHub-provided Action's cache](https://github.com/actions/cache) available
@ -17,16 +18,9 @@ from within your CI execution environment. This is the recommended cache to use
inside your GitHub action pipelines, as long as your use case falls within the
[size and usage limits set by GitHub](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows#usage-limits-and-eviction-policy).
> **Note**
>
> This cache storage backend requires using a different driver than the default
> `docker` driver - see more information on selecting a driver
> [here](../../drivers/index.md). To create a new driver (which can act as a
> simple drop-in replacement):
>
> ```console
> $ docker buildx create --use --driver=docker-container
> ```
This cache storage backend is not supported with the default `docker` driver.
To use this feature, create a new builder using a different driver. See
[Build drivers](../../drivers/_index.md) for more information.
## Synopsis
@ -49,16 +43,16 @@ The following table describes the available CSV parameters that you can pass to
[1]: #authentication
[2]: #scope
[3]: index.md#cache-mode
[3]: _index.md#cache-mode
## Authentication
If the `url` or `token` parameters are left unspecified, the `gha` cache backend
will fall back to using environment variables. If you invoke the `docker buildx`
command manually from an inline step, then the variables must be manually
exposed (using
exposed. Consider using the
[`crazy-max/ghaction-github-runtime`](https://github.com/crazy-max/ghaction-github-runtime),
for example).
GitHub Action as a helper for exposing the variables.
## Scope
@ -107,10 +101,10 @@ For example:
## Further reading
For an introduction to caching see [Optimizing builds with cache](../index.md).
For an introduction to caching see [Optimizing builds with cache](../_index.md).
For more information on the `gha` cache backend, see the
[BuildKit README](https://github.com/moby/buildkit#github-actions-cache-experimental).
For more information about using GitHub Actions with Docker, see
[Introduction to GitHub Actions](../../ci/github-actions/index.md)
[Introduction to GitHub Actions](../../ci/github-actions/_index.md)

4
content/build/cache/backends/inline.md vendored
View File

@ -1,5 +1,6 @@
---
title: Inline cache
description: Embed the build cache into the image
keywords: build, buildx, cache, backend, inline
aliases:
- /build/building/cache/backends/inline/
@ -7,8 +8,7 @@ aliases:
The `inline` cache storage backend is the simplest way to get an external cache
and is easy to get started using if you're already building and pushing an
image. Inline cache is the only cache backend supported by the default `docker`
driver.
image.
The downside of inline cache is that it doesn't scale with multi-stage builds
as well as the other drivers do. It also doesn't offer separation between your

11
content/build/cache/backends/local.md vendored
View File

@ -1,5 +1,6 @@
---
title: Local cache
description: Manage build cache with Amazon S3 buckets
keywords: build, buildx, cache, backend, local
aliases:
- /build/building/cache/backends/local/
@ -35,13 +36,13 @@ The following table describes the available CSV parameters that you can pass to
| `force-compression` | `cache-to` | `true`,`false` | `false` | Forcibly apply compression, see [cache compression][3]. |
| `ignore-error` | `cache-to` | Boolean | `false` | Ignore errors caused by failed cache exports. |
[1]: index.md#cache-mode
[2]: index.md#oci-media-types
[3]: index.md#cache-compression
[1]: _index.md#cache-mode
[2]: _index.md#oci-media-types
[3]: _index.md#cache-compression
[4]: #cache-versioning
If the `src` cache doesn't exist, then the cache import step will fail, but the
build will continue.
build continues.
## Cache versioning
@ -90,7 +91,7 @@ $ docker buildx build --push -t <registry>/<image> \
## Further reading
For an introduction to caching see [Optimizing builds with cache](../index.md).
For an introduction to caching see [Optimizing builds with cache](../_index.md).
For more information on the `local` cache backend, see the
[BuildKit README](https://github.com/moby/buildkit#local-directory-1).

24
content/build/cache/backends/registry.md vendored
View File

@ -1,5 +1,6 @@
---
title: Registry cache
description: Manage build cache with an OCI registry
keywords: build, buildx, cache, backend, registry
aliases:
- /build/building/cache/backends/registry/
@ -17,16 +18,9 @@ everything that the inline cache can do, and more:
- It works with other exporters for more flexibility, instead of only the
`image` exporter.
> **Note**
>
> This cache storage backend requires using a different driver than the default
> `docker` driver - see more information on selecting a driver
> [here](../../drivers/index.md). To create a new driver (which can act as a
> simple drop-in replacement):
>
> ```console
> $ docker buildx create --use --driver=docker-container
> ```
This cache storage backend is not supported with the default `docker` driver.
To use this feature, create a new builder using a different driver. See
[Build drivers](../../drivers/_index.md) for more information.
## Synopsis
@ -53,9 +47,9 @@ The following table describes the available CSV parameters that you can pass to
| `force-compression` | `cache-to` | `true`,`false` | `false` | Forcibly apply compression, see [cache compression][3]. |
| `ignore-error` | `cache-to` | Boolean | `false` | Ignore errors caused by failed cache exports. |
[1]: index.md#cache-mode
[2]: index.md#oci-media-types
[3]: index.md#cache-compression
[1]: _index.md#cache-mode
[2]: _index.md#oci-media-types
[3]: _index.md#cache-compression
You can choose any valid value for `ref`, as long as it's not the same as the
target location that you push your image to. You might choose different tags
@ -65,11 +59,11 @@ target location that you push your image to. You might choose different tags
strategy that you want to use for separating your image from your cache images.
If the `--cache-from` target doesn't exist, then the cache import step will
fail, but the build will continue.
fail, but the build continues.
## Further reading
For an introduction to caching see [Optimizing builds with cache](../index.md).
For an introduction to caching see [Optimizing builds with cache](../_index.md).
For more information on the `registry` cache backend, see the
[BuildKit README](https://github.com/moby/buildkit#registry-push-image-and-cache-separately).

23
content/build/cache/backends/s3.md vendored
View File

@ -1,29 +1,24 @@
---
title: Amazon S3 cache
keywords: build, buildx, cache, backend, s3
description: Manage build cache with Amazon S3 buckets
keywords: build, buildx, cache, backend, s3, buckets, aws
aliases:
- /build/building/cache/backends/s3/
---
> **Warning**
> **Experimental**
>
> This cache backend is unreleased. You can use it today, by using the
> `moby/buildkit:master` image in your Buildx driver.
> This is an experimental feature. The interface and behavior are unstable and
> may change in future releases.
{ .restricted }
The `s3` cache storage uploads your resulting build cache to
[Amazon S3 file storage service](https://aws.amazon.com/s3/),
into a specified bucket.
> **Note**
>
> This cache storage backend requires using a different driver than the default
> `docker` driver - see more information on selecting a driver
> [here](../../drivers/index.md). To create a new driver (which can act as a
> simple drop-in replacement):
>
> ```console
> $ docker buildx create --use --driver=docker-container
> ```
This cache storage backend is not supported with the default `docker` driver.
To use this feature, create a new builder using a different driver. See
[Build drivers](../../drivers/_index.md) for more information.
## Synopsis

20
content/build/cache/garbage-collection.md vendored
View File

@ -1,6 +1,7 @@
---
title: Garbage collection
keywords: build, buildx, buildkit, garbage collection, prune
title: Build garbage collection
description: Learn about garbage collection in the BuildKit daemon
keywords: build, buildx, buildkit, garbage collection, prune, gc
aliases:
- /build/building/cache/garbage-collection/
---
@ -58,8 +59,7 @@ For other drivers, garbage collection can be configured using the
## Default policies
Default garbage collection policies are applied to all builders if not
already set:
Default garbage collection policies apply to all builders if not set:
```
GC Policy rule#0:
@ -79,14 +79,14 @@ GC Policy rule#3:
Keep Bytes: 26GB
```
* `rule#0`: if build cache uses more than 512MB delete the most easily
- `rule#0`: if build cache uses more than 512MB delete the most easily
reproducible data after it has not been used for 2 days.
* `rule#1`: remove any data not used for 60 days.
* `rule#2`: keep the unshared build cache under cap.
* `rule#3`: if previous policies were insufficient start deleting internal data
- `rule#1`: remove any data not used for 60 days.
- `rule#2`: keep the unshared build cache under cap.
- `rule#3`: if previous policies were insufficient start deleting internal data
to keep build cache under cap.
> **Note**
>
> "Keep bytes" defaults to 10% of the size of the disk. If the disk size cannot
> be determined, it defaults to 2GB.
> `Keep Bytes` defaults to 10% of the size of the disk. If the disk size cannot
> be determined, it uses 2GB as a fallback.

2
content/build/ci/_index.md
View File

@ -1,5 +1,5 @@
---
description: Overview of using Docker for continuous integration
description: Using Docker for continuous integration
keywords: ci, build
title: Continuous integration with Docker
aliases:

5
content/build/ci/github-actions/_index.md
View File

@ -1,9 +1,6 @@
---
title: Introduction to GitHub Actions
description: 'Docker maintains a set of official GitHub Actions for building Docker
images.
'
description: Docker maintains a set of official GitHub Actions for building Docker images.
keywords: ci, github actions, gha, build, introduction, tutorial
aliases:
- /ci-cd/github-actions/

65
content/build/ci/github-actions/cache.md
View File

@ -8,7 +8,7 @@ Actions.
> **Note**
>
> See [Cache storage backends](../../cache/backends/index.md) for more
> See [Cache storage backends](../../cache/backends/_index.md) for more
> details about cache storage backends.
## Inline cache
@ -18,7 +18,6 @@ However, note that the `inline` cache exporter only supports `min` cache mode.
To use `max` cache mode, push the image and the cache separately using the
registry cache exporter with the `cache-to` option, as shown in the [registry cache example](#registry-cache).
```yaml
name: ci
@ -31,20 +30,16 @@ jobs:
docker:
runs-on: ubuntu-latest
steps:
-
name: Checkout
- name: Checkout
uses: actions/checkout@v3
-
name: Set up Docker Buildx
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v2
-
name: Login to Docker Hub
- name: Login to Docker Hub
uses: docker/login-action@v2
with:
username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }}
-
name: Build and push
- name: Build and push
uses: docker/build-push-action@v4
with:
context: .
@ -54,13 +49,11 @@ jobs:
cache-to: type=inline
```
## Registry cache
You can import/export cache from a cache manifest or (special) image
configuration on the registry with the [registry cache exporter](../../cache/backends/registry.md).
```yaml
name: ci
@ -73,20 +66,16 @@ jobs:
docker:
runs-on: ubuntu-latest
steps:
-
name: Checkout
- name: Checkout
uses: actions/checkout@v3
-
name: Set up Docker Buildx
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v2
-
name: Login to Docker Hub
- name: Login to Docker Hub
uses: docker/login-action@v2
with:
username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }}
-
name: Build and push
- name: Build and push
uses: docker/build-push-action@v4
with:
context: .
@ -96,7 +85,6 @@ jobs:
cache-to: type=registry,ref=user/app:buildcache,mode=max
```
## GitHub cache
### Cache backend API
@ -114,7 +102,6 @@ backend in a GitHub Action workflow, as the `url` (`$ACTIONS_CACHE_URL`) and
`token` (`$ACTIONS_RUNTIME_TOKEN`) attributes only get populated in a workflow
context.
```yaml
name: ci
@ -127,20 +114,16 @@ jobs:
docker:
runs-on: ubuntu-latest
steps:
-
name: Checkout
- name: Checkout
uses: actions/checkout@v3
-
name: Set up Docker Buildx
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v2
-
name: Login to Docker Hub
- name: Login to Docker Hub
uses: docker/login-action@v2
with:
username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }}
-
name: Build and push
- name: Build and push
uses: docker/build-push-action@v4
with:
context: .
@ -150,7 +133,6 @@ jobs:
cache-to: type=gha,mode=max
```
### Cache mounts
BuildKit doesn't preserve cache mounts in the GitHub Actions cache by default.
@ -165,7 +147,6 @@ cache mount data with your Docker build steps.
The following example shows how to use this workaround with a Go project.
```yaml
name: ci
on: push
@ -224,7 +205,6 @@ jobs:
cache-source: go-build-cache
```
For more information about this workaround, refer to the
[GitHub repository](https://github.com/overmindtech/buildkit-cache-dance).
@ -241,7 +221,6 @@ You can also leverage [GitHub cache](https://docs.github.com/en/actions/using-wo
using the [actions/cache](https://github.com/actions/cache) and [local cache exporter](../../cache/backends/local.md)
with this action:
```yaml
name: ci
@ -254,28 +233,23 @@ jobs:
docker:
runs-on: ubuntu-latest
steps:
-
name: Checkout
- name: Checkout
uses: actions/checkout@v3
-
name: Set up Docker Buildx
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v2
-
name: Cache Docker layers
- name: Cache Docker layers
uses: actions/cache@v3
with:
path: /tmp/.buildx-cache
key: ${{ runner.os }}-buildx-${{ github.sha }}
restore-keys: |
${{ runner.os }}-buildx-
-
name: Login to Docker Hub
- name: Login to Docker Hub
uses: docker/login-action@v2
with:
username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }}
-
name: Build and push
- name: Build and push
uses: docker/build-push-action@v4
with:
context: .
@ -283,8 +257,7 @@ jobs:
tags: user/app:latest
cache-from: type=local,src=/tmp/.buildx-cache
cache-to: type=local,dest=/tmp/.buildx-cache-new,mode=max
-
# Temp fix
- # Temp fix
# https://github.com/docker/build-push-action/issues/252
# https://github.com/moby/buildkit/issues/1896
name: Move cache

72
content/build/ci/github-actions/configure-builder.md
View File

@ -49,16 +49,13 @@ jobs:
buildx:
runs-on: ubuntu-latest
steps:
-
name: Checkout
- name: Checkout
uses: actions/checkout@v3
-
name: Set up Docker Buildx
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v2
with:
buildkitd-flags: --debug
-
name: Build
- name: Build
uses: docker/build-push-action@v4
with:
context: .
@ -89,11 +86,9 @@ jobs:
buildx:
runs-on: ubuntu-latest
steps:
-
name: Checkout
- name: Checkout
uses: actions/checkout@v3
-
name: Set up Docker Buildx
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v2
with:
config-inline: |
@ -128,11 +123,9 @@ jobs:
buildx:
runs-on: ubuntu-latest
steps:
-
name: Checkout
- name: Checkout
uses: actions/checkout@v3
-
name: Set up Docker Buildx
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v2
with:
config: .github/buildkitd.toml
@ -152,7 +145,7 @@ intrinsically linked to GitHub Actions: you can only use strings in the input
fields:
| Name | Type | Description |
|-------------------|--------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| ----------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | String | [Name of the node](../../../engine/reference/commandline/buildx_create.md#node). If empty, it's the name of the builder it belongs to, with an index number suffix. This is useful to set it if you want to modify/remove a node in an underlying step of you workflow. |
| `endpoint` | String | [Docker context or endpoint](../../../engine/reference/commandline/buildx_create.md#description) of the node to add to the builder |
| `driver-opts` | List | List of additional [driver-specific options](../../../engine/reference/commandline/buildx_create.md#driver-opt) |
@ -162,7 +155,6 @@ fields:
Here is an example using remote nodes with the [`remote` driver](../../drivers/remote.md)
and [TLS authentication](#tls-authentication):
```yaml
name: ci
@ -173,8 +165,7 @@ jobs:
buildx:
runs-on: ubuntu-latest
steps:
-
name: Set up Docker Buildx
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v2
with:
driver: remote
@ -196,7 +187,6 @@ jobs:
BUILDER_NODE_2_AUTH_TLS_KEY: ${{ secrets.LINUXONE_KEY }}
```
## Authentication for remote builders
The following examples show how to handle authentication for remote builders,
@ -207,7 +197,6 @@ using SSH or TLS.
To be able to connect to an SSH endpoint using the [`docker-container` driver](../../drivers/docker-container.md),
you have to set up the SSH private key and configuration on the GitHub Runner:
```yaml
name: ci
@ -218,21 +207,18 @@ jobs:
buildx:
runs-on: ubuntu-latest
steps:
-
name: Set up SSH
- name: Set up SSH
uses: MrSquaare/ssh-setup-action@523473d91581ccbf89565e12b40faba93f2708bd # v1.1.0
with:
host: graviton2
private-key: ${{ secrets.SSH_PRIVATE_KEY }}
private-key-name: aws_graviton2
-
name: Set up Docker Buildx
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v2
with:
endpoint: ssh://me@graviton2
```
### TLS authentication
You can also [set up a remote BuildKit instance](../../drivers/remote.md#example-remote-buildkit-in-docker-container)
@ -246,7 +232,6 @@ certificates for the `tcp://`:
The `<idx>` placeholder is the position of the node in the list of nodes.
```yaml
name: ci
@ -257,8 +242,7 @@ jobs:
buildx:
runs-on: ubuntu-latest
steps:
-
name: Set up Docker Buildx
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v2
with:
driver: remote
@ -269,7 +253,6 @@ jobs:
BUILDER_NODE_0_AUTH_TLS_KEY: ${{ secrets.GRAVITON2_KEY }}
```
## Standalone mode
If you don't have the Docker CLI installed on the GitHub Runner, the Buildx
@ -287,16 +270,13 @@ jobs:
buildx:
runs-on: ubuntu-latest
steps:
-
name: Checkout
- name: Checkout
uses: actions/checkout@v3
-
name: Set up Docker Buildx
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v2
with:
driver: kubernetes
-
name: Build
- name: Build
run: |
buildx build .
```
@ -315,7 +295,6 @@ hardware.
For more information about remote builder, see [`remote` driver](../../drivers/remote.md)
and the [append builder nodes example](#append-additional-nodes-to-the-builder).
```yaml
name: ci
@ -328,30 +307,23 @@ jobs:
docker:
runs-on: ubuntu-latest
steps:
-
name: Checkout
- name: Checkout
uses: actions/checkout@v3
-
uses: docker/setup-buildx-action@v2
- uses: docker/setup-buildx-action@v2
id: builder1
-
uses: docker/setup-buildx-action@v2
- uses: docker/setup-buildx-action@v2
id: builder2
-
name: Builder 1 name
- name: Builder 1 name
run: echo ${{ steps.builder1.outputs.name }}
-
name: Builder 2 name
- name: Builder 2 name
run: echo ${{ steps.builder2.outputs.name }}
-
name: Build against builder1
- name: Build against builder1
uses: docker/build-push-action@v4
with:
builder: ${{ steps.builder1.outputs.name }}
context: .
target: mytarget1
-
name: Build against builder2
- name: Build against builder2
uses: docker/build-push-action@v4
with:
builder: ${{ steps.builder2.outputs.name }}

23
content/build/ci/github-actions/copy-image-registries.md
View File

@ -1,12 +1,12 @@
---
title: Copy image between registries with GitHub Actions
description: Build multi-platform images and copy them between registries with GitHub Actions
keywords: ci, github actions, gha, buildkit, buildx, registry
---
[Multi-platform images](../../building/multi-platform.md) built using Buildx can
be copied from one registry to another using the [`buildx imagetools create` command](../../../engine/reference/commandline/buildx_imagetools_create.md):
```yaml
name: ci
@ -19,30 +19,24 @@ jobs:
docker:
runs-on: ubuntu-latest
steps:
-
name: Checkout
- name: Checkout
uses: actions/checkout@v3
-
name: Set up QEMU
- name: Set up QEMU
uses: docker/setup-qemu-action@v2
-
name: Set up Docker Buildx
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v2
-
name: Login to Docker Hub
- name: Login to Docker Hub
uses: docker/login-action@v2
with:
username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }}
-
name: Login to GitHub Container Registry
- name: Login to GitHub Container Registry
uses: docker/login-action@v2
with:
registry: ghcr.io
username: ${{ github.repository_owner }}
password: ${{ secrets.GITHUB_TOKEN }}
-
name: Build and push
- name: Build and push
uses: docker/build-push-action@v4
with:
context: .
@ -51,8 +45,7 @@ jobs:
tags: |
user/app:latest
user/app:1.0.0
-
name: Push image to GHCR
- name: Push image to GHCR
run: |
docker buildx imagetools create \
--tag ghcr.io/user/app:latest \

16
content/build/ci/github-actions/export-docker.md
View File

@ -1,12 +1,12 @@
---
title: Export to Docker with GitHub Actions
keywords: ci, github actions, gha, buildkit, buildx, docker
description: Load the build results to the image store with GitHub Actions
keywords: ci, github actions, gha, buildkit, buildx, docker, export, load
---
You may want your build result to be available in the Docker client through
`docker images` to be able to use it in another step of your workflow:
```yaml
name: ci
@ -19,21 +19,17 @@ jobs:
docker:
runs-on: ubuntu-latest
steps:
-
name: Checkout
- name: Checkout
uses: actions/checkout@v3
-
name: Set up Docker Buildx
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v2
-
name: Build
- name: Build
uses: docker/build-push-action@v4
with:
context: .
load: true
tags: myimage:latest
-
name: Inspect
- name: Inspect
run: |
docker image inspect myimage:latest
```

17
content/build/ci/github-actions/local-registry.md
View File

@ -1,12 +1,12 @@
---
title: Local registry with GitHub Actions
description: Create and use a local OCI registry with GitHub Actions
keywords: ci, github actions, gha, buildkit, buildx, registry
---
For testing purposes you may need to create a [local registry](https://hub.docker.com/_/registry)
to push images into:
```yaml
name: ci
@ -24,26 +24,21 @@ jobs:
ports:
- 5000:5000
steps:
-
name: Checkout
- name: Checkout
uses: actions/checkout@v3
-
name: Set up QEMU
- name: Set up QEMU
uses: docker/setup-qemu-action@v2
-
name: Set up Docker Buildx
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v2
with:
driver-opts: network=host
-
name: Build and push to local registry
- name: Build and push to local registry
uses: docker/build-push-action@v4
with:
context: .
push: true
tags: localhost:5000/name/app:latest
-
name: Inspect
- name: Inspect
run: |
docker buildx imagetools inspect localhost:5000/name/app:latest
```

23
content/build/ci/github-actions/manage-tags-labels.md
View File

@ -1,5 +1,6 @@
---
title: Manage tags and labels with GitHub Actions
description: Assign tags and labels to images automatically with GitHub Actions
keywords: ci, github actions, gha, buildkit, buildx, tags, labels
---
@ -8,7 +9,6 @@ for labels, you can do it in a dedicated setup step. The following workflow
will use the [Docker Metadata Action](https://github.com/docker/metadata-action)
to handle tags and labels based on GitHub Actions events and Git metadata:
```yaml
name: ci
@ -28,11 +28,9 @@ jobs:
docker:
runs-on: ubuntu-latest
steps:
-
name: Checkout
- name: Checkout
uses: actions/checkout@v3
-
name: Docker meta
- name: Docker meta
id: meta
uses: docker/metadata-action@v4
with:
@ -49,29 +47,24 @@ jobs:
type=semver,pattern={{major}}.{{minor}}
type=semver,pattern={{major}}
type=sha
-
name: Set up QEMU
- name: Set up QEMU
uses: docker/setup-qemu-action@v2
-
name: Set up Docker Buildx
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v2
-
name: Login to Docker Hub
- name: Login to Docker Hub
if: github.event_name != 'pull_request'
uses: docker/login-action@v2
with:
username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }}
-
name: Login to GHCR
- name: Login to GHCR
if: github.event_name != 'pull_request'
uses: docker/login-action@v2
with:
registry: ghcr.io
username: ${{ github.repository_owner }}
password: ${{ secrets.GITHUB_TOKEN }}
-
name: Build and push
- name: Build and push
uses: docker/build-push-action@v4
with:
context: .

61
content/build/ci/github-actions/multi-platform.md
View File

@ -1,5 +1,6 @@
---
title: Multi-platform image with GitHub Actions
description: Build for multiple architectures with GitHub Actions using QEMU emulation or multiple native builders
keywords: ci, github actions, gha, buildkit, buildx, multi-platform
---
@ -13,7 +14,6 @@ the `platforms` option, as shown in the following example:
> - If you want support for more platforms, you can use QEMU with the [Docker Setup QEMU](https://github.com/docker/setup-qemu-action)
> action.
```yaml
name: ci
@ -26,23 +26,18 @@ jobs:
docker:
runs-on: ubuntu-latest
steps:
-
name: Checkout
- name: Checkout
uses: actions/checkout@v3
-
name: Set up QEMU
- name: Set up QEMU
uses: docker/setup-qemu-action@v2
-
name: Set up Docker Buildx
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v2
-
name: Login to Docker Hub
- name: Login to Docker Hub
uses: docker/login-action@v2
with:
username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }}
-
name: Build and push
- name: Build and push
uses: docker/build-push-action@v4
with:
context: .
@ -51,7 +46,6 @@ jobs:
tags: user/app:latest
```
## Distribute build across multiple runners
In the previous example, each platform is built on the same runner which can
@ -68,7 +62,6 @@ create a manifest list and push it to Docker Hub.
This example also uses the [`metadata` action](https://github.com/docker/metadata-action)
to set tags and labels.
```yaml
name: ci
@ -92,29 +85,23 @@ jobs:
- linux/arm/v7
- linux/arm64
steps:
-
name: Checkout
- name: Checkout
uses: actions/checkout@v3
-
name: Docker meta
- name: Docker meta
id: meta
uses: docker/metadata-action@v4
with:
images: ${{ env.REGISTRY_IMAGE }}
-
name: Set up QEMU
- name: Set up QEMU
uses: docker/setup-qemu-action@v2
-
name: Set up Docker Buildx
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v2
-
name: Login to Docker Hub
- name: Login to Docker Hub
uses: docker/login-action@v2
with:
username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }}
-
name: Build and push by digest
- name: Build and push by digest
id: build
uses: docker/build-push-action@v4
with:
@ -122,14 +109,12 @@ jobs:
platforms: ${{ matrix.platform }}
labels: ${{ steps.meta.outputs.labels }}
outputs: type=image,name=${{ env.REGISTRY_IMAGE }},push-by-digest=true,name-canonical=true,push=true
-
name: Export digest
- name: Export digest
run: |
mkdir -p /tmp/digests
digest="${{ steps.build.outputs.digest }}"
touch "/tmp/digests/${digest#sha256:}"
-
name: Upload digest
- name: Upload digest
uses: actions/upload-artifact@v3
with:
name: digests
@ -142,35 +127,29 @@ jobs:
needs:
- build
steps:
-
name: Download digests
- name: Download digests
uses: actions/download-artifact@v3
with:
name: digests
path: /tmp/digests
-
name: Set up Docker Buildx
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v2
-
name: Docker meta
- name: Docker meta
id: meta
uses: docker/metadata-action@v4
with:
images: ${{ env.REGISTRY_IMAGE }}
-
name: Login to Docker Hub
- name: Login to Docker Hub
uses: docker/login-action@v2
with:
username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }}
-
name: Create manifest list and push
- name: Create manifest list and push
working-directory: /tmp/digests
run: |
docker buildx imagetools create $(jq -cr '.tags | map("-t " + .) | join(" ")' <<< "$DOCKER_METADATA_OUTPUT_JSON") \
$(printf '${{ env.REGISTRY_IMAGE }}@sha256:%s ' *)
-
name: Inspect image
- name: Inspect image
run: |
docker buildx imagetools inspect ${{ env.REGISTRY_IMAGE }}:${{ steps.meta.outputs.version }}
```

41
content/build/ci/github-actions/named-contexts.md
View File

@ -1,5 +1,6 @@
---
title: Named contexts with GitHub Actions
description: Use additional contexts in multi-stage builds with GitHub Actions
keywords: ci, github actions, gha, buildkit, buildx, context
---
@ -20,7 +21,6 @@ FROM alpine
RUN echo "Hello World"
```
```yaml
name: ci
@ -33,14 +33,11 @@ jobs:
docker:
runs-on: ubuntu-latest
steps:
-
name: Checkout
- name: Checkout
uses: actions/checkout@v3
-
name: Set up Docker Buildx
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v2
-
name: Build
- name: Build
uses: docker/build-push-action@v4
with:
context: .
@ -49,7 +46,6 @@ jobs:
tags: myimage:latest
```
## Use image in subsequent steps
By default, the [Docker Setup Buildx](https://github.com/marketplace/actions/docker-setup-buildx)
@ -64,7 +60,6 @@ FROM alpine
RUN echo "Hello World"
```
```yaml
name: ci
@ -77,24 +72,20 @@ jobs:
docker:
runs-on: ubuntu-latest
steps:
-
name: Checkout
- name: Checkout
uses: actions/checkout@v3
-
name: Set up Docker Buildx
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v2
with:
driver: docker
-
name: Build base image
- name: Build base image
uses: docker/build-push-action@v4
with:
context: ./base
file: ./base/Dockerfile
load: true
tags: my-base-image:latest
-
name: Build
- name: Build
uses: docker/build-push-action@v4
with:
context: .
@ -103,7 +94,6 @@ jobs:
tags: myimage:latest
```
## Using with a container builder
As shown in the previous section we are not using the default
@ -135,28 +125,23 @@ jobs:
ports:
- 5000:5000
steps:
-
name: Checkout
- name: Checkout
uses: actions/checkout@v3
-
name: Set up QEMU
- name: Set up QEMU
uses: docker/setup-qemu-action@v2
-
name: Set up Docker Buildx
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v2
with:
# network=host driver-opt needed to push to local registry
driver-opts: network=host
-
name: Build base image
- name: Build base image
uses: docker/build-push-action@v4
with:
context: ./base
file: ./base/Dockerfile
tags: localhost:5000/my-base-image:latest
push: true
-
name: Build
- name: Build
uses: docker/build-push-action@v4
with:
context: .

26
content/build/ci/github-actions/push-multi-registries.md
View File

@ -1,11 +1,11 @@
---
title: Push to multi-registries with GitHub Actions
title: Push to multiple registries with GitHub Actions
description: Push to multiple registries with GitHub Actions
keywords: ci, github actions, gha, buildkit, buildx, registry
---
The following workflow will connect you to Docker Hub and [GitHub Container Registry](https://github.com/docker/login-action#github-container-registry)
and push the image to both registries:
The following workflow will connect you to Docker Hub and GitHub Container
Registry, and push the image to both registries:
```yaml
name: ci
@ -19,30 +19,24 @@ jobs:
docker:
runs-on: ubuntu-latest
steps:
-
name: Checkout
- name: Checkout
uses: actions/checkout@v3
-
name: Set up QEMU
- name: Set up QEMU
uses: docker/setup-qemu-action@v2
-
name: Set up Docker Buildx
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v2
-
name: Login to Docker Hub
- name: Login to Docker Hub
uses: docker/login-action@v2
with:
username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }}
-
name: Login to GitHub Container Registry
- name: Login to GitHub Container Registry
uses: docker/login-action@v2
with:
registry: ghcr.io
username: ${{ github.repository_owner }}
password: ${{ secrets.GITHUB_TOKEN }}
-
name: Build and push
- name: Build and push
uses: docker/build-push-action@v4
with:
context: .

20
content/build/ci/github-actions/secrets.md
View File

@ -1,5 +1,6 @@
---
title: Using secrets with GitHub Actions
description: Example using secret mounts with GitHub Actions
keywords: ci, github actions, gha, buildkit, buildx, secret
---
@ -18,7 +19,6 @@ RUN --mount=type=secret,id=github_token \
In this example, the secret name is `github_token`. The following workflow
exposes this secret using the `secrets` input:
```yaml
name: ci
@ -31,17 +31,13 @@ jobs:
docker:
runs-on: ubuntu-latest
steps:
-
name: Checkout
- name: Checkout
uses: actions/checkout@v3
-
name: Set up QEMU
- name: Set up QEMU
uses: docker/setup-qemu-action@v2
-
name: Set up Docker Buildx
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v2
-
name: Build
- name: Build
uses: docker/build-push-action@v4
with:
context: .
@ -51,8 +47,6 @@ jobs:
"github_token=${{ secrets.GITHUB_TOKEN }}"
```
> **Note**
>
> You can also expose a secret file to the build with the `secret-files` input:
@ -66,7 +60,6 @@ If you're using [GitHub secrets](https://docs.github.com/en/actions/security-gui
and need to handle multi-line value, you will need to place the key-value pair
between quotes:
```yaml
secrets: |
"MYSECRET=${{ secrets.GPG_KEY }}"
@ -82,9 +75,8 @@ secrets: |
"JSON_SECRET={""key1"":""value1"",""key2"":""value2""}"
```
| Key | Value |
|------------------|-------------------------------------|
| ---------------- | ----------------------------------- |
| `MYSECRET` | `***********************` |
| `GIT_AUTH_TOKEN` | `abcdefghi,jklmno=0123456789` |
| `MYSECRET` | `aaaaaaaa\nbbbbbbb\nccccccccc` |

20
content/build/ci/github-actions/share-image-jobs.md
View File

@ -1,5 +1,6 @@
---
title: Share built image between jobs with GitHub Actions
description: Share an image between runners without pushing to a registry
keywords: ci, github actions, gha, buildkit, buildx
---
@ -10,7 +11,6 @@ in a workflow using the [actions/upload-artifact](https://github.com/actions/upl
and [actions/download-artifact](https://github.com/actions/download-artifact)
actions:
```yaml
name: ci
@ -23,21 +23,17 @@ jobs:
build:
runs-on: ubuntu-latest
steps:
-
name: Checkout
- name: Checkout
uses: actions/checkout@v3
-
name: Set up Docker Buildx
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v2
-
name: Build and export
- name: Build and export
uses: docker/build-push-action@v4
with:
context: .
tags: myimage:latest
outputs: type=docker,dest=/tmp/myimage.tar
-
name: Upload artifact
- name: Upload artifact
uses: actions/upload-artifact@v3
with:
name: myimage
@ -47,14 +43,12 @@ jobs:
runs-on: ubuntu-latest
needs: build
steps:
-
name: Download artifact
- name: Download artifact
uses: actions/download-artifact@v3
with:
name: myimage
path: /tmp
-
name: Load image
- name: Load image
run: |
docker load --input /tmp/myimage.tar
docker image ls -a

35
content/build/ci/github-actions/test-before-push.md
View File

@ -1,18 +1,17 @@
---
title: Test before push with GitHub Actions
description: Here's how you can validate an image, before pushing it to a registry
keywords: ci, github actions, gha, buildkit, buildx, test
---
In some cases, you might want to validate that the image works as expected
before pushing it.
The following workflow implements several steps to achieve this:
before pushing it. The following workflow implements several steps to achieve
this:
1. Build and export the image to Docker
2. Test your image
3. Multi-platform build and push the image
```yaml
name: ci
@ -29,34 +28,27 @@ jobs:
docker:
runs-on: ubuntu-latest
steps:
-
name: Checkout
- name: Checkout
uses: actions/checkout@v3
-
name: Set up QEMU
- name: Set up QEMU
uses: docker/setup-qemu-action@v2
-
name: Set up Docker Buildx
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v2
-
name: Login to Docker Hub
- name: Login to Docker Hub
uses: docker/login-action@v2
with:
username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }}
-
name: Build and export to Docker
- name: Build and export to Docker
uses: docker/build-push-action@v4
with:
context: .
load: true
tags: ${{ env.TEST_TAG }}
-
name: Test
- name: Test
run: |
docker run --rm ${{ env.TEST_TAG }}
-
name: Build and push
- name: Build and push
uses: docker/build-push-action@v4
with:
context: .
@ -65,10 +57,9 @@ jobs:
tags: ${{ env.LATEST_TAG }}
```
> **Note**
>
> This workflow doesn't actually build the `linux/amd64` image twice. The image
> is built once, and the following steps uses the internal cache for from the
> first `Build and push` step. The second `Build and push` step only builds
> The `linux/amd64` image is only built once in this workflow. The image is
> built once, and the following steps use the internal cache from the first
> `Build and push` step. The second `Build and push` step only builds
> `linux/arm64`.

22
content/build/ci/github-actions/update-dockerhub-desc.md
View File

@ -1,5 +1,6 @@
---
title: Update Docker Hub repo description with GitHub Actions
title: Update Docker Hub description with GitHub Actions
description: How to update the repository README in Docker Hub using with GitHub Actions
keywords: ci, github actions, gha, buildkit, buildx, docker hub
---
@ -7,7 +8,6 @@ You can update the Docker Hub repository description using a third party action
called [Docker Hub Description](https://github.com/peter-evans/dockerhub-description)
with this action:
```yaml
name: ci
@ -20,30 +20,24 @@ jobs:
docker:
runs-on: ubuntu-latest
steps:
-
name: Checkout
- name: Checkout
uses: actions/checkout@v3
-
name: Set up QEMU
- name: Set up QEMU
uses: docker/setup-qemu-action@v2
-
name: Set up Docker Buildx
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v2
-
name: Login to Docker Hub
- name: Login to Docker Hub
uses: docker/login-action@v2
with:
username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }}
-
name: Build and push
- name: Build and push
uses: docker/build-push-action@v4
with:
context: .
push: true
tags: user/app:latest
-
name: Update repo description
- name: Update repo description
uses: peter-evans/dockerhub-description@v3
with:
username: ${{ secrets.DOCKERHUB_USERNAME }}

3
content/build/dockerfile/frontend.md
View File

@ -1,5 +1,6 @@
---
title: Custom Dockerfile syntax
description: Dive deep into the Dockerfile frontend, and learn about custom frontends
keywords: build, buildkit, dockerfile, frontend
aliases:
- /build/buildkit/dockerfile-frontend/
@ -96,7 +97,7 @@ compatible. Pin the version to avoid having to deal with breaking changes.
## Other resources
For documentation on "labs" features, master builds, and nightly feature
For documentation on `labs` features, master builds, and nightly feature
releases, refer to the description in [the BuildKit source repository on GitHub](https://github.com/moby/buildkit/blob/master/README.md).
For a full list of available images, visit the [`docker/dockerfile` repository on Docker Hub](https://hub.docker.com/r/docker/dockerfile),
and the [`docker/dockerfile-upstream` repository on Docker Hub](https://hub.docker.com/r/docker/dockerfile-upstream)

110
content/build/dockerfile/release-notes.md
View File

@ -16,22 +16,22 @@ For usage, see the [Dockerfile frontend syntax](frontend.md) page.
### New
* Add `--start-interval` flag to the
- Add `--start-interval` flag to the
[`HEALTHCHECK` instruction](../../engine/reference/builder.md#healthcheck).
The following features have graduated from the labs channel to stable:
* The `ADD` instruction can now [import files directly from Git URLs](../../engine/reference/builder.md#adding-a-git-repository-add-git-ref-dir)
* The `ADD` instruction now supports [`--checksum` flag](../../engine/reference/builder.md#verifying-a-remote-file-checksum-add---checksumchecksum-http-src-dest)
- The `ADD` instruction can now [import files directly from Git URLs](../../engine/reference/builder.md#adding-a-git-repository-add-git-ref-dir)
- The `ADD` instruction now supports [`--checksum` flag](../../engine/reference/builder.md#verifying-a-remote-file-checksum-add---checksumchecksum-http-src-dest)
to validate the contents of the remote URL contents
### Bug fixes and enhancements
* Variable substitution now supports additional POSIX compatible variants without `:`.
- Variable substitution now supports additional POSIX compatible variants without `:`.
[moby/buildkit#3611](https://github.com/moby/buildkit/pull/3611)
* Exported Windows images now contain OSVersion and OSFeatures values from base image.
- Exported Windows images now contain OSVersion and OSFeatures values from base image.
[moby/buildkit#3619](https://github.com/moby/buildkit/pull/3619)
* Changed the permissions for Heredocs to 0644.
- Changed the permissions for Heredocs to 0644.
[moby/buildkit#3992](https://github.com/moby/buildkit/pull/3992)
## 1.5.2
@ -40,9 +40,9 @@ The following features have graduated from the labs channel to stable:
### Bug fixes and enhancements
* Fix building from Git reference that is missing branch name but contains a
- Fix building from Git reference that is missing branch name but contains a
subdir
* 386 platform image is now included in the release
- 386 platform image is now included in the release
## 1.5.1
@ -50,7 +50,7 @@ The following features have graduated from the labs channel to stable:
### Bug fixes and enhancements
* Fix possible panic when warning conditions appear in multi-platform builds
- Fix possible panic when warning conditions appear in multi-platform builds
## 1.5.0 (labs)
@ -60,7 +60,7 @@ The following features have graduated from the labs channel to stable:
### New
* `ADD` command now supports [`--checksum` flag](../../engine/reference/builder.md#verifying-a-remote-file-checksum-add---checksumchecksum-http-src-dest)
- `ADD` command now supports [`--checksum` flag](../../engine/reference/builder.md#verifying-a-remote-file-checksum-add---checksumchecksum-http-src-dest)
to validate the contents of the remote URL contents
## 1.5.0
@ -69,20 +69,20 @@ The following features have graduated from the labs channel to stable:
### New
* `ADD` command can now [import files directly from Git URLs](../../engine/reference/builder.md#adding-a-git-repository-add-git-ref-dir)
- `ADD` command can now [import files directly from Git URLs](../../engine/reference/builder.md#adding-a-git-repository-add-git-ref-dir)
### Bug fixes and enhancements
* Named contexts now support `oci-layout://` protocol for including images from
- Named contexts now support `oci-layout://` protocol for including images from
local OCI layout structure
* Dockerfile now supports secondary requests for listing all build targets or
- Dockerfile now supports secondary requests for listing all build targets or
printing outline of accepted parameters for a specific build target
* Dockerfile `#syntax` directive that redirects to an external frontend image
- Dockerfile `#syntax` directive that redirects to an external frontend image
now allows the directive to be also set with `//` comments or JSON. The file
may also contain a shebang header
* Named context can now be initialized with an empty scratch image
* Named contexts can now be initialized with an SSH Git URL
* Fix handling of `ONBUILD` when importing Schema1 images
- Named context can now be initialized with an empty scratch image
- Named contexts can now be initialized with an SSH Git URL
- Fix handling of `ONBUILD` when importing Schema1 images
## 1.4.3
@ -90,9 +90,9 @@ The following features have graduated from the labs channel to stable:
### Bug fixes and enhancements
* Fix creation timestamp not getting reset when building image from
- Fix creation timestamp not getting reset when building image from
`docker-image://` named context
* Fix passing `--platform` flag of `FROM` command when loading
- Fix passing `--platform` flag of `FROM` command when loading
`docker-image://` named context
## 1.4.2
@ -101,7 +101,7 @@ The following features have graduated from the labs channel to stable:
### Bug fixes and enhancements
* Fix loading certain environment variables from an image passed with built
- Fix loading certain environment variables from an image passed with built
context
## 1.4.1
@ -110,7 +110,7 @@ The following features have graduated from the labs channel to stable:
### Bug fixes and enhancements
* Fix named context resolution for cross-compilation cases from input when input
- Fix named context resolution for cross-compilation cases from input when input
is built for a different platform
## 1.4.0
@ -119,24 +119,24 @@ The following features have graduated from the labs channel to stable:
### New
* [`COPY --link` and `ADD --link`](../../engine/reference/builder.md#copy---link)
- [`COPY --link` and `ADD --link`](../../engine/reference/builder.md#copy---link)
allow copying files with increased cache efficiency and rebase images without
requiring them to be rebuilt. `--link` copies files to a separate layer and
then uses new LLB MergeOp implementation to chain independent layers together
* [Heredocs](../../engine/reference/builder.md#here-documents) support have
- [Heredocs](../../engine/reference/builder.md#here-documents) support have
been promoted from labs channel to stable. This feature allows writing
multiline inline scripts and files
* Additional [named build contexts](../../engine/reference/commandline/buildx_build.md#build-context)
- Additional [named build contexts](../../engine/reference/commandline/buildx_build.md#build-context)
can be passed to build to add or overwrite a stage or an image inside the
build. A source for the context can be a local source, image, Git, or HTTP URL
* [`BUILDKIT_SANDBOX_HOSTNAME` build-arg](../../engine/reference/builder.md#buildkit-built-in-build-args)
- [`BUILDKIT_SANDBOX_HOSTNAME` build-arg](../../engine/reference/builder.md#buildkit-built-in-build-args)
can be used to set the default hostname for the `RUN` steps
### Bug fixes and enhancements
* When using a cross-compilation stage, the target platform for a step is now
- When using a cross-compilation stage, the target platform for a step is now
seen on progress output
* Fix some cases where Heredocs incorrectly removed quotes from content
- Fix some cases where Heredocs incorrectly removed quotes from content
## 1.3.1
@ -144,7 +144,7 @@ The following features have graduated from the labs channel to stable:
### Bug fixes and enhancements
* Fix parsing "required" mount key without a value
- Fix parsing "required" mount key without a value
## 1.3.0 (labs)
@ -154,7 +154,7 @@ The following features have graduated from the labs channel to stable:
### New
* `RUN` and `COPY` commands now support [Here-document syntax](../../engine/reference/builder.md#here-documents)
- `RUN` and `COPY` commands now support [Here-document syntax](../../engine/reference/builder.md#here-documents)
allowing writing multiline inline scripts and files
## 1.3.0
@ -163,17 +163,17 @@ The following features have graduated from the labs channel to stable:
### New
* `RUN` command allows [`--network` flag](../../engine/reference/builder.md#run---network)
- `RUN` command allows [`--network` flag](../../engine/reference/builder.md#run---network)
for requesting a specific type of network conditions. `--network=host`
requires allowing `network.host` entitlement. This feature was previously
only available on labs channel
### Bug fixes and enhancements
* `ADD` command with a remote URL input now correctly handles the `--chmod` flag
* Values for [`RUN --mount` flag](../../engine/reference/builder.md#run---mount)
- `ADD` command with a remote URL input now correctly handles the `--chmod` flag
- Values for [`RUN --mount` flag](../../engine/reference/builder.md#run---mount)
now support variable expansion, except for the `from` field
* Allow [`BUILDKIT_MULTI_PLATFORM` build arg](../../engine/reference/builder.md#buildkit-built-in-build-args)
- Allow [`BUILDKIT_MULTI_PLATFORM` build arg](../../engine/reference/builder.md#buildkit-built-in-build-args)
to force always creating multi-platform image, even if only contains single
platform
@ -185,7 +185,7 @@ The following features have graduated from the labs channel to stable:
### Bug fixes and enhancements
* `RUN` command allows [`--network` flag](../../engine/reference/builder.md#run---network)
- `RUN` command allows [`--network` flag](../../engine/reference/builder.md#run---network)
for requesting a specific type of network conditions. `--network=host`
requires allowing `network.host` entitlement
@ -195,8 +195,8 @@ The following features have graduated from the labs channel to stable:
### Bug fixes and enhancements
* Revert "Ensure ENTRYPOINT command has at least one argument"
* Optimize processing `COPY` calls on multi-platform cross-compilation builds
- Revert "Ensure ENTRYPOINT command has at least one argument"
- Optimize processing `COPY` calls on multi-platform cross-compilation builds
## 1.2.0 (labs)
@ -206,7 +206,7 @@ The following features have graduated from the labs channel to stable:
### Bug fixes and enhancements
* Experimental channel has been renamed to *labs*
- Experimental channel has been renamed to _labs_
## 1.2.0
@ -214,18 +214,18 @@ The following features have graduated from the labs channel to stable:
### New
* [`RUN --mount` syntax](../../engine/reference/builder.md#run---mount) for
- [`RUN --mount` syntax](../../engine/reference/builder.md#run---mount) for
creating secret, ssh, bind, and cache mounts have been moved to mainline
channel
* [`ARG` command](../../engine/reference/builder.md#arg) now supports defining
- [`ARG` command](../../engine/reference/builder.md#arg) now supports defining
multiple build args on the same line similarly to `ENV`
### Bug fixes and enhancements
* Metadata load errors are now handled as fatal to avoid incorrect build results
* Allow lowercase Dockerfile name
* `--chown` flag in `ADD` now allows parameter expansion
* `ENTRYPOINT` requires at least one argument to avoid creating broken images
- Metadata load errors are now handled as fatal to avoid incorrect build results
- Allow lowercase Dockerfile name
- `--chown` flag in `ADD` now allows parameter expansion
- `ENTRYPOINT` requires at least one argument to avoid creating broken images
## 1.1.7
@ -233,7 +233,7 @@ The following features have graduated from the labs channel to stable:
### Bug fixes and enhancements
* Forward `FrontendInputs` to the gateway
- Forward `FrontendInputs` to the gateway
## 1.1.2 (experimental)
@ -243,11 +243,11 @@ The following features have graduated from the labs channel to stable:
### Bug fixes and enhancements
* Allow setting security mode for a process with `RUN --security=sandbox|insecure`
* Allow setting uid/gid for [cache mounts](../../engine/reference/builder.md#run---mounttypecache)
* Avoid requesting internally linked paths to be pulled to build context
* Ensure missing cache IDs default to target paths
* Allow setting namespace for cache mounts with [`BUILDKIT_CACHE_MOUNT_NS` build arg](../../engine/reference/builder.md#buildkit-built-in-build-args)
- Allow setting security mode for a process with `RUN --security=sandbox|insecure`
- Allow setting uid/gid for [cache mounts](../../engine/reference/builder.md#run---mounttypecache)
- Avoid requesting internally linked paths to be pulled to build context
- Ensure missing cache IDs default to target paths
- Allow setting namespace for cache mounts with [`BUILDKIT_CACHE_MOUNT_NS` build arg](../../engine/reference/builder.md#buildkit-built-in-build-args)
## 1.1.2
@ -255,9 +255,9 @@ The following features have graduated from the labs channel to stable:
### Bug fixes and enhancements
* Fix workdir creation with correct user and don't reset custom ownership
* Fix handling empty build args also used as `ENV`
* Detect circular dependencies
- Fix workdir creation with correct user and don't reset custom ownership
- Fix handling empty build args also used as `ENV`
- Detect circular dependencies
## 1.1.0
@ -265,13 +265,13 @@ The following features have graduated from the labs channel to stable:
### New
* `ADD/COPY` commands now support implementation based on `llb.FileOp` and do
- `ADD/COPY` commands now support implementation based on `llb.FileOp` and do
not require helper image if builtin file operations support is available
* `--chown` flag for `COPY` command now supports variable expansion
- `--chown` flag for `COPY` command now supports variable expansion
### Bug fixes and enhancements
* To find the files ignored from the build context Dockerfile frontend will
- To find the files ignored from the build context Dockerfile frontend will
first look for a file `<path/to/Dockerfile>.dockerignore` and if it is not
found `.dockerignore` file will be looked up from the root of the build
context. This allows projects with multiple Dockerfiles to use different

8
content/build/drivers/_index.md
View File

@ -1,5 +1,6 @@
---
title: Drivers overview
title: Build drivers
description: Build drivers are configurations for how and where the BuildKit backend runs.
keywords: build, buildx, driver, builder, docker-container, kubernetes, remote
aliases:
- /build/buildx/drivers/
@ -7,7 +8,7 @@ aliases:
- /build/buildx/multiple-builders/
---
Buildx drivers are configurations for how and where the BuildKit backend runs.
Build drivers are configurations for how and where the BuildKit backend runs.
Driver settings are customizable and allows fine-grained control of the builder.
Buildx supports the following drivers:
@ -33,8 +34,7 @@ The following table outlines some differences between drivers.
## What's next
Read about each of the Buildx drivers to learn about how they work and how to
use them:
Read about each driver:
- [Docker driver](./docker.md)
- [Docker container driver](./docker-container.md)

9
content/build/drivers/docker-container.md
View File

@ -1,12 +1,13 @@
---
title: Docker container driver
title: Docker container build driver
description: The Docker container driver runs BuildKit in a container image.
keywords: build, buildx, driver, builder, docker-container
aliases:
- /build/buildx/drivers/docker-container/
- /build/building/drivers/docker-container/
---
The buildx Docker container driver allows creation of a managed and customizable
The Docker container driver allows creation of a managed and customizable
BuildKit environment in a dedicated Docker container.
Using the Docker container driver has a couple of advantages over the default
@ -33,7 +34,7 @@ The following table describes the available driver-specific options that you can
pass to `--driver-opt`:
| Parameter | Type | Default | Description |
|-----------------|--------|------------------|--------------------------------------------------------------------------------------------|
| --------------- | ------ | ---------------- | ------------------------------------------------------------------------------------------ |
| `image` | String | | Sets the image to use for running BuildKit. |
| `network` | String | | Sets the network mode for running the BuildKit container. |
| `cgroup-parent` | String | `/docker/buildx` | Sets the cgroup parent of the BuildKit container if Docker is using the `cgroupfs` driver. |
@ -171,13 +172,11 @@ $ docker buildx inspect --bootstrap
[Inspect the builder container](../../engine/reference/commandline/inspect.md)
and see what network is being used:
```console
$ docker inspect buildx_buildkit_mybuilder0 --format={{.NetworkSettings.Networks}}
map[foonet:0xc00018c0c0]
```
## Further reading
For more information on the Docker container driver, see the

3
content/build/drivers/docker.md
View File

@ -1,5 +1,8 @@
---
title: Docker driver
description: |
The Docker driver is the default driver.
It uses the BuildKit bundled with the Docker Engine.
keywords: build, buildx, driver, builder, docker
aliases:
- /build/buildx/drivers/docker/

45
content/build/drivers/kubernetes.md
View File

@ -1,14 +1,17 @@
---
title: Kubernetes driver
description: |
The Kubernetes driver lets you run BuildKit in a Kubernetes cluster.
You can connect to, and run your builds in, the cluster using Buildx.
keywords: build, buildx, driver, builder, kubernetes
aliases:
- /build/buildx/drivers/kubernetes/
- /build/building/drivers/kubernetes/
---
The Buildx Kubernetes driver allows connecting your local development or CI
environments to your Kubernetes cluster to allow access to more powerful and
varied compute resources.
The Kubernetes driver lets you connect your local development or CI
environments to builders in a Kubernetes cluster to allow access to more
powerful compute resources, optionally on multiple native architectures.
## Synopsis
@ -23,8 +26,8 @@ $ docker buildx create \
--driver-opt=[key=value,...]
```
The following table describes the available driver-specific options that you can
pass to `--driver-opt`:
The following table describes the available driver-specific options that you
can pass to `--driver-opt`:
| Parameter | Type | Default | Description |
| ----------------- | ----------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
@ -98,7 +101,7 @@ replicas. `sticky` (the default) attempts to connect the same build performed
multiple times to the same node each time, ensuring better use of local cache.
For more information on scalability, see the options for
[buildx create](../../engine/reference/commandline/buildx_create.md#driver-opt).
[`docker buildx create`](../../engine/reference/commandline/buildx_create.md#driver-opt).
## Node assignment
@ -110,8 +113,8 @@ key-value pairs, where the key is the node label and the value is the label
text. For example: `"nodeselector=kubernetes.io/arch=arm64"`
The `tolerations` parameter is a semicolon-separated list of taints. It accepts
the same values as the Kubernetes manifest. Each `tolerations` entry specifies a
taint key and the value, operator, or effect. For example:
the same values as the Kubernetes manifest. Each `tolerations` entry specifies
a taint key and the value, operator, or effect. For example:
`"tolerations=key=foo,value=bar;key=foo2,operator=exists;key=foo3,effect=NoSchedule"`
Due to quoting rules for shell commands, you must wrap the `nodeselector` and
@ -128,9 +131,9 @@ $ docker buildx create \
## Multi-platform builds
The Buildx Kubernetes driver has support for creating
[multi-platform images](../building/multi-platform.md), either using QEMU or by
leveraging the native architecture of nodes.
The Kubernetes driver has support for creating
[multi-platform images](../building/multi-platform.md),
either using QEMU or by leveraging the native architecture of nodes.
### QEMU
@ -154,6 +157,7 @@ $ docker buildx build \
> QEMU performs full-system emulation of non-native platforms, which is much
> slower than native builds. Compute-heavy tasks like compilation and
> compression/decompression will likely take a large performance hit.
{ .warning }
Using a custom BuildKit image or invoking non-native binaries in builds may
require that you explicitly turn on QEMU using the `qemu.install` option when
@ -208,7 +212,7 @@ $ docker buildx create \
--driver-opt=namespace=buildkit,nodeselector="kubernetes.io/arch=arm64"
```
If you list builders now, you should be able to see both nodes present:
Listing your builders shows both nodes for the `kube` builder:
```console
$ docker buildx ls
@ -218,8 +222,8 @@ kube kubernetes
builder-arm64 kubernetes:///kube?deployment=builder-arm64&kubeconfig= running linux/arm64*
```
You should now be able to build multi-arch images with `amd64` and `arm64`
combined, by specifying those platforms together in your buildx command:
You can now build multi-arch `amd64` and `arm64` images, by specifying those
platforms together in your build command:
```console
$ docker buildx build --builder=kube --platform=linux/amd64,linux/arm64 -t <user>/<image> --push .
@ -276,10 +280,9 @@ Prerequisites:
namespace/buildkit created
```
2. Create a new Buildx builder with the Kubernetes driver:
2. Create a new builder with the Kubernetes driver:
```console
# Remember to specify the namespace in driver options
$ docker buildx create \
--bootstrap \
--name=kube \
@ -287,7 +290,11 @@ Prerequisites:
--driver-opt=namespace=buildkit
```
3. List available Buildx builders using `docker buildx ls`
> **Note**
>
> Remember to specify the namespace in driver options.
3. List available builders using `docker buildx ls`
```console
$ docker buildx ls
@ -298,7 +305,7 @@ Prerequisites:
default default running linux/amd64, linux/386
```
4. Inspect the running pods created by the Buildx driver with `kubectl`.
4. Inspect the running pods created by the build driver with `kubectl`.
```console
$ kubectl -n buildkit get deployments
@ -310,7 +317,7 @@ Prerequisites:
kube0-6977cdcb75-k9h9m 1/1 Running 0 32s
```
The buildx driver creates the necessary resources on your cluster in the
The build driver creates the necessary resources on your cluster in the
specified namespace (in this case, `buildkit`), while keeping your driver
configuration locally.

36
content/build/drivers/remote.md
View File

@ -1,5 +1,8 @@
---
title: Remote driver
description: |
The remote driver lets you connect to a remote BuildKit instance
that you set up and configure manually.
keywords: build, buildx, driver, builder, remote
aliases:
- /build/buildx/drivers/remote/
@ -35,8 +38,7 @@ pass to `--driver-opt`:
This guide shows you how to create a setup with a BuildKit daemon listening on a
Unix socket, and have Buildx connect through it.
1. Ensure that [BuildKit](https://github.com/moby/buildkit)
is installed.
1. Ensure that [BuildKit](https://github.com/moby/buildkit) is installed.
For example, you can launch an instance of buildkitd with:
@ -174,22 +176,16 @@ copied between them.
tcp://buildkitd.default.svc:1234
```
Note that this will only work internally, within the cluster, since the BuildKit
setup guide only creates a ClusterIP service. To configure the builder to be
accessible remotely, you can use an appropriately configured ingress, which is
outside the scope of this guide.
Note that this only works internally, within the cluster, since the BuildKit
setup guide only creates a `ClusterIP` service. To access a builder remotely,
you can set up and use an ingress, which is outside the scope of this guide.
To access the service remotely, use the port forwarding mechanism of `kubectl`:
### Debug a remote builder in Kubernetes
```console
$ kubectl port-forward svc/buildkitd 1234:1234
```
Then you can point the remote driver at `tcp://localhost:1234`.
Alternatively, you can use the `kube-pod://` URL scheme to connect directly to a
BuildKit pod through the Kubernetes API. Note that this method only connects to
a single pod in the deployment:
If you're having trouble accessing a remote builder deployed in Kubernetes, you
can use the `kube-pod://` URL scheme to connect directly to a BuildKit pod
through the Kubernetes API. Note that this method only connects to a single pod
in the deployment.
```console
$ kubectl get pods --selector=app=buildkitd -o json | jq -r '.items[].metadata.name
@ -199,3 +195,11 @@ $ docker buildx create \
--driver remote \
kube-pod://buildkitd-XXXXXXXXXX-xxxxx
```
Alternatively, use the port forwarding mechanism of `kubectl`:
```console
$ kubectl port-forward svc/buildkitd 1234:1234
```
Then you can point the remote driver at `tcp://localhost:1234`.

22
content/build/exporters/_index.md
View File

@ -1,9 +1,7 @@
---
title: Exporters overview
keywords: 'build, buildx, buildkit, exporter, image, registry, local, tar, oci, docker,
cacheonly
'
description: Build exporters define the output format of your build result
keywords: build, buildx, buildkit, exporter, image, registry, local, tar, oci, docker, cacheonly
aliases:
- /build/building/exporters/
---
@ -36,10 +34,10 @@ $ docker buildx build --tag <registry>/<image> \
--output type=<TYPE> .
```
Most common use cases doesn't require you don't need to specify which exporter
to use explicitly. You only need to specify the exporter if you intend to
customize the output somehow, or if you want to save it to disk. The `--load`
and `--push` options allow Buildx to infer the exporter settings to use.
Most common use cases don't require that you specify which exporter to use
explicitly. You only need to specify the exporter if you intend to customize
the output, or if you want to save it to disk. The `--load` and `--push`
options allow Buildx to infer the exporter settings to use.
For example, if you use the `--push` option in combination with `--tag`, Buildx
automatically uses the `image` exporter, and configures the exporter to push the
@ -152,7 +150,7 @@ $ docker buildx build --output type=tar,dest=<path/to/output> .
```
The `local` exporter is useful in [multi-stage builds](../building/multi-stage.md)
since it allows you to export only a minimal number of build artifacts. For example,
since it allows you to export only a minimal number of build artifacts, such as
self-contained binaries.
### Cache-only export
@ -248,12 +246,10 @@ the previous compression algorithm.
### OCI media types
Exporters that output container images, support creating images with either
Docker media types (the default) or with OCI media types. This is supported by
the `image`, `registry`, `oci` and `docker` exporters.
The `image`, `registry`, `oci` and `docker` exporters create container images.
These exporters support both Docker media types (default) and OCI media types
To export images with OCI media types set, use the `oci-mediatypes` property.
For example, with the `image` exporter:
```console
$ docker buildx build \

22
content/build/exporters/image-registry.md
View File

@ -1,8 +1,9 @@
---
title: Image and registry exporters
keywords: 'build, buildx, buildkit, exporter, image, registry
'
description: |
The image and registry exporters create an image that can be loaded to your
local image store or pushed to a registry
keywords: build, buildx, buildkit, exporter, image, registry
aliases:
- /build/building/exporters/image-registry/
---
@ -17,9 +18,6 @@ Build a container image using the `image` and `registry` exporters:
```console
$ docker buildx build --output type=image[,parameters] .
```
```console
$ docker buildx build --output type=registry[,parameters] .
```
@ -27,7 +25,7 @@ The following table describes the available parameters that you can pass to
`--output` for `type=image`:
| Parameter | Type | Default | Description |
|------------------------|----------------------------------------|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| ---------------------- | -------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | String | | Specify image name(s) |
| `push` | `true`,`false` | `false` | Push after creating the image. |
| `push-by-digest` | `true`,`false` | `false` | Push image without name. |
@ -42,15 +40,15 @@ The following table describes the available parameters that you can pass to
| `store` | `true`,`false` | `true` | Store the result images to the worker's (for example, containerd) image store, and ensures that the image has all blobs in the content store. Ignored if the worker doesn't have image store (when using OCI workers, for example). |
| `annotation.<key>` | String | | Attach an annotation with the respective `key` and `value` to the built image,see [annotations][3] |
[1]: index.md#compression
[2]: index.md#oci-media-types
[1]: _index.md#compression
[2]: _index.md#oci-media-types
[3]: #annotations
## Annotations
These exporters support adding OCI annotation using `annotation.*` dot notation
parameter. The following example sets the `org.opencontainers.image.title`
annotation for a build:
These exporters support adding OCI annotation using `annotation` parameter,
followed by the annotation name using dot notation. The following example sets
the `org.opencontainers.image.title` annotation:
```console
$ docker buildx build \

11
content/build/exporters/local-tar.md
View File

@ -1,8 +1,8 @@
---
title: Local and tar exporters
keywords: 'build, buildx, buildkit, exporter, local, tar
'
keywords: build, buildx, buildkit, exporter, local, tar
description: >
The local and tar exporters save the build result to the local filesystem
aliases:
- /build/building/exporters/local-tar/
---
@ -20,16 +20,13 @@ Build a container image using the `local` exporter:
```console
$ docker buildx build --output type=local[,parameters] .
```
```console
$ docker buildx build --output type=tar[,parameters] .
```
The following table describes the available parameters:
| Parameter | Type | Default | Description |
|-----------|--------|---------|-----------------------|
| --------- | ------ | ------- | --------------------- |
| `dest` | String | | Path to copy files to |
## Further reading

18
content/build/exporters/oci-docker.md
View File

@ -1,8 +1,8 @@
---
title: OCI and Docker exporters
keywords: 'build, buildx, buildkit, exporter, oci, docker
'
keywords: build, buildx, buildkit, exporter, oci, docker
description: >
The OCI and Docker exporters create an image layout tarball on the local filesystem
aliases:
- /build/building/exporters/local-tar/
---
@ -31,7 +31,7 @@ $ docker buildx build --output type=docker[,parameters] .
The following table describes the available parameters:
| Parameter | Type | Default | Description |
|---------------------|----------------------------------------|---------|---------------------------------------------------------------------------------------------------------------------------------------|
| ------------------- | -------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | String | | Specify image name(s) |
| `dest` | String | | Path |
| `tar` | `true`,`false` | `true` | Bundle the output into a tarball layout |
@ -41,15 +41,15 @@ The following table describes the available parameters:
| `oci-mediatypes` | `true`,`false` | | Use OCI media types in exporter manifests. Defaults to `true` for `type=oci`, and `false` for `type=docker`. See [OCI Media types][2] |
| `annotation.<key>` | String | | Attach an annotation with the respective `key` and `value` to the built image,see [annotations][3] |
[1]: index.md#compression
[2]: index.md#oci-media-types
[1]: _index.md#compression
[2]: _index.md#oci-media-types
[3]: #annotations
## Annotations
These exporters support adding OCI annotation using `annotation.*` dot notation
parameter. The following example sets the `org.opencontainers.image.title`
annotation for a build:
These exporters support adding OCI annotation using `annotation` parameter,
followed by the annotation name using dot notation. The following example sets
the `org.opencontainers.image.title` annotation:
```console
$ docker buildx build \

639
content/build/release-notes.md
View File

@ -127,9 +127,9 @@ The full release note for this release is available
### Bug fixes and enhancements
* Add `BUILDX_NO_DEFAULT_ATTESTATIONS` as alternative to `--provenance false`. {% include github_issue.md repo="docker/buildx" number="1645" %}
* Disable dirty Git checkout detection by default for performance. Can be enabled with `BUILDX_GIT_CHECK_DIRTY` opt-in. {% include github_issue.md repo="docker/buildx" number="1650" %}
* Strip credentials from VCS hint URL before sending to BuildKit. {% include github_issue.md repo="docker/buildx" number="1664" %}
- Add `BUILDX_NO_DEFAULT_ATTESTATIONS` as alternative to `--provenance false`. [docker/buildx#1645](https://github.com/docker/buildx/issues/1645)
- Disable dirty Git checkout detection by default for performance. Can be enabled with `BUILDX_GIT_CHECK_DIRTY` opt-in. [docker/buildx#1650](https://github.com/docker/buildx/issues/1650)
- Strip credentials from VCS hint URL before sending to BuildKit. [docker/buildx#1664](https://github.com/docker/buildx/issues/1664)
## 0.10.3
@ -139,11 +139,11 @@ The full release note for this release is available
### Bug fixes and enhancements
* Fix reachable commit and warnings on collecting Git provenance info. {% include github_issue.md repo="docker/buildx" number="1592" %} {% include github_issue.md repo="docker/buildx" number="1634" %}
* Fix a regression where docker context was not being validated. {% include github_issue.md repo="docker/buildx" number="1596" %}
* Fix function resolution with JSON bake definition. {% include github_issue.md repo="docker/buildx" number="1605" %}
* Fix case where original HCL bake diagnostic is discarded. {% include github_issue.md repo="docker/buildx" number="1607" %}
* Fix labels not correctly set with bake and compose file. {% include github_issue.md repo="docker/buildx" number="1631" %}
- Fix reachable commit and warnings on collecting Git provenance info. [docker/buildx#1592](https://github.com/docker/buildx/issues/1592), [docker/buildx#1634](https://github.com/docker/buildx/issues/1634)
- Fix a regression where docker context was not being validated. [docker/buildx#1596](https://github.com/docker/buildx/issues/1596)
- Fix function resolution with JSON bake definition. [docker/buildx#1605](https://github.com/docker/buildx/issues/1605)
- Fix case where original HCL bake diagnostic is discarded. [docker/buildx#1607](https://github.com/docker/buildx/issues/1607)
- Fix labels not correctly set with bake and compose file. [docker/buildx#1631](https://github.com/docker/buildx/issues/1631)
## 0.10.2
@ -153,11 +153,11 @@ The full release note for this release is available
### Bug fixes and enhancements
* Fix preferred platforms order not taken into account in multi-node builds. {% include github_issue.md repo="docker/buildx" number="1561" %}
* Fix possible panic on handling `SOURCE_DATE_EPOCH` environment variable. {% include github_issue.md repo="docker/buildx" number="1564" %}
* Fix possible push error on multi-node manifest merge since BuildKit v0.11 on
some registries. {% include github_issue.md repo="docker/buildx" number="1566" %}
* Improve warnings on collecting Git provenance info. {% include github_issue.md repo="docker/buildx" number="1568" %}
- Fix preferred platforms order not taken into account in multi-node builds. [docker/buildx#1561](https://github.com/docker/buildx/issues/1561)
- Fix possible panic on handling `SOURCE_DATE_EPOCH` environment variable. [docker/buildx#1564](https://github.com/docker/buildx/issues/1564)
- Fix possible push error on multi-node manifest merge since BuildKit v0.11 on
some registries. [docker/buildx#1566](https://github.com/docker/buildx/issues/1566)
- Improve warnings on collecting Git provenance info. [docker/buildx#1568](https://github.com/docker/buildx/issues/1568)
## 0.10.1
@ -167,14 +167,14 @@ The full release note for this release is available
### Bug fixes and enhancements
* Fix sending the correct origin URL as `vsc:source` metadata. {% include github_issue.md repo="docker/buildx" number="1548" %}
* Fix possible panic from data-race. {% include github_issue.md repo="docker/buildx" number="1504" %}
* Fix regression with `rm --all-inactive`. {% include github_issue.md repo="docker/buildx" number="1547" %}
* Improve attestation access in `imagetools inspect` by lazily loading data. {% include github_issue.md repo="docker/buildx" number="1546" %}
* Correctly mark capabilities request as internal. {% include github_issue.md repo="docker/buildx" number="1538" %}
* Detect invalid attestation configuration. {% include github_issue.md repo="docker/buildx" number="1545" %}
* Update containerd patches to fix possible push regression affecting
`imagetools` commands. {% include github_issue.md repo="docker/buildx" number="1559" %}
- Fix sending the correct origin URL as `vsc:source` metadata. [docker/buildx#1548](https://github.com/docker/buildx/issues/1548)
- Fix possible panic from data-race. [docker/buildx#1504](https://github.com/docker/buildx/issues/1504)
- Fix regression with `rm --all-inactive`. [docker/buildx#1547](https://github.com/docker/buildx/issues/1547)
- Improve attestation access in `imagetools inspect` by lazily loading data. [docker/buildx#1546](https://github.com/docker/buildx/issues/1546)
- Correctly mark capabilities request as internal. [docker/buildx#1538](https://github.com/docker/buildx/issues/1538)
- Detect invalid attestation configuration. [docker/buildx#1545](https://github.com/docker/buildx/issues/1545)
- Update containerd patches to fix possible push regression affecting
`imagetools` commands. [docker/buildx#1559](https://github.com/docker/buildx/issues/1559)
## 0.10.0
@ -184,65 +184,72 @@ The full release note for this release is available
### New
* The `buildx build` command supports new `--attest` flag, along with
- The `buildx build` command supports new `--attest` flag, along with
shorthands `--sbom` and `--provenance`, for adding attestations for your
current build. {% include github_issue.md repo="docker/buildx" number="1412" %}
{% include github_issue.md repo="docker/buildx" number="1475" %}
* `--attest type=sbom` or `--sbom=true` adds [SBOM attestations](attestations/sbom.md).
* `--attest type=provenance` or `--provenance=true` adds [SLSA provenance attestation](attestations/slsa-provenance.md)
* When creating OCI images, a minimal provenance attestation is included
current build. [docker/buildx#1412](https://github.com/docker/buildx/issues/1412)
[docker/buildx#1475](https://github.com/docker/buildx/issues/1475)
- `--attest type=sbom` or `--sbom=true` adds [SBOM attestations](attestations/sbom.md).
- `--attest type=provenance` or `--provenance=true` adds [SLSA provenance attestation](attestations/slsa-provenance.md).
- When creating OCI images, a minimal provenance attestation is included
with the image by default.
* When building with BuildKit that supports provenance attestations Buildx will
- When building with BuildKit that supports provenance attestations Buildx will
automatically share the version control information of your build context, so
it can be shown in provenance for later debugging. Previously this only
happened when building from a Git URL directly. To opt-out of this behavior
you can set `BUILDX_GIT_INFO=0`. Optionally you can also automatically define
labels with VCS info by setting `BUILDX_GIT_LABELS=1`. {% include github_issue.md repo="docker/buildx" number="1462" %}
{% include github_issue.md repo="docker/buildx" number="1297" %} {% include github_issue.md repo="docker/buildx" number="1341" %}
{% include github_issue.md repo="docker/buildx" number="1468" %} {% include github_issue.md repo="docker/buildx" number="1477" %}
* Named contexts with `--build-context` now support `oci-layout://` protocol
labels with VCS info by setting `BUILDX_GIT_LABELS=1`.
[docker/buildx#1462](https://github.com/docker/buildx/issues/1462),
[docker/buildx#1297](https://github.com/docker/buildx),
[docker/buildx#1341](https://github.com/docker/buildx/issues/1341),
[docker/buildx#1468](https://github.com/docker/buildx),
[docker/buildx#1477](https://github.com/docker/buildx/issues/1477)
- Named contexts with `--build-context` now support `oci-layout://` protocol
for initializing the context with a value of a local OCI layout directory.
E.g. `--build-context stagename=oci-layout://path/to/dir`. This feature
requires BuildKit v0.11.0+ and Dockerfile 1.5.0+. {% include github_issue.md repo="docker/buildx" number="1456" %}
* Bake now supports [resource interpolation](bake/configuring-build.md#resource-interpolation)
where you can reuse the values from other target definitions. {% include github_issue.md repo="docker/buildx" number="1434" %}
* Buildx will now automatically forward `SOURCE_DATE_EPOCH` environment variable
requires BuildKit v0.11.0+ and Dockerfile 1.5.0+. [docker/buildx#1456](https://github.com/docker/buildx/issues/1456)
- Bake now supports [resource interpolation](bake/configuring-build.md#resource-interpolation)
where you can reuse the values from other target definitions. [docker/buildx#1434](https://github.com/docker/buildx/issues/1434)
- Buildx will now automatically forward `SOURCE_DATE_EPOCH` environment variable
if it is defined in your environment. This feature is meant to be used with
updated [reproducible builds](https://github.com/moby/buildkit/blob/master/docs/build-repro.md)
support in BuildKit v0.11.0+. {% include github_issue.md repo="docker/buildx" number="1482" %}
* Buildx now remembers the last activity for a builder for better organization
of builder instances. {% include github_issue.md repo="docker/buildx" number="1439" %}
* Bake definition now supports null values for [variables](bake/reference.md#variable) and [labels](bake/reference.md#targetlabels)
for build arguments and labels to use the defaults set in the Dockerfile {% include github_issue.md repo="docker/buildx" number="1449" %}
* The [`buildx imagetools inspect` command](../engine/reference/commandline/buildx_imagetools_inspect.md)
now supports showing SBOM and Provenance data {% include github_issue.md repo="docker/buildx" number="1444" %}
{% include github_issue.md repo="docker/buildx" number="1498" %}
* Increase performance of `ls` command and inspect flows {% include github_issue.md repo="docker/buildx" number="1430" %}
{% include github_issue.md repo="docker/buildx" number="1454" %} {% include github_issue.md repo="docker/buildx" number="1455" %}
{% include github_issue.md repo="docker/buildx" number="1345" %}
* Adding extra hosts with [Docker driver](drivers/docker.md) now supports
Docker-specific `host-gateway` special value {% include github_issue.md repo="docker/buildx" number="1446" %}
* [OCI exporter](exporters/oci-docker.md) now supports `tar=false` option for
exporting OCI format directly in a directory {% include github_issue.md repo="docker/buildx" number="1420" %}
support in BuildKit v0.11.0+. [docker/buildx#1482](https://github.com/docker/buildx/issues/1482)
- Buildx now remembers the last activity for a builder for better organization
of builder instances. [docker/buildx#1439](https://github.com/docker/buildx/issues/1439)
- Bake definition now supports null values for [variables](bake/reference.md#variable) and [labels](bake/reference.md#targetlabels)
for build arguments and labels to use the defaults set in the Dockerfile.
[docker/buildx#1449](https://github.com/docker/buildx/issues/1449)
- The [`buildx imagetools inspect` command](../engine/reference/commandline/buildx_imagetools_inspect.md)
now supports showing SBOM and Provenance data.
[docker/buildx#1444](https://github.com/docker/buildx/issues/1444),
[docker/buildx#1498](https://github.com/docker/buildx/issues/1498)
- Increase performance of `ls` command and inspect flows.
[docker/buildx#1430](https://github.com/docker/buildx/issues/1430),
[docker/buildx#1454](https://github.com/docker/buildx/issues/1454),
[docker/buildx#1455](https://github.com/docker/buildx/issues/1455),
[docker/buildx#1345](https://github.com/docker/buildx/issues/1345)
- Adding extra hosts with [Docker driver](drivers/docker.md) now supports
Docker-specific `host-gateway` special value. [docker/buildx#1446](https://github.com/docker/buildx/issues/1446)
- [OCI exporter](exporters/oci-docker.md) now supports `tar=false` option for
exporting OCI format directly in a directory. [docker/buildx#1420](https://github.com/docker/buildx/issues/1420)
### Upgrades
* Updated the Compose Specification to 1.6.0 {% include github_issue.md repo="docker/buildx" number="1387" %}
- Updated the Compose Specification to 1.6.0. [docker/buildx#1387](https://github.com/docker/buildx/issues/1387)
### Bug fixes and enhancements
* `--invoke` can now load default launch environment from the image metadata {% include github_issue.md repo="docker/buildx" number="1324" %}
* Fix container driver behavior in regards to UserNS {% include github_issue.md repo="docker/buildx" number="1368" %}
* Fix possible panic in Bake when using wrong variable value type {% include github_issue.md repo="docker/buildx" number="1442" %}
* Fix possible panic in `imagetools inspect` {% include github_issue.md repo="docker/buildx" number="1441" %}
{% include github_issue.md repo="docker/buildx" number="1406" %}
* Fix sending empty `--add-host` value to BuildKit by default {% include github_issue.md repo="docker/buildx" number="1457" %}
* Fix handling progress prefixes with progress groups {% include github_issue.md repo="docker/buildx" number="1305" %}
* Fix recursively resolving groups in Bake {% include github_issue.md repo="docker/buildx" number="1313" %}
* Fix possible wrong indentation on multi-node builder manifests {% include github_issue.md repo="docker/buildx" number="1396" %}
* Fix possible panic from missing OpenTelemetry configuration {% include github_issue.md repo="docker/buildx" number="1383" %}
* Fix `--progress=tty` behavior when TTY is not available {% include github_issue.md repo="docker/buildx" number="1371" %}
* Fix connection error conditions in `prune` and `du` commands {% include github_issue.md repo="docker/buildx" number="1307" %}
- `--invoke` can now load default launch environment from the image metadata. [docker/buildx#1324](https://github.com/docker/buildx/issues/1324)
- Fix container driver behavior in regards to UserNS. [docker/buildx#1368](https://github.com/docker/buildx/issues/1368)
- Fix possible panic in Bake when using wrong variable value type. [docker/buildx#1442](https://github.com/docker/buildx/issues/1442)
- Fix possible panic in `imagetools inspect`. [docker/buildx#1441](https://github.com/docker/buildx/issues/1441)
[docker/buildx#1406](https://github.com/docker/buildx/issues/1406)
- Fix sending empty `--add-host` value to BuildKit by default. [docker/buildx#1457](https://github.com/docker/buildx/issues/1457)
- Fix handling progress prefixes with progress groups. [docker/buildx#1305](https://github.com/docker/buildx/issues/1305)
- Fix recursively resolving groups in Bake. [docker/buildx#1313](https://github.com/docker/buildx/issues/1313)
- Fix possible wrong indentation on multi-node builder manifests. [docker/buildx#1396](https://github.com/docker/buildx/issues/1396)
- Fix possible panic from missing OpenTelemetry configuration. [docker/buildx#1383](https://github.com/docker/buildx/issues/1383)
- Fix `--progress=tty` behavior when TTY is not available. [docker/buildx#1371](https://github.com/docker/buildx/issues/1371)
- Fix connection error conditions in `prune` and `du` commands. [docker/buildx#1307](https://github.com/docker/buildx/issues/1307)
## 0.9.1
@ -250,9 +257,9 @@ The full release note for this release is available
### Bug fixes and enhancements
* The `inspect` command now displays the BuildKit version in use {% include github_issue.md repo="docker/buildx" number="1279" %}
* Fixed a regression when building Compose files that contain services without a
build block {% include github_issue.md repo="docker/buildx" number="1277" %}
- The `inspect` command now displays the BuildKit version in use. [docker/buildx#1279](https://github.com/docker/buildx/issues/1279)
- Fixed a regression when building Compose files that contain services without a
build block. [docker/buildx#1277](https://github.com/docker/buildx/issues/1277)
For more details, see the complete release notes in the [Buildx GitHub repository](https://github.com/docker/buildx/releases/tag/v0.9.1).
@ -262,92 +269,97 @@ For more details, see the complete release notes in the [Buildx GitHub repositor
### New
* Support for new [driver `remote`](drivers/remote.md) that you can use
to connect to any already running BuildKit instance {% include github_issue.md repo="docker/buildx" number="1078" %}
{% include github_issue.md repo="docker/buildx" number="1093" %} {% include github_issue.md repo="docker/buildx" number="1094" %}
{% include github_issue.md repo="docker/buildx" number="1103" %} {% include github_issue.md repo="docker/buildx" number="1134" %}
{% include github_issue.md repo="docker/buildx" number="1204" %}
* You can now load Dockerfile from standard input even when the build context is
coming from external Git or HTTP URL {% include github_issue.md repo="docker/buildx" number="994" %}
* Build commands now support new the build context type `oci-layout://` for loading
- Support for a new [`remote` driver](drivers/remote.md) that you can use
to connect to any already running BuildKit instance.
[docker/buildx#1078](https://github.com/docker/buildx/issues/1078),
[docker/buildx#1093](https://github.com/docker/buildx/issues/1093),
[docker/buildx#1094](https://github.com/docker/buildx/issues/1094),
[docker/buildx#1103](https://github.com/docker/buildx/issues/1103),
[docker/buildx#1134](https://github.com/docker/buildx/issues/1134),
[docker/buildx#1204](https://github.com/docker/buildx/issues/1204)
- You can now load Dockerfile from standard input even when the build context is
coming from external Git or HTTP URL. [docker/buildx#994](https://github.com/docker/buildx/issues/994)
- Build commands now support new the build context type `oci-layout://` for loading
[build context from local OCI layout directories](../engine/reference/commandline/buildx_build.md#source-oci-layout).
Note that this feature depends on an unreleased BuildKit feature and builder
instance from `moby/buildkit:master` needs to be used until BuildKit v0.11 is
released {% include github_issue.md repo="docker/buildx" number="1173" %}
* You can now use the new `--print` flag to run helper functions supported by the
released. [docker/buildx#1173](https://github.com/docker/buildx/issues/1173)
- You can now use the new `--print` flag to run helper functions supported by the
BuildKit frontend performing the build and print their results. You can use
this feature in Dockerfile to show the build arguments and secrets that the
current build supports with `--print=outline` and list all available
Dockerfile stages with `--print=targets`. This feature is experimental for
gathering early feedback and requires enabling `BUILDX_EXPERIMENTAL=1`
environment variable. We plan to update/extend this feature in the future
without keeping backward compatibility {% include github_issue.md repo="docker/buildx" number="1100" %}
{% include github_issue.md repo="docker/buildx" number="1272" %}
* You can now use the new `--invoke` flag to launch interactive containers from
without keeping backward compatibility. [docker/buildx#1100](https://github.com/docker/buildx/issues/1100),
[docker/buildx#1272](https://github.com/docker/buildx/issues/1272)
- You can now use the new `--invoke` flag to launch interactive containers from
build results for an interactive debugging cycle. You can reload these
containers with code changes or restore them to an initial state from the
special monitor mode. This feature is experimental for gathering early
feedback and requires enabling `BUILDX_EXPERIMENTAL=1` environment variable.
We plan to update/extend this feature in the future without enabling backward
compatibility {% include github_issue.md repo="docker/buildx" number="1168" %}
{% include github_issue.md repo="docker/buildx" number="1257" %} {% include github_issue.md repo="docker/buildx" number="1259" %}
* Buildx now understands environment variable `BUILDKIT_COLORS` and `NO_COLOR`
to customize/disable the colors of interactive build progressbar {% include github_issue.md repo="docker/buildx" number="1230" %}
{% include github_issue.md repo="docker/buildx" number="1226" %}
* `buildx ls` command now shows the current BuildKit version of each builder
instance {% include github_issue.md repo="docker/buildx" number="998" %}
* The `bake` command now loads `.env` file automatically when building Compose
files for compatibility {% include github_issue.md repo="docker/buildx" number="1261" %}
* Bake now supports Compose files with `cache_to` definition {% include github_issue.md repo="docker/buildx" number="1155" %}
* Bake now supports new builtin function `timestamp()` to access current time {% include github_issue.md repo="docker/buildx" number="1214" %}
* Bake now supports Compose build secrets definition {% include github_issue.md repo="docker/buildx" number="1069" %}
* Additional build context configuration is now supported in Compose files via `x-bake` {% include github_issue.md repo="docker/buildx" number="1256" %}
* Inspecting builder now shows current driver options configuration {% include github_issue.md repo="docker/buildx" number="1003" %}
{% include github_issue.md repo="docker/buildx" number="1066" %}
compatibility.
[docker/buildx#1168](https://github.com/docker/buildx/issues/1168),
[docker/buildx#1257](https://github.com/docker/buildx),
[docker/buildx#1259](https://github.com/docker/buildx/issues/1259)
- Buildx now understands environment variable `BUILDKIT_COLORS` and `NO_COLOR`
to customize/disable the colors of interactive build progressbar. [docker/buildx#1230](https://github.com/docker/buildx/issues/1230),
[docker/buildx#1226](https://github.com/docker/buildx/issues/1226)
- `buildx ls` command now shows the current BuildKit version of each builder
instance. [docker/buildx#998](https://github.com/docker/buildx/issues/998)
- The `bake` command now loads `.env` file automatically when building Compose
files for compatibility. [docker/buildx#1261](https://github.com/docker/buildx/issues/1261)
- Bake now supports Compose files with `cache_to` definition. [docker/buildx#1155](https://github.com/docker/buildx/issues/1155)
- Bake now supports new builtin function `timestamp()` to access current time. [docker/buildx#1214](https://github.com/docker/buildx/issues/1214)
- Bake now supports Compose build secrets definition. [docker/buildx#1069](https://github.com/docker/buildx/issues/1069)
- Additional build context configuration is now supported in Compose files via `x-bake`. [docker/buildx#1256](https://github.com/docker/buildx/issues/1256)
- Inspecting builder now shows current driver options configuration. [docker/buildx#1003](https://github.com/docker/buildx/issues/1003),
[docker/buildx#1066](https://github.com/docker/buildx/issues/1066)
### Updates
* Updated the Compose Specification to 1.4.0 {% include github_issue.md repo="docker/buildx" number="1246" %}
{% include github_issue.md repo="docker/buildx" number="1251" %}
- Updated the Compose Specification to 1.4.0. [docker/buildx#1246](https://github.com/docker/buildx/issues/1246),
[docker/buildx#1251](https://github.com/docker/buildx/issues/1251)
### Bug fixes and enhancements
* The `buildx ls` command output has been updated with better access to errors
from different builders {% include github_issue.md repo="docker/buildx" number="1109" %}
* The `buildx create` command now performs additional validation of builder parameters
to avoid creating a builder instance with invalid configuration {% include github_issue.md repo="docker/buildx" number="1206" %}
* The `buildx imagetools create` command can now create new multi-platform images
- The `buildx ls` command output has been updated with better access to errors
from different builders. [docker/buildx#1109](https://github.com/docker/buildx/issues/1109)
- The `buildx create` command now performs additional validation of builder parameters
to avoid creating a builder instance with invalid configuration. [docker/buildx#1206](https://github.com/docker/buildx/issues/1206)
- The `buildx imagetools create` command can now create new multi-platform images
even if the source subimages are located on different repositories or
registries {% include github_issue.md repo="docker/buildx" number="1137" %}
* You can now set the default builder config that is used when creating
builder instances without passing custom `--config` value {% include github_issue.md repo="docker/buildx" number="1111" %}
* Docker driver can now detect if `dockerd` instance supports initially
disabled Buildkit features like multi-platform images {% include github_issue.md repo="docker/buildx" number="1260" %}
{% include github_issue.md repo="docker/buildx" number="1262" %}
* Compose files using targets with `.` in the name are now converted to use `_`
so the selector keys can still be used in such targets {% include github_issue.md repo="docker/buildx" number="1011" %}
* Included an additional validation for checking valid driver configurations {% include github_issue.md repo="docker/buildx" number="1188" %}
{% include github_issue.md repo="docker/buildx" number="1273" %}
* The `remove` command now displays the removed builder and forbids removing
context builders {% include github_issue.md repo="docker/buildx" number="1128" %}
* Enable Azure authentication when using Kubernetes driver {% include github_issue.md repo="docker/buildx" number="974" %}
* Add tolerations handling for kubernetes driver {% include github_issue.md repo="docker/buildx" number="1045" %}
{% include github_issue.md repo="docker/buildx" number="1053" %}
* Replace deprecated seccomp annotations with `securityContext` in kubernetes
driver {% include github_issue.md repo="docker/buildx" number="1052" %}
* Fix panic on handling manifests with nil platform {% include github_issue.md repo="docker/buildx" number="1144" %}
* Fix using duration filter with `prune` command {% include github_issue.md repo="docker/buildx" number="1252" %}
* Fix merging multiple JSON files on Bake definition {% include github_issue.md repo="docker/buildx" number="1025" %}
* Fix issues with implicit builder created from Docker context had invalid
configuration or dropped connection {% include github_issue.md repo="docker/buildx" number="1129" %}
* Fix conditions for showing no-output warning when using named contexts {% include github_issue.md repo="docker/buildx" number="968" %}
* Fix duplicating builders when builder instance and docker context have the
same name {% include github_issue.md repo="docker/buildx" number="1131" %}
* Fix printing unnecessary SSH warning logs {% include github_issue.md repo="docker/buildx" number="1085" %}
* Fix possible panic when using an empty variable block with Bake JSON
definition {% include github_issue.md repo="docker/buildx" number="1080" %}
* Fix image tools commands not handling `--builder` flag correctly {% include github_issue.md repo="docker/buildx" number="1067" %}
* Fix using custom image together with rootless option {% include github_issue.md repo="docker/buildx" number="1063" %}
registries. [docker/buildx#1137](https://github.com/docker/buildx/issues/1137)
- You can now set the default builder config that is used when creating
builder instances without passing custom `--config` value. [docker/buildx#1111](https://github.com/docker/buildx/issues/1111)
- Docker driver can now detect if `dockerd` instance supports initially
disabled Buildkit features like multi-platform images. [docker/buildx#1260](https://github.com/docker/buildx/issues/1260),
[docker/buildx#1262](https://github.com/docker/buildx/issues/1262)
- Compose files using targets with `.` in the name are now converted to use `_`
so the selector keys can still be used in such targets. [docker/buildx#1011](https://github.com/docker/buildx/issues/1011)
- Included an additional validation for checking valid driver configurations. [docker/buildx#1188](https://github.com/docker/buildx/issues/1188),
[docker/buildx#1273](https://github.com/docker/buildx/issues/1273)
- The `remove` command now displays the removed builder and forbids removing
context builders. [docker/buildx#1128](https://github.com/docker/buildx/issues/1128)
- Enable Azure authentication when using Kubernetes driver. [docker/buildx#974](https://github.com/docker/buildx/issues/974)
- Add tolerations handling for kubernetes driver. [docker/buildx#1045](https://github.com/docker/buildx/issues/1045)
[docker/buildx#1053](https://github.com/docker/buildx/issues/1053)
- Replace deprecated seccomp annotations with `securityContext` in the `kubernetes` driver.
[docker/buildx#1052](https://github.com/docker/buildx/issues/1052)
- Fix panic on handling manifests with nil platform. [docker/buildx#1144](https://github.com/docker/buildx/issues/1144)
- Fix using duration filter with `prune` command. [docker/buildx#1252](https://github.com/docker/buildx/issues/1252)
- Fix merging multiple JSON files on Bake definition. [docker/buildx#1025](https://github.com/docker/buildx/issues/1025)
- Fix issues with implicit builder created from Docker context had invalid
configuration or dropped connection. [docker/buildx#1129](https://github.com/docker/buildx/issues/1129)
- Fix conditions for showing no-output warning when using named contexts. [docker/buildx#968](https://github.com/docker/buildx/issues/968)
- Fix duplicating builders when builder instance and docker context have the
same name. [docker/buildx#1131](https://github.com/docker/buildx/issues/1131)
- Fix printing unnecessary SSH warning logs. [docker/buildx#1085](https://github.com/docker/buildx/issues/1085)
- Fix possible panic when using an empty variable block with Bake JSON
definition. [docker/buildx#1080](https://github.com/docker/buildx/issues/1080)
- Fix image tools commands not handling `--builder` flag correctly. [docker/buildx#1067](https://github.com/docker/buildx/issues/1067)
- Fix using custom image together with rootless option. [docker/buildx#1063](https://github.com/docker/buildx/issues/1063)
For more details, see the complete release notes in the [Buildx GitHub repository](https://github.com/docker/buildx/releases/tag/v0.9.0).
@ -356,11 +368,13 @@ For more details, see the complete release notes in the [Buildx GitHub repositor
{{< release-date date="2022-04-04" >}}
### Updates
* Update Compose spec used by `buildx bake` to v1.2.1 to fix parsing ports definition {% include github_issue.md repo="docker/buildx" number="1033" %}
- Update Compose spec used by `buildx bake` to v1.2.1 to fix parsing ports definition. [docker/buildx#1033](https://github.com/docker/buildx/issues/1033)
### Bug fixes and enhancements
* Fix possible crash on handling progress streams from BuildKit v0.10 {% include github_issue.md repo="docker/buildx" number="1042" %}
* Fix parsing groups in `buildx bake` when already loaded by a parent group {% include github_issue.md repo="docker/buildx" number="1021" %}
- Fix possible crash on handling progress streams from BuildKit v0.10. [docker/buildx#1042](https://github.com/docker/buildx/issues/1042)
- Fix parsing groups in `buildx bake` when already loaded by a parent group. [docker/buildx#1021](https://github.com/docker/buildx/issues/1021)
For more details, see the complete release notes in the [Buildx GitHub repository](https://github.com/docker/buildx/releases/tag/v0.8.2).
@ -370,8 +384,8 @@ For more details, see the complete release notes in the [Buildx GitHub repositor
### Bug fixes and enhancements
* Fix possible panic on handling build context scanning errors {% include github_issue.md repo="docker/buildx" number="1005" %}
* Allow `.` on Compose target names in `buildx bake` for backward compatibility {% include github_issue.md repo="docker/buildx" number="1018" %}
- Fix possible panic on handling build context scanning errors. [docker/buildx#1005](https://github.com/docker/buildx/issues/1005)
- Allow `.` on Compose target names in `buildx bake` for backward compatibility. [docker/buildx#1018](https://github.com/docker/buildx/issues/1018)
For more details, see the complete release notes in the [Buildx GitHub repository](https://github.com/docker/buildx/releases/tag/v0.8.1).
@ -381,47 +395,50 @@ For more details, see the complete release notes in the [Buildx GitHub repositor
### New
* Build command now accepts `--build-context` flag to [define additional named build contexts](/engine/reference/commandline/buildx_build/#build-context)
for your builds {% include github_issue.md repo="docker/buildx" number="904" %}
* Bake definitions now support [defining dependencies between targets](bake/build-contexts.md)
and using the result of one target in another build {% include github_issue.md repo="docker/buildx" number="928" %}
{% include github_issue.md repo="docker/buildx" number="965" %} {% include github_issue.md repo="docker/buildx" number="963" %}
{% include github_issue.md repo="docker/buildx" number="962" %} {% include github_issue.md repo="docker/buildx" number="981" %}
* `imagetools inspect` now accepts `--format` flag allowing access to config
and buildinfo for specific images {% include github_issue.md repo="docker/buildx" number="854" %}
{% include github_issue.md repo="docker/buildx" number="972" %}
* New flag `--no-cache-filter` allows configuring build, so it ignores cache
only for specified Dockerfile stages {% include github_issue.md repo="docker/buildx" number="860" %}
* Builds can now show a summary of warnings sets by the building frontend {% include github_issue.md repo="docker/buildx" number="892" %}
* The new build argument `BUILDKIT_INLINE_BUILDINFO_ATTRS` allows opting-in to embed
building attributes to resulting image {% include github_issue.md repo="docker/buildx" number="908" %}
* The new flag `--keep-buildkitd` allows keeping BuildKit daemon running when removing a builder
* {% include github_issue.md repo="docker/buildx" number="852" %}
- Build command now accepts `--build-context` flag to [define additional named build contexts](/engine/reference/commandline/buildx_build/#build-context)
for your builds. [docker/buildx#904](https://github.com/docker/buildx/issues/904)
- Bake definitions now support [defining dependencies between targets](bake/build-contexts.md)
and using the result of one target in another build.
[docker/buildx#928](https://github.com/docker/buildx/issues/928),
[docker/buildx#965](https://github.com/docker/buildx/issues/965),
[docker/buildx#963](https://github.com/docker/buildx/issues/963),
[docker/buildx#962](https://github.com/docker/buildx/issues/962),
[docker/buildx#981](https://github.com/docker/buildx/issues/981)
- `imagetools inspect` now accepts `--format` flag allowing access to config
and buildinfo for specific images. [docker/buildx#854](https://github.com/docker/buildx/issues/854),
[docker/buildx#972](https://github.com/docker/buildx/issues/972)
- New flag `--no-cache-filter` allows configuring build, so it ignores cache
only for specified Dockerfile stages. [docker/buildx#860](https://github.com/docker/buildx/issues/860)
- Builds can now show a summary of warnings sets by the building frontend. [docker/buildx#892](https://github.com/docker/buildx/issues/892)
- The new build argument `BUILDKIT_INLINE_BUILDINFO_ATTRS` allows opting-in to embed
building attributes to resulting image. [docker/buildx#908](https://github.com/docker/buildx/issues/908)
- The new flag `--keep-buildkitd` allows keeping BuildKit daemon running when removing a builder
- [docker/buildx#852](https://github.com/docker/buildx/issues/852)
### Bug fixes and enhancements
* `--metadata-file` output now supports embedded structure types {% include github_issue.md repo="docker/buildx" number="946" %}
* `buildx rm` now accepts new flag `--all-inactive` for removing all builders
that are not currently running {% include github_issue.md repo="docker/buildx" number="885" %}
* Proxy config is now read from Docker configuration file and sent with build
requests for backward compatibility {% include github_issue.md repo="docker/buildx" number="959" %}
* Support host networking in Compose {% include github_issue.md repo="docker/buildx" number="905" %}
{% include github_issue.md repo="docker/buildx" number="880" %}
* Bake files can now be read from stdin with `-f -` {% include github_issue.md repo="docker/buildx" number="864" %}
* `--iidfile` now always writes the image config digest independently of the
driver being used (use `--metadata-file` for digest) {% include github_issue.md repo="docker/buildx" number="980" %}
* Target names in Bake are now restricted to not use special characters {% include github_issue.md repo="docker/buildx" number="929" %}
* Image manifest digest can be read from metadata when pushed with `docker`
driver {% include github_issue.md repo="docker/buildx" number="989" %}
* Fix environment file handling in Compose files {% include github_issue.md repo="docker/buildx" number="905" %}
* Show last access time in `du` command {% include github_issue.md repo="docker/buildx" number="867" %}
* Fix possible double output logs when multiple Bake targets run same build
steps {% include github_issue.md repo="docker/buildx" number="977" %}
* Fix possible errors on multi-node builder building multiple targets with
mixed platform {% include github_issue.md repo="docker/buildx" number="985" %}
* Fix some nested inheritance cases in Bake {% include github_issue.md repo="docker/buildx" number="914" %}
* Fix printing default group on Bake files {% include github_issue.md repo="docker/buildx" number="884" %}
* Fix `UsernsMode` when using rootless container {% include github_issue.md repo="docker/buildx" number="887" %}
- `--metadata-file` output now supports embedded structure types. [docker/buildx#946](https://github.com/docker/buildx/issues/946)
- `buildx rm` now accepts new flag `--all-inactive` for removing all builders
that are not currently running. [docker/buildx#885](https://github.com/docker/buildx/issues/885)
- Proxy config is now read from Docker configuration file and sent with build
requests for backward compatibility. [docker/buildx#959](https://github.com/docker/buildx/issues/959)
- Support host networking in Compose. [docker/buildx#905](https://github.com/docker/buildx/issues/905),
[docker/buildx#880](https://github.com/docker/buildx/issues/880)
- Bake files can now be read from stdin with `-f -`. [docker/buildx#864](https://github.com/docker/buildx/issues/864)
- `--iidfile` now always writes the image config digest independently of the
driver being used (use `--metadata-file` for digest). [docker/buildx#980](https://github.com/docker/buildx/issues/980)
- Target names in Bake are now restricted to not use special characters. [docker/buildx#929](https://github.com/docker/buildx/issues/929)
- Image manifest digest can be read from metadata when pushed with `docker`
driver. [docker/buildx#989](https://github.com/docker/buildx/issues/989)
- Fix environment file handling in Compose files. [docker/buildx#905](https://github.com/docker/buildx/issues/905)
- Show last access time in `du` command. [docker/buildx#867](https://github.com/docker/buildx/issues/867)
- Fix possible double output logs when multiple Bake targets run same build
steps. [docker/buildx#977](https://github.com/docker/buildx/issues/977)
- Fix possible errors on multi-node builder building multiple targets with
mixed platform. [docker/buildx#985](https://github.com/docker/buildx/issues/985)
- Fix some nested inheritance cases in Bake. [docker/buildx#914](https://github.com/docker/buildx/issues/914)
- Fix printing default group on Bake files. [docker/buildx#884](https://github.com/docker/buildx/issues/884)
- Fix `UsernsMode` when using rootless container. [docker/buildx#887](https://github.com/docker/buildx/issues/887)
For more details, see the complete release notes in the [Buildx GitHub repository](https://github.com/docker/buildx/releases/tag/v0.8.0).
@ -431,8 +448,8 @@ For more details, see the complete release notes in the [Buildx GitHub repositor
### Fixes
* Fix issue with matching exclude rules in `.dockerignore` {% include github_issue.md repo="docker/buildx" number="858" %}
* Fix `bake --print` JSON output for current group {% include github_issue.md repo="docker/buildx" number="857" %}
- Fix issue with matching exclude rules in `.dockerignore`. [docker/buildx#858](https://github.com/docker/buildx/issues/858)
- Fix `bake --print` JSON output for current group. [docker/buildx#857](https://github.com/docker/buildx/issues/857)
For more details, see the complete release notes in the [Buildx GitHub repository](https://github.com/docker/buildx/releases/tag/v0.7.1).
@ -442,42 +459,42 @@ For more details, see the complete release notes in the [Buildx GitHub repositor
### New features
* TLS certificates from BuildKit configuration are now transferred to build
container with `docker-container` and `kubernetes` drivers {% include github_issue.md repo="docker/buildx" number="787" %}
* Builds support `--ulimit` flag for feature parity {% include github_issue.md repo="docker/buildx" number="800" %}
* Builds support `--shm-size` flag for feature parity {% include github_issue.md repo="docker/buildx" number="790" %}
* Builds support `--quiet` for feature parity {% include github_issue.md repo="docker/buildx" number="740" %}
* Builds support `--cgroup-parent` flag for feature parity {% include github_issue.md repo="docker/buildx" number="814" %}
* Bake supports builtin variable `BAKE_LOCAL_PLATFORM` {% include github_issue.md repo="docker/buildx" number="748" %}
* Bake supports `x-bake` extension field in Compose files {% include github_issue.md repo="docker/buildx" number="721" %}
* `kubernetes` driver now supports colon-separated `KUBECONFIG` {% include github_issue.md repo="docker/buildx" number="761" %}
* `kubernetes` driver now supports setting Buildkit config file with `--config` {% include github_issue.md repo="docker/buildx" number="682" %}
* `kubernetes` driver now supports installing QEMU emulators with driver-opt {% include github_issue.md repo="docker/buildx" number="682" %}
- TLS certificates from BuildKit configuration are now transferred to build
container with `docker-container` and `kubernetes` drivers. [docker/buildx#787](https://github.com/docker/buildx/issues/787)
- Builds support `--ulimit` flag for feature parity. [docker/buildx#800](https://github.com/docker/buildx/issues/800)
- Builds support `--shm-size` flag for feature parity. [docker/buildx#790](https://github.com/docker/buildx/issues/790)
- Builds support `--quiet` for feature parity. [docker/buildx#740](https://github.com/docker/buildx/issues/740)
- Builds support `--cgroup-parent` flag for feature parity. [docker/buildx#814](https://github.com/docker/buildx/issues/814)
- Bake supports builtin variable `BAKE_LOCAL_PLATFORM`. [docker/buildx#748](https://github.com/docker/buildx/issues/748)
- Bake supports `x-bake` extension field in Compose files. [docker/buildx#721](https://github.com/docker/buildx/issues/721)
- `kubernetes` driver now supports colon-separated `KUBECONFIG`. [docker/buildx#761](https://github.com/docker/buildx/issues/761)
- `kubernetes` driver now supports setting Buildkit config file with `--config`. [docker/buildx#682](https://github.com/docker/buildx/issues/682)
- `kubernetes` driver now supports installing QEMU emulators with driver-opt. [docker/buildx#682](https://github.com/docker/buildx/issues/682)
### Enhancements
* Allow using custom registry configuration for multi-node pushes from the
client {% include github_issue.md repo="docker/buildx" number="825" %}
* Allow using custom registry configuration for `buildx imagetools` command {% include github_issue.md repo="docker/buildx" number="825" %}
* Allow booting builder after creating with `buildx create --bootstrap` {% include github_issue.md repo="docker/buildx" number="692" %}
* Allow `registry:insecure` output option for multi-node pushes {% include github_issue.md repo="docker/buildx" number="825" %}
* BuildKit config and TLS files are now kept in Buildx state directory and
reused if BuildKit instance needs to be recreated {% include github_issue.md repo="docker/buildx" number="824" %}
* Ensure different projects use separate destination directories for
incremental context transfer for better performance {% include github_issue.md repo="docker/buildx" number="817" %}
* Build containers are now placed on separate cgroup by default {% include github_issue.md repo="docker/buildx" number="782" %}
* Bake now prints the default group with `--print` {% include github_issue.md repo="docker/buildx" number="720" %}
* `docker` driver now dials build session over HTTP for better performance {% include github_issue.md repo="docker/buildx" number="804" %}
- Allow using custom registry configuration for multi-node pushes from the
client. [docker/buildx#825](https://github.com/docker/buildx/issues/825)
- Allow using custom registry configuration for `buildx imagetools` command. [docker/buildx#825](https://github.com/docker/buildx/issues/825)
- Allow booting builder after creating with `buildx create --bootstrap`. [docker/buildx#692](https://github.com/docker/buildx/issues/692)
- Allow `registry:insecure` output option for multi-node pushes. [docker/buildx#825](https://github.com/docker/buildx/issues/825)
- BuildKit config and TLS files are now kept in Buildx state directory and
reused if BuildKit instance needs to be recreated. [docker/buildx#824](https://github.com/docker/buildx/issues/824)
- Ensure different projects use separate destination directories for
incremental context transfer for better performance. [docker/buildx#817](https://github.com/docker/buildx/issues/817)
- Build containers are now placed on separate cgroup by default. [docker/buildx#782](https://github.com/docker/buildx/issues/782)
- Bake now prints the default group with `--print`. [docker/buildx#720](https://github.com/docker/buildx/issues/720)
- `docker` driver now dials build session over HTTP for better performance. [docker/buildx#804](https://github.com/docker/buildx/issues/804)
### Fixes
* Fix using `--iidfile` together with a multi-node push {% include github_issue.md repo="docker/buildx" number="826" %}
* Using `--push` in Bake does not clear other image export options in the file {% include github_issue.md repo="docker/buildx" number="773" %}
* Fix Git URL detection for `buildx bake` when `https` protocol was used {% include github_issue.md repo="docker/buildx" number="822" %}
* Fix pushing image with multiple names on multi-node builds {% include github_issue.md repo="docker/buildx" number="815" %}
* Avoid showing `--builder` flags for commands that don't use it {% include github_issue.md repo="docker/buildx" number="818" %}
* Unsupported build flags now show a warning {% include github_issue.md repo="docker/buildx" number="810" %}
* Fix reporting error details in some OpenTelemetry traces {% include github_issue.md repo="docker/buildx" number="812" %}
- Fix using `--iidfile` together with a multi-node push. [docker/buildx#826](https://github.com/docker/buildx/issues/826)
- Using `--push` in Bake does not clear other image export options in the file. [docker/buildx#773](https://github.com/docker/buildx/issues/773)
- Fix Git URL detection for `buildx bake` when `https` protocol was used. [docker/buildx#822](https://github.com/docker/buildx/issues/822)
- Fix pushing image with multiple names on multi-node builds. [docker/buildx#815](https://github.com/docker/buildx/issues/815)
- Avoid showing `--builder` flags for commands that don't use it. [docker/buildx#818](https://github.com/docker/buildx/issues/818)
- Unsupported build flags now show a warning. [docker/buildx#810](https://github.com/docker/buildx/issues/810)
- Fix reporting error details in some OpenTelemetry traces. [docker/buildx#812](https://github.com/docker/buildx/issues/812)
For more details, see the complete release notes in the [Buildx GitHub repository](https://github.com/docker/buildx/releases/tag/v0.7.0).
@ -487,7 +504,7 @@ For more details, see the complete release notes in the [Buildx GitHub repositor
### Fixes
* Fix BuildKit state volume location for Windows clients {% include github_issue.md repo="docker/buildx" number="751" %}
- Fix BuildKit state volume location for Windows clients. [docker/buildx#751](https://github.com/docker/buildx/issues/751)
For more details, see the complete release notes in the [Buildx GitHub repository](https://github.com/docker/buildx/releases/tag/v0.6.3).
@ -499,7 +516,7 @@ For more details, see the complete release notes in the [Buildx GitHub repositor
### Fixes
* Fix connection error showing up in some SSH configurations {% include github_issue.md repo="docker/buildx" number="741" %}
- Fix connection error showing up in some SSH configurations. [docker/buildx#741](https://github.com/docker/buildx/issues/741)
## 0.6.1
@ -507,12 +524,12 @@ For more details, see the complete release notes in the [Buildx GitHub repositor
### Enhancements
* Set `ConfigFile` to parse compose files with Bake {% include github_issue.md repo="docker/buildx" number="704" %}
- Set `ConfigFile` to parse compose files with Bake. [docker/buildx#704](https://github.com/docker/buildx/issues/704)
### Fixes
* Duplicate progress env var {% include github_issue.md repo="docker/buildx" number="693" %}
* Should ignore nil client {% include github_issue.md repo="docker/buildx" number="686" %}
- Duplicate progress env var. [docker/buildx#693](https://github.com/docker/buildx/issues/693)
- Should ignore nil client. [docker/buildx#686](https://github.com/docker/buildx/issues/686)
For more details, see the complete release notes in the [Buildx GitHub repository](https://github.com/docker/buildx/releases/tag/v0.6.1).
@ -522,46 +539,48 @@ For more details, see the complete release notes in the [Buildx GitHub repositor
### New features
* Support for OpenTelemetry traces and forwarding Buildx client traces to
BuildKit {% include github_issue.md repo="docker/buildx" number="635" %}
* Experimental GitHub Actions remote cache backend with `--cache-to type=gha`
and `--cache-from type=gha` {% include github_issue.md repo="docker/buildx" number="535" %}
* New `--metadata-file` flag has been added to build and Bake command that
allows saving build result metadata in JSON format {% include github_issue.md repo="docker/buildx" number="605" %}
* This is the first release supporting Windows ARM64 {% include github_issue.md repo="docker/buildx" number="654" %}
* This is the first release supporting Linux Risc-V {% include github_issue.md repo="docker/buildx" number="652" %}
* Bake now supports building from remote definition with local files or
another remote source as context {% include github_issue.md repo="docker/buildx" number="671" %}
* Bake now allows variables to reference each other and using user functions
in variables and vice-versa {% include github_issue.md repo="docker/buildx" number="575" %}
{% include github_issue.md repo="docker/buildx" number="539" %} {% include github_issue.md repo="docker/buildx" number="532" %}
* Bake allows defining attributes in the global scope {% include github_issue.md repo="docker/buildx" number="541" %}
* Bake allows variables across multiple files {% include github_issue.md repo="docker/buildx" number="538" %}
* New quiet mode has been added to progress printer {% include github_issue.md repo="docker/buildx" number="558" %}
* `kubernetes` driver now supports defining resources/limits {% include github_issue.md repo="docker/buildx" number="618" %}
* Buildx binaries can now be accessed through [buildx-bin](https://hub.docker.com/r/docker/buildx-bin)
Docker image {% include github_issue.md repo="docker/buildx" number="656" %}
- Support for OpenTelemetry traces and forwarding Buildx client traces to
BuildKit. [docker/buildx#635](https://github.com/docker/buildx/issues/635)
- Experimental GitHub Actions remote cache backend with `--cache-to type=gha`
and `--cache-from type=gha`. [docker/buildx#535](https://github.com/docker/buildx/issues/535)
- New `--metadata-file` flag has been added to build and Bake command that
allows saving build result metadata in JSON format. [docker/buildx#605](https://github.com/docker/buildx/issues/605)
- This is the first release supporting Windows ARM64. [docker/buildx#654](https://github.com/docker/buildx/issues/654)
- This is the first release supporting Linux Risc-V. [docker/buildx#652](https://github.com/docker/buildx/issues/652)
- Bake now supports building from remote definition with local files or
another remote source as context. [docker/buildx#671](https://github.com/docker/buildx/issues/671)
- Bake now allows variables to reference each other and using user functions
in variables and vice-versa.
[docker/buildx#575](https://github.com/docker/buildx/issues/575),
[docker/buildx#539](https://github.com/docker/buildx/issues/539),
[docker/buildx#532](https://github.com/docker/buildx/issues/532)
- Bake allows defining attributes in the global scope. [docker/buildx#541](https://github.com/docker/buildx/issues/541)
- Bake allows variables across multiple files. [docker/buildx#538](https://github.com/docker/buildx/issues/538)
- New quiet mode has been added to progress printer. [docker/buildx#558](https://github.com/docker/buildx/issues/558)
- `kubernetes` driver now supports defining resources/limits. [docker/buildx#618](https://github.com/docker/buildx/issues/618)
- Buildx binaries can now be accessed through [buildx-bin](https://hub.docker.com/r/docker/buildx-bin)
Docker image. [docker/buildx#656](https://github.com/docker/buildx/issues/656)
### Enhancements
* `docker-container` driver now keeps BuildKit state in volume. Enabling
updates with keeping state {% include github_issue.md repo="docker/buildx" number="672" %}
* Compose parser is now based on new [compose-go parser](https://github.com/compose-spec/compose-go)
fixing support for some newer syntax {% include github_issue.md repo="docker/buildx" number="669" %}
* SSH socket is now automatically forwarded when building an ssh-based git URL {% include github_issue.md repo="docker/buildx" number="581" %}
* Bake HCL parser has been rewritten {% include github_issue.md repo="docker/buildx" number="645" %}
* Extend HCL support with more functions {% include github_issue.md repo="docker/buildx" number="491" %}
{% include github_issue.md repo="docker/buildx" number="503" %}
* Allow secrets from environment variables {% include github_issue.md repo="docker/buildx" number="488" %}
* Builds with an unsupported multi-platform and load configuration now fail fast {% include github_issue.md repo="docker/buildx" number="582" %}
* Store Kubernetes config file to make buildx builder switchable {% include github_issue.md repo="docker/buildx" number="497" %}
* Kubernetes now lists all pods as nodes on inspection {% include github_issue.md repo="docker/buildx" number="477" %}
* Default Rootless image has been set to `moby/buildkit:buildx-stable-1-rootless` {% include github_issue.md repo="docker/buildx" number="480" %}
- `docker-container` driver now keeps BuildKit state in volume. Enabling
updates with keeping state. [docker/buildx#672](https://github.com/docker/buildx/issues/672)
- Compose parser is now based on new [compose-go parser](https://github.com/compose-spec/compose-go)
fixing support for some newer syntax. [docker/buildx#669](https://github.com/docker/buildx/issues/669)
- SSH socket is now automatically forwarded when building an ssh-based git URL. [docker/buildx#581](https://github.com/docker/buildx/issues/581)
- Bake HCL parser has been rewritten. [docker/buildx#645](https://github.com/docker/buildx/issues/645)
- Extend HCL support with more functions. [docker/buildx#491](https://github.com/docker/buildx/issues/491)
[docker/buildx#503](https://github.com/docker/buildx/issues/503)
- Allow secrets from environment variables. [docker/buildx#488](https://github.com/docker/buildx/issues/488)
- Builds with an unsupported multi-platform and load configuration now fail fast. [docker/buildx#582](https://github.com/docker/buildx/issues/582)
- Store Kubernetes config file to make buildx builder switchable. [docker/buildx#497](https://github.com/docker/buildx/issues/497)
- Kubernetes now lists all pods as nodes on inspection. [docker/buildx#477](https://github.com/docker/buildx/issues/477)
- Default Rootless image has been set to `moby/buildkit:buildx-stable-1-rootless`. [docker/buildx#480](https://github.com/docker/buildx/issues/480)
### Fixes
* `imagetools create` command now correctly merges JSON descriptor with old one {% include github_issue.md repo="docker/buildx" number="592" %}
* Fix building with `--network=none` not requiring extra security entitlements {% include github_issue.md repo="docker/buildx" number="531" %}
- `imagetools create` command now correctly merges JSON descriptor with old one. [docker/buildx#592](https://github.com/docker/buildx/issues/592)
- Fix building with `--network=none` not requiring extra security entitlements. [docker/buildx#531](https://github.com/docker/buildx/issues/531)
For more details, see the complete release notes in the [Buildx GitHub repository](https://github.com/docker/buildx/releases/tag/v0.6.0).
@ -571,8 +590,8 @@ For more details, see the complete release notes in the [Buildx GitHub repositor
### Fixes
* Fix regression on setting `--platform` on `buildx create` outside
`kubernetes` driver {% include github_issue.md repo="docker/buildx" number="475" %}
- Fix regression on setting `--platform` on `buildx create` outside
`kubernetes` driver. [docker/buildx#475](https://github.com/docker/buildx/issues/475)
For more details, see the complete release notes in the [Buildx GitHub repository](https://github.com/docker/buildx/releases/tag/v0.5.1).
@ -582,38 +601,41 @@ For more details, see the complete release notes in the [Buildx GitHub repositor
### New features
* The `docker` driver now supports the `--push` flag {% include github_issue.md repo="docker/buildx" number="442" %}
* Bake supports inline Dockerfiles {% include github_issue.md repo="docker/buildx" number="398" %}
* Bake supports building from remote URLs and Git repositories {% include github_issue.md repo="docker/buildx" number="398" %}
* `BUILDX_CONFIG` env var allow users to have separate buildx state from
Docker config {% include github_issue.md repo="docker/buildx" number="385" %}
* `BUILDKIT_MULTI_PLATFORM` build arg allows to force building multi-platform
return objects even if only one `--platform` specified {% include github_issue.md repo="docker/buildx" number="467" %}
- The `docker` driver now supports the `--push` flag. [docker/buildx#442](https://github.com/docker/buildx/issues/442)
- Bake supports inline Dockerfiles. [docker/buildx#398](https://github.com/docker/buildx/issues/398)
- Bake supports building from remote URLs and Git repositories. [docker/buildx#398](https://github.com/docker/buildx/issues/398)
- `BUILDX_CONFIG` env var allow users to have separate buildx state from
Docker config. [docker/buildx#385](https://github.com/docker/buildx/issues/385)
- `BUILDKIT_MULTI_PLATFORM` build arg allows to force building multi-platform
return objects even if only one `--platform` specified. [docker/buildx#467](https://github.com/docker/buildx/issues/467)
### Enhancements
* Allow `--append` to be used with `kubernetes` driver {% include github_issue.md repo="docker/buildx" number="370" %}
* Build errors show error location in source files and system stacktraces
with `--debug` {% include github_issue.md repo="docker/buildx" number="389" %}
* Bake formats HCL errors with source definition {% include github_issue.md repo="docker/buildx" number="391" %}
* Bake allows empty string values in arrays that will be discarded {% include github_issue.md repo="docker/buildx" number="428" %}
* You can now use the Kubernetes cluster config with the `kubernetes` driver {% include github_issue.md repo="docker/buildx" number="368" %}
{% include github_issue.md repo="docker/buildx" number="460" %}
* Creates a temporary token for pulling images instead of sharing credentials
when possible {% include github_issue.md repo="docker/buildx" number="469" %}
* Ensure credentials are passed when pulling BuildKit container image {% include github_issue.md repo="docker/buildx" number="441" %}
{% include github_issue.md repo="docker/buildx" number="433" %}
* Disable user namespace remapping in `docker-container` driver {% include github_issue.md repo="docker/buildx" number="462" %}
* Allow `--builder` flag to switch to default instance {% include github_issue.md repo="docker/buildx" number="425" %}
* Avoid warn on empty `BUILDX_NO_DEFAULT_LOAD` config value {% include github_issue.md repo="docker/buildx" number="390" %}
* Replace error generated by `quiet` option by a warning {% include github_issue.md repo="docker/buildx" number="403" %}
* CI has been switched to GitHub Actions {% include github_issue.md repo="docker/buildx" number="451" %}
{% include github_issue.md repo="docker/buildx" number="463" %} {% include github_issue.md repo="docker/buildx" number="466" %}
{% include github_issue.md repo="docker/buildx" number="468" %} {% include github_issue.md repo="docker/buildx" number="471" %}
- Allow `--append` to be used with `kubernetes` driver. [docker/buildx#370](https://github.com/docker/buildx/issues/370)
- Build errors show error location in source files and system stacktraces
with `--debug`. [docker/buildx#389](https://github.com/docker/buildx/issues/389)
- Bake formats HCL errors with source definition. [docker/buildx#391](https://github.com/docker/buildx/issues/391)
- Bake allows empty string values in arrays that will be discarded. [docker/buildx#428](https://github.com/docker/buildx/issues/428)
- You can now use the Kubernetes cluster config with the `kubernetes` driver. [docker/buildx#368](https://github.com/docker/buildx/issues/368)
[docker/buildx#460](https://github.com/docker/buildx/issues/460)
- Creates a temporary token for pulling images instead of sharing credentials
when possible. [docker/buildx#469](https://github.com/docker/buildx/issues/469)
- Ensure credentials are passed when pulling BuildKit container image. [docker/buildx#441](https://github.com/docker/buildx/issues/441)
[docker/buildx#433](https://github.com/docker/buildx/issues/433)
- Disable user namespace remapping in `docker-container` driver. [docker/buildx#462](https://github.com/docker/buildx/issues/462)
- Allow `--builder` flag to switch to default instance. [docker/buildx#425](https://github.com/docker/buildx/issues/425)
- Avoid warn on empty `BUILDX_NO_DEFAULT_LOAD` config value. [docker/buildx#390](https://github.com/docker/buildx/issues/390)
- Replace error generated by `quiet` option by a warning. [docker/buildx#403](https://github.com/docker/buildx/issues/403)
- CI has been switched to GitHub Actions.
[docker/buildx#451](https://github.com/docker/buildx/issues/451),
[docker/buildx#463](https://github.com/docker/buildx/issues/463),
[docker/buildx#466](https://github.com/docker/buildx/issues/466),
[docker/buildx#468](https://github.com/docker/buildx/issues/468),
[docker/buildx#471](https://github.com/docker/buildx/issues/471)
### Fixes
* Handle lowercase Dockerfile name as a fallback for backward compatibility {% include github_issue.md repo="docker/buildx" number="444" %}
- Handle lowercase Dockerfile name as a fallback for backward compatibility. [docker/buildx#444](https://github.com/docker/buildx/issues/444)
For more details, see the complete release notes in the [Buildx GitHub repository](https://github.com/docker/buildx/releases/tag/v0.5.0).
@ -623,18 +645,18 @@ For more details, see the complete release notes in the [Buildx GitHub repositor
### New features
* Support `cacheonly` exporter {% include github_issue.md repo="docker/buildx" number="337" %}
- Support `cacheonly` exporter. [docker/buildx#337](https://github.com/docker/buildx/issues/337)
### Enhancements
* Update `go-cty` to pull in more `stdlib` functions {% include github_issue.md repo="docker/buildx" number="277" %}
* Improve error checking on load {% include github_issue.md repo="docker/buildx" number="281" %}
- Update `go-cty` to pull in more `stdlib` functions. [docker/buildx#277](https://github.com/docker/buildx/issues/277)
- Improve error checking on load. [docker/buildx#281](https://github.com/docker/buildx/issues/281)
### Fixes
* Fix parsing json config with HCL {% include github_issue.md repo="docker/buildx" number="280" %}
* Ensure `--builder` is wired from root options {% include github_issue.md repo="docker/buildx" number="321" %}
* Remove warning for multi-platform iidfile {% include github_issue.md repo="docker/buildx" number="351" %}
- Fix parsing json config with HCL. [docker/buildx#280](https://github.com/docker/buildx/issues/280)
- Ensure `--builder` is wired from root options. [docker/buildx#321](https://github.com/docker/buildx/issues/321)
- Remove warning for multi-platform iidfile. [docker/buildx#351](https://github.com/docker/buildx/issues/351)
For more details, see the complete release notes in the [Buildx GitHub repository](https://github.com/docker/buildx/releases/tag/v0.4.2).
@ -644,8 +666,8 @@ For more details, see the complete release notes in the [Buildx GitHub repositor
### Fixes
* Fix regression on flag parsing {% include github_issue.md repo="docker/buildx" number="268" %}
* Fix using pull and no-cache keys in HCL targets {% include github_issue.md repo="docker/buildx" number="268" %}
- Fix regression on flag parsing. [docker/buildx#268](https://github.com/docker/buildx/issues/268)
- Fix using pull and no-cache keys in HCL targets. [docker/buildx#268](https://github.com/docker/buildx/issues/268)
For more details, see the complete release notes in the [Buildx GitHub repository](https://github.com/docker/buildx/releases/tag/v0.4.1).
@ -655,17 +677,17 @@ For more details, see the complete release notes in the [Buildx GitHub repositor
### New features
* Add `kubernetes` driver {% include github_issue.md repo="docker/buildx" number="167" %}
* New global `--builder` flag to override builder instance for a single command {% include github_issue.md repo="docker/buildx" number="246" %}
* New `prune` and `du` commands for managing local builder cache {% include github_issue.md repo="docker/buildx" number="249" %}
* You can now set the new `pull` and `no-cache` options for HCL targets {% include github_issue.md repo="docker/buildx" number="165" %}
- Add `kubernetes` driver. [docker/buildx#167](https://github.com/docker/buildx/issues/167)
- New global `--builder` flag to override builder instance for a single command. [docker/buildx#246](https://github.com/docker/buildx/issues/246)
- New `prune` and `du` commands for managing local builder cache. [docker/buildx#249](https://github.com/docker/buildx/issues/249)
- You can now set the new `pull` and `no-cache` options for HCL targets. [docker/buildx#165](https://github.com/docker/buildx/issues/165)
### Enhancements
* Upgrade Bake to HCL2 with support for variables and functions {% include github_issue.md repo="docker/buildx" number="192" %}
* Bake now supports `--load` and `--push` {% include github_issue.md repo="docker/buildx" number="164" %}
* Bake now supports wildcard overrides for multiple targets {% include github_issue.md repo="docker/buildx" number="164" %}
* Container driver allows setting environment variables via `driver-opt` {% include github_issue.md repo="docker/buildx" number="170" %}
- Upgrade Bake to HCL2 with support for variables and functions. [docker/buildx#192](https://github.com/docker/buildx/issues/192)
- Bake now supports `--load` and `--push`. [docker/buildx#164](https://github.com/docker/buildx/issues/164)
- Bake now supports wildcard overrides for multiple targets. [docker/buildx#164](https://github.com/docker/buildx/issues/164)
- Container driver allows setting environment variables via `driver-opt`. [docker/buildx#170](https://github.com/docker/buildx/issues/170)
For more details, see the complete release notes in the [Buildx GitHub repository](https://github.com/docker/buildx/releases/tag/v0.4.0).
@ -675,13 +697,14 @@ For more details, see the complete release notes in the [Buildx GitHub repositor
### Enhancements
* Handle copying unix sockets instead of erroring {% include github_issue.md repo="docker/buildx" number="155" %}
{% include github_issue.md repo="moby/buildkit" number="1144" %}
- Handle copying unix sockets instead of erroring. [docker/buildx#155](https://github.com/docker/buildx/issues/155)
[moby/buildkit#1144](https://github.com/moby/buildkit/issues/1144)
### Fixes
* Running Bake with multiple Compose files now merges targets correctly {% include github_issue.md repo="docker/buildx" number="134" %}
* Fix bug when building a Dockerfile from stdin (`build -f -`) {% include github_issue.md repo="docker/buildx" number="153" %}
- Running Bake with multiple Compose files now merges targets correctly. [docker/buildx#134](https://github.com/docker/buildx/issues/134)
- Fix bug when building a Dockerfile from stdin (`build -f -`).
[docker/buildx#153](https://github.com/docker/buildx/issues/153)
For more details, see the complete release notes in the [Buildx GitHub repository](https://github.com/docker/buildx/releases/tag/v0.3.1).
@ -691,19 +714,19 @@ For more details, see the complete release notes in the [Buildx GitHub repositor
### New features
* Custom `buildkitd` daemon flags {% include github_issue.md repo="docker/buildx" number="102" %}
* Driver-specific options on `create` {% include github_issue.md repo="docker/buildx" number="122" %}
- Custom `buildkitd` daemon flags. [docker/buildx#102](https://github.com/docker/buildx/issues/102)
- Driver-specific options on `create`. [docker/buildx#122](https://github.com/docker/buildx/issues/122)
### Enhancements
* Environment variables are used in Compose files {% include github_issue.md repo="docker/buildx" number="117" %}
* Bake now honors `--no-cache` and `--pull` {% include github_issue.md repo="docker/buildx" number="118" %}
* Custom BuildKit config file {% include github_issue.md repo="docker/buildx" number="121" %}
* Entitlements support with `build --allow` {% include github_issue.md repo="docker/buildx" number="104" %}
- Environment variables are used in Compose files. [docker/buildx#117](https://github.com/docker/buildx/issues/117)
- Bake now honors `--no-cache` and `--pull`. [docker/buildx#118](https://github.com/docker/buildx/issues/118)
- Custom BuildKit config file. [docker/buildx#121](https://github.com/docker/buildx/issues/121)
- Entitlements support with `build --allow`. [docker/buildx#104](https://github.com/docker/buildx/issues/104)
### Fixes
* Fix bug where `--build-arg foo` would not read `foo` from environment {% include github_issue.md repo="docker/buildx" number="116" %}
- Fix bug where `--build-arg foo` would not read `foo` from environment. [docker/buildx#116](https://github.com/docker/buildx/issues/116)
For more details, see the complete release notes in the [Buildx GitHub repository](https://github.com/docker/buildx/releases/tag/v0.3.0).
@ -713,7 +736,7 @@ For more details, see the complete release notes in the [Buildx GitHub repositor
### Enhancements
* Change Compose file handling to require valid service specifications {% include github_issue.md repo="docker/buildx" number="87" %}
- Change Compose file handling to require valid service specifications. [docker/buildx#87](https://github.com/docker/buildx/issues/87)
For more details, see the complete release notes in the [Buildx GitHub repository](https://github.com/docker/buildx/releases/tag/v0.2.2).
@ -723,17 +746,17 @@ For more details, see the complete release notes in the [Buildx GitHub repositor
### New features
* Add `BUILDKIT_PROGRESS` env var {% include github_issue.md repo="docker/buildx" number="69" %}
* Add `local` platform {% include github_issue.md repo="docker/buildx" number="70" %}
- Add `BUILDKIT_PROGRESS` env var. [docker/buildx#69](https://github.com/docker/buildx/issues/69)
- Add `local` platform. [docker/buildx#70](https://github.com/docker/buildx/issues/70)
### Enhancements
* Keep arm variant if one is defined in the config {% include github_issue.md repo="docker/buildx" number="68" %}
* Make dockerfile relative to context {% include github_issue.md repo="docker/buildx" number="83" %}
- Keep arm variant if one is defined in the config. [docker/buildx#68](https://github.com/docker/buildx/issues/68)
- Make dockerfile relative to context. [docker/buildx#83](https://github.com/docker/buildx/issues/83)
### Fixes
* Fix parsing target from compose files {% include github_issue.md repo="docker/buildx" number="53" %}
- Fix parsing target from compose files. [docker/buildx#53](https://github.com/docker/buildx/issues/53)
For more details, see the complete release notes in the [Buildx GitHub repository](https://github.com/docker/buildx/releases/tag/v0.2.1).
@ -743,6 +766,6 @@ For more details, see the complete release notes in the [Buildx GitHub repositor
### New features
* First release
- First release
For more details, see the complete release notes in the [Buildx GitHub repository](https://github.com/docker/buildx/releases/tag/v0.2.0).

4
data/toc.yaml
View File

@ -1718,8 +1718,8 @@ Manuals:
title: Bake file reference
- path: /build/bake/configuring-build/
title: Configuring builds
- path: /build/bake/hcl-funcs/
title: User defined HCL functions
- path: /build/bake/advanced/
title: Advanced patterns
- path: /build/bake/build-contexts/
title: Build contexts and linking targets
- path: /build/bake/compose-file/