centersl/docker-docs
1
0
Fork 0
mirror of https://github.com/docker/docs.git synced 2026-03-27 06:18:55 +07:00
Code Issues Packages Projects Releases Wiki Activity

Update buildx reference to v0.28.0 (#23351)

Browse Source 
Update the buildx reference documentation to keep in sync with the
latest release `v0.28.0`

Signed-off-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: tonistiigi <585223+tonistiigi@users.noreply.github.com>
This commit is contained in:
docker-tools-robot
2025-09-04 09:46:24 +02:00
committed by GitHub
parent 8e1c55d3cd
commit e085bfab7c
6 changed files with 256 additions and 49 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
_vendor/modules.txt
View File

@@ -1,6 +1,6 @@
# github.com/moby/moby v28.3.3+incompatible
# github.com/moby/buildkit v0.23.2
# github.com/docker/buildx v0.27.0
# github.com/moby/buildkit v0.24.0
# github.com/docker/buildx v0.28.0
# github.com/docker/cli v28.3.3+incompatible
# github.com/docker/compose/v2 v2.39.2
# github.com/docker/model-cli v0.1.39

6
data/buildx/docker_buildx_dap_build.yaml
View File

@@ -520,16 +520,18 @@ examples: |-
Command line arguments may be passed to the debug adapter the same way they would be passed to the normal build command and they will set the value.
Launch request arguments that are set will override command line arguments if they are present.
A debug extension should include an `args` entry in the launch configuration and should append these arguments to the end of the tool invocation.
A debug extension should include an `args` and `builder` entry in the launch configuration. These will modify the arguments passed to the binary for the tool invocation.
`builder` will add `--builder <arg>` directly after the executable and `args` will append to the end of the tool invocation.
For example, a launch configuration in Visual Studio Code with the following:
```json
{
"args": ["--build-arg", "FOO=AAA"]
"builder": ["mybuilder"]
}
```
This should cause the debug adapter to be invoked as `docker buildx dap build --build-arg FOO=AAA`.
This should cause the debug adapter to be invoked as `docker buildx --builder mybuilder dap build --build-arg FOO=AAA`.
deprecated: false
hidden: false
experimental: false

180
data/buildx/docker_buildx_du.yaml
View File

@@ -8,6 +8,17 @@ options:
- option: filter
value_type: filter
description: Provide filter values
details_url: '#filter'
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: format
value_type: string
description: Format the output
details_url: '#format'
deprecated: false
hidden: false
experimental: false
@@ -17,7 +28,7 @@ options:
- option: verbose
value_type: bool
default_value: "false"
description: Provide a more verbose output
description: Shorthand for `--format=pretty`
details_url: '#verbose'
deprecated: false
hidden: false
@@ -77,7 +88,7 @@ examples: |-
the record, even if you use `--all`. That's because the record is actively in
use by some component of the builder.
The asterisks (\*) in the default output indicate the following:
The asterisks (\*) in the default output format indicate the following:
- An asterisk next to an ID (`zu7m6evdpebh5h8kfkpw9dlf2*`) indicates that the record
is mutable. The size of the record may change, or another build can take ownership of
@@ -88,33 +99,156 @@ examples: |-
If you prune such a record then you will lose build cache but only metadata
will be deleted as the image still needs to actual storage layers.
### Provide filter values (--filter) {#filter}
Same as [`buildx prune --filter`](/reference/cli/docker/buildx/prune/#filter).
### Format the output (--format) {#format}
The formatting options (`--format`) pretty-prints usage information output
using a Go template.
Valid placeholders for the Go template are:
* `.ID`
* `.Parents`
* `.CreatedAt`
* `.Mutable`
* `.Reclaimable`
* `.Shared`
* `.Size`
* `.Description`
* `.UsageCount`
* `.LastUsedAt`
* `.Type`
When using the `--format` option, the `du` command will either output the data
exactly as the template declares or, when using the `table` directive, includes
column headers as well.
The `pretty` format is useful for inspecting the disk usage records in more
detail. It shows the mutable and shared states more clearly, as well as
additional information about the corresponding layer:
```console
$ docker buildx du --format=pretty
...
ID: 6wqu0v6hjdwvhh8yjozrepaof
Parents:
- bqx15bcewecz4wcg14b7iodvp
Created at: 2025-06-12 15:44:02.715795569 +0000 UTC
Mutable: false
Reclaimable: true
Shared: true
Size: 1.653GB
Description: [build-base 4/4] COPY . .
Usage count: 1
Last used: 2 months ago
Type: regular
Shared: 35.57GB
Private: 97.94GB
Reclaimable: 131.5GB
Total: 133.5GB
```
The following example uses a template without headers and outputs the
`ID` and `Size` entries separated by a colon (`:`):
```console
$ docker buildx du --format "{{.ID}}: {{.Size}}"
6wqu0v6hjdwvhh8yjozrepaof: 1.653GB
4m8061kctvjyh9qleus8rgpgx: 1.723GB
fcm9mlz2641u8r5eicjqdhy1l: 1.841GB
z2qu1swvo3afzd9mhihi3l5k0: 1.873GB
nmi6asc00aa3ja6xnt6o7wbrr: 2.027GB
0qlam41jxqsq6i27yqllgxed3: 2.495GB
3w9qhzzskq5jc262snfu90bfz: 2.617GB
```
The following example uses a `table` template and outputs the `ID` and
`Description`:
```console
$ docker buildx du --format "table {{.ID}} {{.Description}}"
ID DESCRIPTION
03bbhchaib8cygqs68um6hfnl [binaries-linux 2/5] LINK COPY --link --from=binfmt-filter /out/ /
2h8un0tyg57oj64xvbas6mzea [cni-plugins-export 2/4] LINK COPY --link --from=cni-plugins /opt/cni/bin/loopback /buildkit-cni-loopback
evckox33t07ob9dmollhn4h4j [cni-plugins-export 3/4] LINK COPY --link --from=cni-plugins /opt/cni/bin/host-local /buildkit-cni-host-local
jlxzwcw6xaomxj8irerow9bhb [binaries-linux 4/5] LINK COPY --link --from=buildctl /usr/bin/buildctl /
ov2oetgebkhpsw39rv1sbh5w1 [buildkit-linux 1/1] LINK COPY --link --from=binaries / /usr/bin/
ruoczhyq25n5v9ld7n231zalx [binaries-linux 3/5] LINK COPY --link --from=cni-plugins-export-squashed / /
ax7cov6kizxi9ufvcwsef4occ* local source for context
```
JSON output is also supported and will print as newline delimited JSON:
```console
$ docker buildx du --format=json
{"CreatedAt":"2025-07-29T12:36:01Z","Description":"pulled from docker.io/library/rust:1.85.1-bookworm@sha256:e51d0265072d2d9d5d320f6a44dde6b9ef13653b035098febd68cce8fa7c0bc4","ID":"ic1gfidvev5nciupzz53alel4","LastUsedAt":"2025-07-29T12:36:01Z","Mutable":false,"Parents":["hmpdhm4sjrfpmae4xm2y3m0ra"],"Reclaimable":true,"Shared":false,"Size":"829889526","Type":"regular","UsageCount":1}
{"CreatedAt":"2025-08-05T09:24:09Z","Description":"pulled from docker.io/library/node:22@sha256:3218f0d1b9e4b63def322e9ae362d581fbeac1ef21b51fc502ef91386667ce92","ID":"jsw7fx09l5zsda3bri1z4mwk5","LastUsedAt":"2025-08-05T09:24:09Z","Mutable":false,"Parents":["098jsj5ebbv1w47ikqigeuurs"],"Reclaimable":true,"Shared":true,"Size":"829898832","Type":"regular","UsageCount":1}
```
You can use `jq` to pretty-print the JSON output:
```console
$ docker buildx du --format=json | jq .
{
"CreatedAt": "2025-07-29T12:36:01Z",
"Description": "pulled from docker.io/library/rust:1.85.1-bookworm@sha256:e51d0265072d2d9d5d320f6a44dde6b9ef13653b035098febd68cce8fa7c0bc4",
"ID": "ic1gfidvev5nciupzz53alel4",
"LastUsedAt": "2025-07-29T12:36:01Z",
"Mutable": false,
"Parents": [
"hmpdhm4sjrfpmae4xm2y3m0ra"
],
"Reclaimable": true,
"Shared": false,
"Size": "829889526",
"Type": "regular",
"UsageCount": 1
}
{
"CreatedAt": "2025-08-05T09:24:09Z",
"Description": "pulled from docker.io/library/node:22@sha256:3218f0d1b9e4b63def322e9ae362d581fbeac1ef21b51fc502ef91386667ce92",
"ID": "jsw7fx09l5zsda3bri1z4mwk5",
"LastUsedAt": "2025-08-05T09:24:09Z",
"Mutable": false,
"Parents": [
"098jsj5ebbv1w47ikqigeuurs"
],
"Reclaimable": true,
"Shared": true,
"Size": "829898832",
"Type": "regular",
"UsageCount": 1
}
```
### Use verbose output (--verbose) {#verbose}
The verbose output of the `docker buildx du` command is useful for inspecting
the disk usage records in more detail. The verbose output shows the mutable and
shared states more clearly, as well as additional information about the
corresponding layer.
Shorthand for [`--format=pretty`](#format):
```console
$ docker buildx du --verbose
...
Last used: 2 days ago
Type: regular
ID: 6wqu0v6hjdwvhh8yjozrepaof
Parents:
- bqx15bcewecz4wcg14b7iodvp
Created at: 2025-06-12 15:44:02.715795569 +0000 UTC
Mutable: false
Reclaimable: true
Shared: true
Size: 1.653GB
Description: [build-base 4/4] COPY . .
Usage count: 1
Last used: 2 months ago
Type: regular
ID: 05d0elirb4mmvpmnzbrp3ssrg
Parent: e8sfdn4mygrg7msi9ak1dy6op
Created at: 2023-11-20 09:53:30.881558721 +0000 UTC
Mutable: false
Reclaimable: true
Shared: false
Size: 0B
Description: [gobase 3/3] WORKDIR /src
Usage count: 3
Last used: 24 hours ago
Type: regular
Reclaimable: 4.453GB
Total: 4.453GB
Shared: 35.57GB
Private: 97.94GB
Reclaimable: 131.5GB
Total: 133.5GB
```
### Override the configured builder instance (--builder) {#builder}
@@ -122,7 +256,7 @@ examples: |-
Use the `--builder` flag to inspect the disk usage of a particular builder.
```console
$ docker buildx du --builder youthful_shtern
$ docker buildx du --builder mybuilder
ID RECLAIMABLE SIZE LAST ACCESSED
g41agepgdczekxg2mtw0dujsv* true 1.312GB 47 hours ago
e6ycrsa0bn9akigqgzu0sc6kr true 318MB 47 hours ago

107
data/buildx/docker_buildx_prune.yaml
View File

@@ -1,23 +1,6 @@
command: docker buildx prune
short: Remove build cache
long: |-
Clears the build cache of the selected builder.
You can finely control what cache data is kept using:
- The `--filter=until=<duration>` flag to keep images that have been used in
the last `<duration>` time.
`<duration>` is a duration string, e.g. `24h` or `2h30m`, with allowable
units of `(h)ours`, `(m)inutes` and `(s)econds`.
- The `--keep-storage=<size>` flag to keep `<size>` bytes of data in the cache.
`<size>` is a human-readable memory string, e.g. `128mb`, `2gb`, etc. Units
are case-insensitive.
- The `--all` flag to allow clearing internal helper images and frontend images
set using the `#syntax=` directive or the `BUILDKIT_SYNTAX` build argument.
long: Clears the build cache of the selected builder.
usage: docker buildx prune
pname: docker buildx
plink: docker_buildx.yaml
@@ -27,6 +10,7 @@ options:
value_type: bool
default_value: "false"
description: Include internal/frontend images
details_url: '#all'
deprecated: false
hidden: false
experimental: false
@@ -35,7 +19,8 @@ options:
swarm: false
- option: filter
value_type: filter
description: Provide filter values (e.g., `until=24h`)
description: Provide filter values
details_url: '#filter'
deprecated: false
hidden: false
experimental: false
@@ -67,6 +52,7 @@ options:
value_type: bytes
default_value: "0"
description: Maximum amount of disk space allowed to keep for cache
details_url: '#max-used-space'
deprecated: false
hidden: false
experimental: false
@@ -77,6 +63,7 @@ options:
value_type: bytes
default_value: "0"
description: Target amount of free disk space after pruning
details_url: '#min-free-space'
deprecated: false
hidden: false
experimental: false
@@ -87,6 +74,7 @@ options:
value_type: bytes
default_value: "0"
description: Amount of disk space always allowed to keep for cache
details_url: '#reserved-space'
deprecated: false
hidden: false
experimental: false
@@ -126,6 +114,87 @@ inherited_options:
kubernetes: false
swarm: false
examples: |-
### Include internal/frontend images (--all) {#all}
The `--all` flag to allow clearing internal helper images and frontend images
set using the `#syntax=` directive or the `BUILDKIT_SYNTAX` build argument.
### Provide filter values (--filter) {#filter}
You can finely control which cache records to delete using the `--filter` flag.
The filter format is in the form of `<key><op><value>`, known as selectors. All
selectors must match the target object for the filter to be true. We define the
operators `=` for equality, `!=` for not equal and `~=` for a regular
expression.
Valid filter keys are:
- `until` flag to keep records that have been used in the last duration time.
Value is a duration string, e.g. `24h` or `2h30m`, with allowable units of
`(h)ours`, `(m)inutes` and `(s)econds`.
- `id` flag to target a specific image ID.
- `parents` flag to target records that are parents of the
specified image ID. Multiple parent IDs are separated by a semicolon (`;`).
- `description` flag to target records whose description is the specified
substring.
- `inuse` flag to target records that are actively in use and therefore not
reclaimable.
- `mutable` flag to target records that are mutable.
- `immutable` flag to target records that are immutable.
- `shared` flag to target records that are shared with other resources,
typically images.
- `private` flag to target records that are not shared.
- `type` flag to target records by type. Valid types are:
- `internal`
- `frontend`
- `source.local`
- `source.git.checkout`
- `exec.cachemount`
- `regular`
Examples:
```console
docker buildx prune --filter "until=24h"
docker buildx prune --filter "description~=golang"
docker buildx prune --filter "parents=dpetmoi6n0yqanxjqrbnofz9n;kgoj0q6g57i35gdyrv546alz7"
docker buildx prune --filter "type=source.local"
docker buildx prune --filter "type!=exec.cachemount"
```
> [!NOTE]
> Multiple `--filter` flags are ANDed together.
### Maximum amount of disk space allowed to keep for cache (--max-used-space) {#max-used-space}
The `--max-used-space` flag allows setting a maximum amount of disk space
that the build cache can use. If the cache is using more disk space than this
value, the least recently used cache records are deleted until the total
used space is less than or equal to the specified value.
The value is specified in bytes. You can use a human-readable memory string,
e.g. `128mb`, `2gb`, etc. Units are case-insensitive.
### Target amount of free disk space after pruning (--min-free-space) {#min-free-space}
The `--min-free-space` flag allows setting a target amount of free disk space
that should be available after pruning. If the available disk space is less
than this value, the least recently used cache records are deleted until
the available free space is greater than or equal to the specified value.
The value is specified in bytes. You can use a human-readable memory string,
e.g. `128mb`, `2gb`, etc. Units are case-insensitive.
### Amount of disk space always allowed to keep for cache (--reserved-space) {#reserved-space}
The `--reserved-space` flag allows setting an amount of disk space that
should always be kept for the build cache. If the available disk space is less
than this value, the least recently used cache records are deleted until
the available free space is greater than or equal to the specified value.
The value is specified in bytes. You can use a human-readable memory string,
e.g. `128mb`, `2gb`, etc. Units are case-insensitive.
### Override the configured builder instance (--builder) {#builder}
Same as [`buildx --builder`](/reference/cli/docker/buildx/#builder).

6
go.mod
View File

@@ -15,7 +15,7 @@ require (
github.com/containerd/stargz-snapshotter/estargz v0.16.3 // indirect
github.com/containerd/typeurl/v2 v2.2.3 // indirect
github.com/distribution/reference v0.6.0 // indirect
github.com/docker/buildx v0.27.0 // indirect
github.com/docker/buildx v0.28.0 // indirect
github.com/docker/cli v28.3.3+incompatible // indirect
github.com/docker/compose/v2 v2.39.2 // indirect
github.com/docker/distribution v2.8.3+incompatible // indirect
@@ -53,7 +53,7 @@ require (
github.com/mattn/go-runewidth v0.0.16 // indirect
github.com/mattn/go-shellwords v1.0.12 // indirect
github.com/mitchellh/go-homedir v1.1.0 // indirect
github.com/moby/buildkit v0.23.2 // indirect
github.com/moby/buildkit v0.24.0 // indirect
github.com/moby/docker-image-spec v1.3.1 // indirect
github.com/moby/locker v1.0.1 // indirect
github.com/moby/moby v28.3.3+incompatible // indirect
@@ -109,7 +109,7 @@ require (
)
replace (
github.com/docker/buildx => github.com/docker/buildx v0.27.0
github.com/docker/buildx => github.com/docker/buildx v0.28.0
github.com/docker/cli => github.com/docker/cli v28.3.3+incompatible
github.com/docker/compose/v2 => github.com/docker/compose/v2 v2.39.2
github.com/docker/model-cli => github.com/docker/model-cli v0.1.39

2
go.sum
View File

@@ -40,6 +40,8 @@ github.com/docker/buildx v0.26.1 h1:nlj3bVhHK9fV7g6floRvGhPcR0u2hxCPMmObCS1ZKL4=
github.com/docker/buildx v0.26.1/go.mod h1:oxMC30cSHPaCCkY2j+EqN7uxFikjSzVC0c44lo9b4Fo=
github.com/docker/buildx v0.27.0 h1:8QQOqIAMpDItzlmYO5ua/AR2Qttu07hHeOeOxPSbUR8=
github.com/docker/buildx v0.27.0/go.mod h1:omZ9N6owYkRoAN79fq+Dfa0RwfR3iblCGuUyThovCpM=
github.com/docker/buildx v0.28.0 h1:ZnrVsZ/qQwSOQ4Fx3IgXjiurAwvocaF1YUaPbIXD89E=
github.com/docker/buildx v0.28.0/go.mod h1:nLwx58w7xrQbLVSXiWiHpkVhY4ou4ci/hYomc139Vjk=
github.com/docker/cli v28.2.1+incompatible h1:AYyTcuwvhl9dXdyCiXlOGXiIqSNYzTmaDNpxIISPGsM=
github.com/docker/cli v28.2.1+incompatible/go.mod h1:JLrzqnKDaYBop7H2jaqPtU4hHvMKP+vjCwu2uszcLI8=
github.com/docker/cli v28.3.0+incompatible h1:s+ttruVLhB5ayeuf2BciwDVxYdKi+RoUlxmwNHV3Vfo=