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

Merge pull request #21300 from dvdksn/bk0.17-bx0.18 

build: buildx v0.18.0, buildkit v0.17.0, dockerfile v1.11.0
This commit is contained in:
David Karlsson 2024-10-31 13:11:51 +01:00 committed by GitHub
parent 5cd626cf5d 8201899a00
commit 29d100f92c
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
20 changed files with 441 additions and 97 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
Dockerfile
View File

@ -84,8 +84,8 @@ RUN hugo mod vendor
# vendor is an empty stage with only vendored Hugo modules
FROM scratch AS vendor
COPY --from=update-modules /src/_vendor /_vendor
COPY --from=update-modules /src/go.* /
COPY --from=update-modules /project/_vendor /_vendor
COPY --from=update-modules /project/go.* /
# build-upstream builds an upstream project with a replacement module
FROM build-base AS build-upstream

2
_vendor/github.com/docker/buildx/docs/bake-reference.md generated
View File

@ -844,7 +844,7 @@ The following example forces the builder to always pull all images referenced in
```hcl
target "default" {
pull = "always"
pull = true
}
```

4
_vendor/github.com/moby/buildkit/docs/attestations/attestation-storage.md generated
View File

@ -1,4 +1,6 @@
# Image Attestation Storage
---
title: Image attestation storage
---
Buildkit supports creating and attaching attestations to build artifacts. These
attestations can provide valuable information from the build process,

4
_vendor/github.com/moby/buildkit/docs/attestations/slsa-definitions.md generated
View File

@ -1,4 +1,6 @@
# SLSA definitions
---
title: SLSA definitions
---
BuildKit supports the [creation of SLSA Provenance](./slsa-provenance.md) for builds that
it runs.

65
_vendor/github.com/moby/buildkit/docs/buildkitd.toml.md generated
View File

@ -62,11 +62,25 @@ insecure-entitlements = [ "network.host", "security.insecure" ]
# Whether run subprocesses in main pid namespace or not, this is useful for
# running rootless buildkit inside a container.
noProcessSandbox = false
# gc enables/disables garbage collection
gc = true
# gckeepstorage can be an integer number of bytes (e.g. 512000000), a string
# with a unit (e.g. "512MB"), or a string percentage of the total disk
# space (e.g. "10%")
gckeepstorage = 9000
# reservedSpace is the minimum amount of disk space guaranteed to be
# retained by this buildkit worker - any usage below this threshold will not
# be reclaimed during garbage collection.
# all disk space parameters can be an integer number of bytes (e.g.
# 512000000), a string with a unit (e.g. "512MB"), or a string percentage
# of the total disk space (e.g. "10%")
reservedSpace = "30%"
# maxUsedSpace is the maximum amount of disk space that may be used by
# this buildkit worker - any usage above this threshold will be reclaimed
# during garbage collection.
maxUsedSpace = "60%"
# minFreeSpace is the target amount of free disk space that the garbage
# collector will attempt to leave - however, it will never be bought below
# reservedSpace.
minFreeSpace = "20GB"
# alternate OCI worker binary name(example 'crun'), by default either
# buildkit-runc or runc binary is used
binary = ""
@ -83,26 +97,51 @@ insecure-entitlements = [ "network.host", "security.insecure" ]
"foo" = "bar"
[[worker.oci.gcpolicy]]
# keepBytes can be an integer number of bytes (e.g. 512000000), a string
# with a unit (e.g. "512MB"), or a string percentage of the total disk
# space (e.g. "10%")
keepBytes = "512MB"
# reservedSpace is the minimum amount of disk space guaranteed to be
# retained by this policy - any usage below this threshold will not be
# reclaimed during # garbage collection.
reservedSpace = "512MB"
# maxUsedSpace is the maximum amount of disk space that may be used by this
# policy - any usage above this threshold will be reclaimed during garbage
# collection.
maxUsedSpace = "1GB"
# minFreeSpace is the target amount of free disk space that the garbage
# collector will attempt to leave - however, it will never be bought below
# reservedSpace.
minFreeSpace = "10GB"
# keepDuration can be an integer number of seconds (e.g. 172800), or a
# string duration (e.g. "48h")
keepDuration = "48h"
filters = [ "type==source.local", "type==exec.cachemount", "type==source.git.checkout"]
[[worker.oci.gcpolicy]]
all = true
keepBytes = 1024000000
reservedSpace = 1024000000
[worker.containerd]
address = "/run/containerd/containerd.sock"
enabled = true
platforms = [ "linux/amd64", "linux/arm64" ]
namespace = "buildkit"
# gc enables/disables garbage collection
gc = true
# gckeepstorage sets storage limit for default gc profile, in bytes.
gckeepstorage = 9000
# reservedSpace is the minimum amount of disk space guaranteed to be
# retained by this buildkit worker - any usage below this threshold will not
# be reclaimed during garbage collection.
# all disk space parameters can be an integer number of bytes (e.g.
# 512000000), a string with a unit (e.g. "512MB"), or a string percentage
# of the total disk space (e.g. "10%")
reservedSpace = "30%"
# maxUsedSpace is the maximum amount of disk space that may be used by
# this buildkit worker - any usage above this threshold will be reclaimed
# during garbage collection.
maxUsedSpace = "60%"
# minFreeSpace is the target amount of free disk space that the garbage
# collector will attempt to leave - however, it will never be bought below
# reservedSpace.
minFreeSpace = "20GB"
# maintain a pool of reusable CNI network namespaces to amortize the overhead
# of allocating and releasing the namespaces
cniPoolSize = 16
@ -119,12 +158,12 @@ insecure-entitlements = [ "network.host", "security.insecure" ]
options = { BinaryName = "runc" }
[[worker.containerd.gcpolicy]]
keepBytes = 512000000
reservedSpace = 512000000
keepDuration = 172800
filters = [ "type==source.local", "type==exec.cachemount", "type==source.git.checkout"]
[[worker.containerd.gcpolicy]]
all = true
keepBytes = 1024000000
reservedSpace = 1024000000
# registry configures a new Docker register used for cache import or output.
[registry."docker.io"]

110
_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/reference.md generated
View File

@ -47,8 +47,8 @@ be UPPERCASE to distinguish them from arguments more easily.
Docker runs instructions in a Dockerfile in order. A Dockerfile **must
begin with a `FROM` instruction**. This may be after [parser
directives](#parser-directives), [comments](#format), and globally scoped
[ARGs](#arg). The `FROM` instruction specifies the [parent
image](https://docs.docker.com/glossary/#parent-image) from which you are
[ARGs](#arg). The `FROM` instruction specifies the [base
image](https://docs.docker.com/glossary/#base-image) from which you are
building. `FROM` may only be preceded by one or more `ARG` instructions, which
declare arguments that are used in `FROM` lines in the Dockerfile.
@ -345,6 +345,11 @@ despite warnings. To make the build fail on warnings, set `#check=error=true`.
# check=error=true
```
> [!NOTE]
> When using the `check` directive, with `error=true` option, it is recommended
> to pin the [Dockerfile syntax](#syntax) to a specific version. Otherwise, your build may
> start to fail when new checks are added in the future versions.
To combine both the `skip` and `error` options, use a semi-colon to separate
them:
@ -723,7 +728,7 @@ This can be used to:
The supported mount types are:
| Type | Description |
| ---------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| [`bind`](#run---mounttypebind) (default) | Bind-mount context directories (read-only). |
| [`cache`](#run---mounttypecache) | Mount a temporary directory to cache directories for compilers and package managers. |
| [`tmpfs`](#run---mounttypetmpfs) | Mount a `tmpfs` in the build container. |
@ -736,7 +741,7 @@ This mount type allows binding files or directories to the build container. A
bind mount is read-only by default.
| Option | Description |
| ---------------- | ---------------------------------------------------------------------------------------------- |
| ---------------------------------- | ---------------------------------------------------------------------------------------------- |
| `target`, `dst`, `destination`[^1] | Mount path. |
| `source` | Source path in the `from`. Defaults to the root of the `from`. |
| `from` | Build stage, context, or image name for the root of the source. Defaults to the build context. |
@ -748,7 +753,7 @@ This mount type allows the build container to cache directories for compilers
and package managers.
| Option | Description |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | Optional ID to identify separate/different caches. Defaults to value of `target`. |
| `target`, `dst`, `destination`[^1] | Mount path. |
| `ro`,`readonly` | Read-only if set. |
@ -797,7 +802,7 @@ case.
This mount type allows mounting `tmpfs` in the build container.
| Option | Description |
| ------------ | ----------------------------------------------------- |
| ---------------------------------- | ----------------------------------------------------- |
| `target`, `dst`, `destination`[^1] | Mount path. |
| `size` | Specify an upper limit on the size of the filesystem. |
@ -842,7 +847,7 @@ environment variable with the same name.
# syntax=docker/dockerfile:1
FROM alpine
RUN --mount=type=secret,id=API_KEY,env=API_KEY \
some-command --token-from-env API_KEY
some-command --token-from-env $API_KEY
```
Assuming that the `API_KEY` environment variable is set in the build
@ -858,7 +863,7 @@ This mount type allows the build container to access SSH keys via SSH agents,
with support for passphrases.
| Option | Description |
| ---------- | ---------------------------------------------------------------------------------------------- |
| ------------------------------ | ---------------------------------------------------------------------------------------------- |
| `id` | ID of SSH agent socket or key. Defaults to "default". |
| `target`, `dst`, `destination` | SSH agent socket path. Defaults to `/run/buildkit/ssh_agent.${N}`. |
| `required` | If set to `true`, the instruction errors out when the key is unavailable. Defaults to `false`. |
@ -1012,7 +1017,7 @@ both the `CMD` and `ENTRYPOINT` instructions should be specified in the
## LABEL
```dockerfile
LABEL <key>=<value> <key>=<value> <key>=<value> ...
LABEL <key>=<value> [<key>=<value>...]
```
The `LABEL` instruction adds metadata to an image. A `LABEL` is a
@ -1047,9 +1052,9 @@ LABEL multi.label1="value1" \
> using string interpolation (e.g. `LABEL example="foo-$ENV_VAR"`), single
> quotes will take the string as is without unpacking the variable's value.
Labels included in base or parent images (images in the `FROM` line) are
inherited by your image. If a label already exists but with a different value,
the most-recently-applied value overrides any previously-set value.
Labels included in base images (images in the `FROM` line) are inherited by
your image. If a label already exists but with a different value, the
most-recently-applied value overrides any previously-set value.
To view an image's labels, use the `docker image inspect` command. You can use
the `--format` option to show just the labels;
@ -1139,7 +1144,7 @@ port. For detailed information, see the
## ENV
```dockerfile
ENV <key>=<value> ...
ENV <key>=<value> [<key>=<value>...]
```
The `ENV` instruction sets the environment variable `<key>` to the value
@ -1232,7 +1237,7 @@ The available `[OPTIONS]` are:
| [`--chown`](#add---chown---chmod) | |
| [`--chmod`](#add---chown---chmod) | 1.2 |
| [`--link`](#add---link) | 1.4 |
| [`--exclude`](#add---exclude) | 1.7 |
| [`--exclude`](#add---exclude) | 1.7-labs |
The `ADD` instruction copies new files or directories from `<src>` and adds
them to the filesystem of the image at the path `<dest>`. Files and directories
@ -1517,8 +1522,8 @@ The available `[OPTIONS]` are:
| [`--chown`](#copy---chown---chmod) | |
| [`--chmod`](#copy---chown---chmod) | 1.2 |
| [`--link`](#copy---link) | 1.4 |
| [`--parents`](#copy---parents) | 1.7 |
| [`--exclude`](#copy---exclude) | 1.7 |
| [`--parents`](#copy---parents) | 1.7-labs |
| [`--exclude`](#copy---exclude) | 1.7-labs |
The `COPY` instruction copies new files or directories from `<src>` and adds
them to the filesystem of the image at the path `<dest>`. Files and directories
@ -1815,7 +1820,7 @@ COPY [--parents[=<boolean>]] <src> ... <dest>
The `--parents` flag preserves parent directories for `src` entries. This flag defaults to `false`.
```dockerfile
# syntax=docker/dockerfile:1.7-labs
# syntax=docker/dockerfile:1-labs
FROM scratch
COPY ./x/a.txt ./y/a.txt /no_parents/
@ -1835,7 +1840,7 @@ directories after it will be preserved. This may be especially useful copies bet
with `--from` where the source paths need to be absolute.
```dockerfile
# syntax=docker/dockerfile:1.7-labs
# syntax=docker/dockerfile:1-labs
FROM scratch
COPY --parents ./x/./y/*.txt /parents/
@ -1877,6 +1882,9 @@ supporting wildcards and matching using Go's
For example, to add all files starting with "hom", excluding files with a `.txt` extension:
```dockerfile
# syntax=docker/dockerfile:1-labs
FROM scratch
COPY --exclude=*.txt hom* /mydir/
```
@ -1886,6 +1894,9 @@ even if the files paths match the pattern specified in `<src>`.
To add all files starting with "hom", excluding files with either `.txt` or `.md` extensions:
```dockerfile
# syntax=docker/dockerfile:1-labs
FROM scratch
COPY --exclude=*.txt --exclude=*.md hom* /mydir/
```
@ -2305,7 +2316,7 @@ Therefore, to avoid unintended operations in unknown directories, it's best prac
## ARG
```dockerfile
ARG <name>[=<default value>]
ARG <name>[=<default value>] [<name>[=<default value>]...]
```
The `ARG` instruction defines a variable that users can pass at build-time to
@ -2349,9 +2360,8 @@ at build-time, the builder uses the default.
### Scope
An `ARG` variable definition comes into effect from the line on which it is
defined in the Dockerfile not from the argument's use on the command-line or
elsewhere. For example, consider this Dockerfile:
An `ARG` variable comes into effect from the line on which it is declared in
the Dockerfile. For example, consider this Dockerfile:
```dockerfile
FROM busybox
@ -2367,24 +2377,22 @@ A user builds this file by calling:
$ docker build --build-arg username=what_user .
```
The `USER` at line 2 evaluates to `some_user` as the `username` variable is defined on the
subsequent line 3. The `USER` at line 4 evaluates to `what_user`, as the `username` argument is
defined and the `what_user` value was passed on the command line. Prior to its definition by an
`ARG` instruction, any use of a variable results in an empty string.
- The `USER` instruction on line 2 evaluates to the `some_user` fallback,
because the `username` variable is not yet declared.
- The `username` variable is declared on line 3, and available for reference in
Dockerfile instruction from that point onwards.
- The `USER` instruction on line 4 evaluates to `what_user`, since at that
point the `username` argument has a value of `what_user` which was passed on
the command line. Prior to its definition by an `ARG` instruction, any use of
a variable results in an empty string.
An `ARG` instruction goes out of scope at the end of the build
stage where it was defined. To use an argument in multiple stages, each stage must
include the `ARG` instruction.
An `ARG` variable declared within a build stage is automatically inherited by
other stages based on that stage. Unrelated build stages do not have access to
the variable. To use an argument in multiple distinct stages, each stage must
include the `ARG` instruction, or they must both be based on a shared base
stage in the same Dockerfile where the variable is declared.
```dockerfile
FROM busybox
ARG SETTINGS
RUN ./run/setup $SETTINGS
FROM busybox
ARG SETTINGS
RUN ./run/other $SETTINGS
```
For more information, refer to [variable scoping](https://docs.docker.com/build/building/variables/#scoping).
### Using ARG variables
@ -2622,8 +2630,6 @@ another build. The trigger will be executed in the context of the
downstream build, as if it had been inserted immediately after the
`FROM` instruction in the downstream Dockerfile.
Any build instruction can be registered as a trigger.
This is useful if you are building an image which will be used as a base
to build other images, for example an application build environment or a
daemon which may be customized with user-specific configuration.
@ -2666,11 +2672,26 @@ ONBUILD ADD . /app/src
ONBUILD RUN /usr/local/bin/python-build --dir /app/src
```
### Copy or mount from stage, image, or context
As of Dockerfile syntax 1.11, you can use `ONBUILD` with instructions that copy
or mount files from other stages, images, or build contexts. For example:
```dockerfile
# syntax=docker/dockerfile:1.11
FROM alpine AS baseimage
ONBUILD COPY --from=build /usr/bin/app /app
ONBUILD RUN --mount=from=config,target=/opt/appconfig ...
```
If the source of `from` is a build stage, the stage must be defined in the
Dockerfile where `ONBUILD` gets triggered. If it's a named context, that
context must be passed to the downstream build.
### ONBUILD limitations
- Chaining `ONBUILD` instructions using `ONBUILD ONBUILD` isn't allowed.
- The `ONBUILD` instruction may not trigger `FROM` or `MAINTAINER` instructions.
- `ONBUILD COPY --from` is [not supported](https://github.com/moby/buildkit/issues/816).
## STOPSIGNAL
@ -3002,10 +3023,9 @@ hello world
For examples of Dockerfiles, refer to:
- The ["build images" section](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/)
- The ["get started" tutorial](https://docs.docker.com/get-started/)
- The [language-specific getting started guides](https://docs.docker.com/language/)
- The [build guide](https://docs.docker.com/build/guide/)
- The [building best practices page](https://docs.docker.com/build/building/best-practices/)
- The ["get started" tutorials](https://docs.docker.com/get-started/)
- The [language-specific getting started guides](https://docs.docker.com/guides/language/)
[^1]: Value required
[^2]: For Docker-integrated [BuildKit](https://docs.docker.com/build/buildkit/#getting-started) and `docker buildx build`

4
_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/_index.md generated
View File

@ -103,5 +103,9 @@ To learn more about how to use build checks, see
<td><a href="./copy-ignored-file/">CopyIgnoredFile (experimental)</a></td>
<td>Attempting to Copy file that is excluded by .dockerignore</td>
</tr>
<tr>
<td><a href="./invalid-definition-description/">InvalidDefinitionDescription (experimental)</a></td>
<td>Comment for build stage or argument should follow the format: `# <arg/stage name> <description>`. If this is not intended to be a description comment, add an empty line or comment between the instruction and the comment.</td>
</tr>
</tbody>
</table>

70
_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/invalid-definition-description.md generated Normal file
View File

@ -0,0 +1,70 @@
---
title: InvalidDefinitionDescription
description: "Comment for build stage or argument should follow the format: `# <arg/stage name> <description>`. If this is not intended to be a description comment, add an empty line or comment between the instruction and the comment."
aliases:
- /go/dockerfile/rule/invalid-definition-description/
---
> [!NOTE]
> This check is experimental and is not enabled by default. To enable it, see
> [Experimental checks](https://docs.docker.com/go/build-checks-experimental/).
## Output
```text
Comment for build stage or argument should follow the format: `# <arg/stage name> <description>`. If this is not intended to be a description comment, add an empty line or comment between the instruction and the comment.
```
## Description
The [`--call=outline`](https://docs.docker.com/reference/cli/docker/buildx/build/#call-outline)
and [`--call=targets`](https://docs.docker.com/reference/cli/docker/buildx/build/#call-outline)
flags for the `docker build` command print descriptions for build targets and arguments.
The descriptions are generated from [Dockerfile comments](https://docs.docker.com/reference/cli/docker/buildx/build/#descriptions)
that immediately precede the `FROM` or `ARG` instruction
and that begin with the name of the build stage or argument.
For example:
```dockerfile
# build-cli builds the CLI binary
FROM alpine AS build-cli
# VERSION controls the version of the program
ARG VERSION=1
```
In cases where preceding comments are not meant to be descriptions,
add an empty line or comment between the instruction and the preceding comment.
## Examples
❌ Bad: A non-descriptive comment on the line preceding the `FROM` command.
```dockerfile
# a non-descriptive comment
FROM scratch AS base
# another non-descriptive comment
ARG VERSION=1
```
✅ Good: An empty line separating non-descriptive comments.
```dockerfile
# a non-descriptive comment
FROM scratch AS base
# another non-descriptive comment
ARG VERSION=1
```
✅ Good: Comments describing `ARG` keys and stages immediately proceeding the command.
```dockerfile
# base is a stage for compiling source
FROM scratch AS base
# VERSION This is the version number.
ARG VERSION=1
```

39
_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/json-args-recommended.md generated
View File

@ -50,10 +50,41 @@ Note that running programs as PID 1 means the program now has the special
responsibilities and behaviors associated with PID 1 in Linux, such as reaping
child processes.
Alternatively, if you want to ignore this lint rule because you do want your
executable to be invoked via a shell, you can use the
[`SHELL`](https://docs.docker.com/reference/dockerfile.md#shell) Dockerfile
instruction to explicitly specify a shell to use.
### Workarounds
There might still be cases when you want to run your containers under a shell.
When using exec form, shell features such as variable expansion, piping (`|`)
and command chaining (`&&`, `||`, `;`), are not available. To use such
features, you need to use shell form.
Here are some ways you can achieve that. Note that this still means that
executables run as child-processes of a shell.
#### Create a wrapper script
You can create an entrypoint script that wraps your startup commands, and
execute that script with a JSON-formatted `ENTRYPOINT` command.
✅ Good: the `ENTRYPOINT` uses JSON format.
```dockerfile
FROM alpine
RUN apk add bash
COPY --chmod=755 <<EOT /entrypoint.sh
#!/usr/bin/env bash
set -e
my-background-process &
my-program start
EOT
ENTRYPOINT ["/entrypoint.sh"]
```
#### Explicitly specify the shell
You can use the [`SHELL`](https://docs.docker.com/reference/dockerfile/#shell)
Dockerfile instruction to explicitly specify a shell to use. This will suppress
the warning since setting the `SHELL` instruction indicates that using shell
form is a conscious decision.
✅ Good: shell is explicitly defined.

35
_vendor/github.com/moby/buildkit/frontend/dockerfile/docs/rules/undefined-var.md generated
View File

@ -13,24 +13,25 @@ Usage of undefined variable '$foo'
## Description
Before you reference an environment variable or a build argument in a `RUN`
instruction, you should ensure that the variable is declared in the Dockerfile,
using the `ARG` or `ENV` instructions.
This check ensures that environment variables and build arguments are correctly
declared before being used. While undeclared variables might not cause an
immediate build failure, they can lead to unexpected behavior or errors later
in the build process.
Attempting to access an environment variable without explicitly declaring it
doesn't necessarily result in a build error, but it may yield an unexpected
result or an error later on in the build process.
This check does not evaluate undefined variables for `RUN`, `CMD`, and
`ENTRYPOINT` instructions where you use the [shell form](https://docs.docker.com/reference/dockerfile/#shell-form).
That's because when you use shell form, variables are resolved by the command
shell.
This check also attempts to detect if you're accessing a variable with a typo.
For example, given the following Dockerfile:
It also detects common mistakes like typos in variable names. For example, in
the following Dockerfile:
```dockerfile
FROM alpine
ENV PATH=$PAHT:/app/bin
```
The check detects that `$PAHT` is undefined, and that it's probably a
misspelling of `PATH`.
The check identifies that `$PAHT` is undefined and likely a typo for `$PATH`:
```text
Usage of undefined variable '$PAHT' (did you mean $PATH?)
@ -53,3 +54,17 @@ ARG foo
COPY $foo .
```
❌ Bad: `$foo` is undefined.
```dockerfile
FROM alpine AS base
ARG VERSION=$foo
```
✅ Good: the base image defines `$PYTHON_VERSION`
```dockerfile
FROM python AS base
ARG VERSION=$PYTHON_VERSION
```

4
_vendor/modules.txt
View File

@ -1,6 +1,6 @@
# github.com/moby/moby v27.3.1+incompatible
# github.com/moby/buildkit v0.16.0
# github.com/docker/buildx v0.17.1
# github.com/moby/buildkit v0.17.0
# github.com/docker/buildx v0.18.0
# github.com/docker/cli v27.3.2-0.20241008150905-cb3048fbebb1+incompatible
# github.com/docker/compose/v2 v2.30.1
# github.com/docker/scout-cli v1.13.0

32
content/manuals/build/buildkit/dockerfile-release-notes.md
View File

@ -13,6 +13,38 @@ issues, and bug fixes in [Dockerfile reference](/reference/dockerfile.md).
For usage, see the [Dockerfile frontend syntax](frontend.md) page.
## 1.11.0
{{< release-date date="2024-10-30" >}}
The full release note for this release is available
[on GitHub](https://github.com/moby/buildkit/releases/tag/dockerfile%2F1.11.0).
```dockerfile
# syntax=docker/dockerfile:1.11.0
```
- The [`ONBUILD` instruction](/reference/dockerfile.md#onbuild) now supports commands that refer to other stages or images with `from`, such as `COPY --from` or `RUN mount=from=...`. [moby/buildkit#5357]
- The [`SecretsUsedInArgOrEnv`](/reference/build-checks/secrets-used-in-arg-or-env.md) build check has been improved to reduce false positives. [moby/buildkit#5208]
- A new [`InvalidDefinitionDescription`](/reference/build-checks/invalid-definition-description.md) build check recommends formatting comments for build arguments and stages descriptions. This is an [experimental check](/manuals/build/checks.md#experimental-checks). [moby/buildkit#5208], [moby/buildkit#5414]
- Multiple fixes for the `ONBUILD` instruction's progress and error handling. [moby/buildkit#5397]
- Improved error reporting for missing flag errors. [moby/buildkit#5369]
- Enhanced progress output for secret values mounted as environment variables. [moby/buildkit#5336]
- Added built-in build argument `TARGETSTAGE` to expose the name of the (final) target stage for the current build. [moby/buildkit#5431]
### 1.11.0-labs
- `COPY --chmod` now supports non-octal values. [moby/buildkit#5380]
[moby/buildkit#5357]: https://github.com/moby/buildkit/pull/5357
[moby/buildkit#5208]: https://github.com/moby/buildkit/pull/5208
[moby/buildkit#5414]: https://github.com/moby/buildkit/pull/5414
[moby/buildkit#5397]: https://github.com/moby/buildkit/pull/5397
[moby/buildkit#5369]: https://github.com/moby/buildkit/pull/5369
[moby/buildkit#5336]: https://github.com/moby/buildkit/pull/5336
[moby/buildkit#5431]: https://github.com/moby/buildkit/pull/5431
[moby/buildkit#5380]: https://github.com/moby/buildkit/pull/5380
## 1.10.0
{{< release-date date="2024-09-10" >}}

30
content/manuals/build/release-notes.md
View File

@ -10,6 +10,36 @@ toc_max: 2
This page contains information about the new features, improvements, and bug
fixes in [Docker Buildx](https://github.com/docker/buildx).
## 0.18.0
### New
- The `docker buildx inspect` command now displays BuildKit daemon configuration options set with a TOML file. [docker/buildx#2684](https://github.com/docker/buildx/pull/2684)
- The `docker buildx ls` command output is now more compact by default by compacting the platform list. A new `--no-trunc` option can be used for the full list. [docker/buildx#2138](https://github.com/docker/buildx/pull/2138), [docker/buildx#2717](https://github.com/docker/buildx/pull/2717)
- The `docker buildx prune` command now supports new `--max-used-space` and `--min-free-space` filters with BuildKit v0.17.0+ builders. [docker/buildx#2766](https://github.com/docker/buildx/pull/2766)
### Enhancements
- Allow capturing of CPU and memory profiles with `pprof` using the [`BUILDX_CPU_PROFILE`](/manuals/build/building/variables.md#buildx_cpu_profile) and [`BUILDX_MEM_PROFILE`](/manuals/build/building/variables.md#buildx_mem_profile) environment variables. [docker/buildx#2746](https://github.com/docker/buildx/pull/2746)
- Maximum Dockerfile size from standard input has increased. [docker/buildx#2716](https://github.com/docker/buildx/pull/2716), [docker/buildx#2719](https://github.com/docker/buildx/pull/2719)
- Memory allocations have been reduced. [docker/buildx#2724](https://github.com/docker/buildx/pull/2724), [docker/buildx#2713](https://github.com/docker/buildx/pull/2713)
- The `--list-targets` and `--list-variables` flags for `docker buildx bake` no longer require initialization of the builder. [docker/buildx#2763](https://github.com/docker/buildx/pull/2763)
### Bug fixes
- Check warnings now print the full filepath to the offending Dockerfile, relative to the current working directory. [docker/buildx#2672](https://github.com/docker/buildx/pull/2672)
- Fallback images for the `--check` and `--call` options have been updated to correct references. [docker/buildx#2705](https://github.com/docker/buildx/pull/2705)
- Fix issue with the build details link not showing in experimental mode. [docker/buildx#2722](https://github.com/docker/buildx/pull/2722)
- Fix validation issue with invalid target linking for Bake. [docker/buildx#2700](https://github.com/docker/buildx/pull/2700)
- Fix missing error message when running an invalid command. [docker/buildx#2741](https://github.com/docker/buildx/pull/2741)
- Fix possible false warnings for local state in `--call` requests. [docker/buildx#2754](https://github.com/docker/buildx/pull/2754)
- Fix potential issues with entitlements when using linked targets in Bake. [docker/buildx#2701](https://github.com/docker/buildx/pull/2701)
- Fix possible permission issues when accessing local state after running Buildx with `sudo`. [docker/buildx#2745](https://github.com/docker/buildx/pull/2745)
### Packaging
- Compose compatibility has been updated to v2.4.1. [docker/buildx#2760](https://github.com/docker/buildx/pull/2760)
## 0.17.1
{{< release-date date="2024-09-13" >}}

1
data/buildx/docker_buildx.yaml
View File

@ -1,6 +1,7 @@
command: docker buildx
short: Docker Buildx
long: Extended build capabilities with BuildKit
usage: docker buildx
pname: docker
plink: docker.yaml
cname:

81
data/buildx/docker_buildx_build.yaml
View File

@ -1115,7 +1115,7 @@ examples: |-
```dockerfile
# syntax=docker/dockerfile:1
FROM oven/bun:1 as base
FROM oven/bun:1 AS base
WORKDIR /app
FROM base AS install
@ -1401,17 +1401,39 @@ examples: |-
Supported types are:
- [`file`](#file)
- [`env`](#env)
- [`type=file`](#typefile)
- [`type=env`](#typeenv)
Buildx attempts to detect the `type` automatically if unset.
Buildx attempts to detect the `type` automatically if unset. If an environment
variable with the same key as `id` is set, then Buildx uses `type=env` and the
variable value becomes the secret. If no such environment variable is set, and
`type` is not set, then Buildx falls back to `type=file`.
#### `file`
#### `type=file`
Attribute keys:
Source a build secret from a file.
- `id` - ID of the secret. Defaults to base name of the `src` path.
- `src`, `source` - Secret filename. `id` used if unset.
##### `type=file` synopsis
```console
$ docker buildx build --secret [type=file,]id=<ID>[,src=<FILEPATH>] .
```
##### `type=file` attributes
| Key | Description | Default |
| --------------- | ----------------------------------------------------------------------------------------------------- | -------------------------- |
| `id` | ID of the secret. | N/A (this key is required) |
| `src`, `source` | Filepath of the file containing the secret value (absolute or relative to current working directory). | `id` if unset. |
###### `type=file` usage
In the following example, `type=file` is automatically detected because no
environment variable mathing `aws` (the ID) is set.
```console
$ docker buildx build --secret id=aws,src=$HOME/.aws/credentials .
```
```dockerfile
# syntax=docker/dockerfile:1
@ -1421,16 +1443,31 @@ examples: |-
aws s3 cp s3://... ...
```
#### `type=env`
Source a build secret from an environment variable.
##### `type=env` synopsis
```console
$ docker buildx build --secret id=aws,src=$HOME/.aws/credentials .
$ docker buildx build --secret [type=env,]id=<ID>[,env=<VARIABLE>] .
```
#### `env`
##### `type=env` attributes
Attribute keys:
| Key | Description | Default |
| ---------------------- | ----------------------------------------------- | -------------------------- |
| `id` | ID of the secret. | N/A (this key is required) |
| `env`, `src`, `source` | Environment variable to source the secret from. | `id` if unset. |
- `id` - ID of the secret. Defaults to `env` name.
- `env` - Secret environment variable. `id` used if unset, otherwise will look for `src`, `source` if `id` unset.
##### `type=env` usage
In the following example, `type=env` is automatically detected because an
environment variable matching `id` is set.
```console
$ SECRET_TOKEN=token docker buildx build --secret id=SECRET_TOKEN .
```
```dockerfile
# syntax=docker/dockerfile:1
@ -1440,10 +1477,26 @@ examples: |-
yarn run test
```
In the following example, the build argument `SECRET_TOKEN` is set to contain
the value of the environment variable `API_KEY`.
```console
$ SECRET_TOKEN=token docker buildx build --secret id=SECRET_TOKEN .
$ API_KEY=token docker buildx build --secret id=SECRET_TOKEN,env=API_KEY .
```
You can also specify the name of the environment variable with `src` or `source`:
```console
$ API_KEY=token docker buildx build --secret type=env,id=SECRET_TOKEN,src=API_KEY .
```
> [!NOTE]
> Specifying the environment variable name with `src` or `source`, you are
> required to set `type=env` explicitly, or else Buildx assumes that the secret
> is `type=file`, and looks for a file with the name of `src` or `source` (in
> this case, a file named `API_KEY` relative to the location where the `docker
> buildx build` command was executed.
### Shared memory size for build containers (--shm-size) {#shm-size}
Sets the size of the shared memory allocated for build containers when using

1
data/buildx/docker_buildx_imagetools.yaml
View File

@ -4,6 +4,7 @@ long: |-
The `imagetools` commands contains subcommands for working with manifest lists
in container registries. These commands are useful for inspecting manifests
to check multi-platform configuration and attestations.
usage: docker buildx imagetools
pname: docker buildx
plink: docker_buildx.yaml
cname:

10
data/buildx/docker_buildx_ls.yaml
View File

@ -39,6 +39,16 @@ options:
experimentalcli: false
kubernetes: false
swarm: false
- option: no-trunc
value_type: bool
default_value: "false"
description: Don't truncate output
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
inherited_options:
- option: debug
shorthand: D

30
data/buildx/docker_buildx_prune.yaml
View File

@ -57,6 +57,36 @@ options:
value_type: bytes
default_value: "0"
description: Amount of disk space to keep for cache
deprecated: true
hidden: true
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: max-used-space
value_type: bytes
default_value: "0"
description: Maximum amount of disk space allowed to keep for cache
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: min-free-space
value_type: bytes
default_value: "0"
description: Target amount of free disk space after pruning
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: reserved-space
value_type: bytes
default_value: "0"
description: Amount of disk space always allowed to keep for cache
deprecated: false
hidden: false
experimental: false

8
go.mod
View File

@ -3,19 +3,19 @@ module github.com/docker/docs
go 1.23.1
require (
github.com/docker/buildx v0.17.1 // indirect
github.com/docker/buildx v0.18.0 // indirect
github.com/docker/cli v27.3.2-0.20241008150905-cb3048fbebb1+incompatible // indirect
github.com/docker/compose/v2 v2.30.1 // indirect
github.com/docker/scout-cli v1.13.0 // indirect
github.com/moby/buildkit v0.16.0 // indirect
github.com/moby/buildkit v0.17.0 // indirect
github.com/moby/moby v27.3.1+incompatible // indirect
)
replace (
github.com/docker/buildx => github.com/docker/buildx v0.17.1
github.com/docker/buildx => github.com/docker/buildx v0.18.0
github.com/docker/cli => github.com/docker/cli v27.3.1+incompatible
github.com/docker/compose/v2 => github.com/docker/compose/v2 v2.30.1
github.com/docker/scout-cli => github.com/docker/scout-cli v1.13.0
github.com/moby/buildkit => github.com/moby/buildkit v0.16.0
github.com/moby/buildkit => github.com/moby/buildkit v0.17.0
github.com/moby/moby => github.com/moby/moby v27.3.1+incompatible
)

4
go.sum
View File

@ -82,6 +82,8 @@ github.com/docker/buildx v0.17.0 h1:Z+QQxsJJPldaeU/4aNXoudFwDDK0/ALFYmDcP5q5fiY=
github.com/docker/buildx v0.17.0/go.mod h1:sBKkoZFs+R2D6ARyQ4/GE/FQHHFsl9PkHdvv/GXAsMo=
github.com/docker/buildx v0.17.1 h1:9ob2jGp4+W9PxWw68GsoNFp+eYFc7eUoRL9VljLCSM4=
github.com/docker/buildx v0.17.1/go.mod h1:kJOhOhS47LRvrLFRulFiO5SE6VJf54yYMn7DzjgO5W0=
github.com/docker/buildx v0.18.0 h1:rSauXHeJt90NvtXrLK5J992Eb0UPJZs2vV3u1zTf1nE=
github.com/docker/buildx v0.18.0/go.mod h1:JGNSshOhHs5FhG3u51jXUf4lLOeD2QBIlJ2vaRB67p4=
github.com/docker/cli v24.0.2+incompatible h1:QdqR7znue1mtkXIJ+ruQMGQhpw2JzMJLRXp6zpzF6tM=
github.com/docker/cli v24.0.2+incompatible/go.mod h1:JLrzqnKDaYBop7H2jaqPtU4hHvMKP+vjCwu2uszcLI8=
github.com/docker/cli v24.0.4+incompatible h1:Y3bYF9ekNTm2VFz5U/0BlMdJy73D+Y1iAAZ8l63Ydzw=
@ -300,6 +302,8 @@ github.com/moby/buildkit v0.15.1 h1:J6wrew7hphKqlq1wuu6yaUb/1Ra7gEzDAovylGztAKM=
github.com/moby/buildkit v0.15.1/go.mod h1:Yis8ZMUJTHX9XhH9zVyK2igqSHV3sxi3UN0uztZocZk=
github.com/moby/buildkit v0.16.0 h1:wOVBj1o5YNVad/txPQNXUXdelm7Hs/i0PUFjzbK0VKE=
github.com/moby/buildkit v0.16.0/go.mod h1:Xqx/5GlrqE1yIRORk0NSCVDFpQAU1WjlT6KHYZdisIQ=
github.com/moby/buildkit v0.17.0 h1:ZA/4AxwBbve1f3ZaNNJQiCBtTV62R6YweWNwq4A+sTc=
github.com/moby/buildkit v0.17.0/go.mod h1:ru8NFyDHD8HbuKaLXJIjK9nr3x6FZR+IWjtF07S+wdM=
github.com/moby/locker v1.0.1/go.mod h1:S7SDdo5zpBK84bzzVlKr2V0hz+7x9hWbYC/kq7oQppc=
github.com/moby/moby v24.0.2+incompatible h1:yH+5dRHH1x3XRKzl1THA2aGTy6CHYnkt5N924ADMax8=
github.com/moby/moby v24.0.2+incompatible/go.mod h1:fDXVQ6+S340veQPv35CzDahGBmHsiclFwfEygB/TWMc=