@ -58,78 +58,135 @@ here we’
## Examples
## Examples
### < a name = " builder"> < / a > Override the configured builder instance (--builder )
### < a name = " allow"> < / a > Allow extra privileged entitlement (--allow )
Same as [`buildx --builder` ](buildx.md#builder ).
```
--allow=ENTITLEMENT
```
### < a name = "platform" > < / a > Set the target platforms for the build (--platform)
Allow extra privileged entitlement. List of entitlements:
```
- `network.host` - Allows executions with host networking.
--platform=value[,value]
- `security.insecure` - Allows executions without sandbox. See
[related Dockerfile extensions ](https://github.com/moby/buildkit/blob/master/frontend/dockerfile/docs/experimental.md#run---securityinsecuresandbox ).
For entitlements to be enabled, the `buildkitd` daemon also needs to allow them
with `--allow-insecure-entitlement` (see [`create --buildkitd-flags` ](buildx_create.md#buildkitd-flags ))
**Examples**
```console
$ docker buildx create --use --name insecure-builder --buildkitd-flags '--allow-insecure-entitlement security.insecure'
$ docker buildx build --allow security.insecure .
```
```
Set the target platform for the build. All `FROM` commands inside the Dockerfile
### < a name = "build-context" > < / a > Additional build contexts (--build-context)
without their own `--platform` flag will pull base images for this platform and
this value will also be the platform of the resulting image. The default value
will be the current platform of the buildkit daemon.
When using `docker-container` driver with `buildx` , this flag can accept multiple
```
values as an input separated by a comma. With multiple values the result will be
--build-context=name=VALUE
built for all of the specified platforms and joined together into a single manifest
```
list.
If the `Dockerfile` needs to invoke the `RUN` command, the builder needs runtime
Define additional build context with specified contents. In Dockerfile the context can be accessed when `FROM name` or `--from=name` is used.
support for the specified platform. In a clean setup, you can only execute `RUN`
When Dockerfile defines a stage with the same name it is overwritten.
commands for your system architecture.
If your kernel supports [`binfmt_misc` ](https://en.wikipedia.org/wiki/Binfmt_misc )
launchers for secondary architectures, buildx will pick them up automatically.
Docker desktop releases come with `binfmt_misc` automatically configured for `arm64`
and `arm` architectures. You can see what runtime platforms your current builder
instance supports by running `docker buildx inspect --bootstrap` .
Inside a `Dockerfile` , you can access the current platform value through
The value can be a local source directory, container image (with docker-image:// prefix), Git or HTTP URL.
`TARGETPLATFORM` build argument. Please refer to the [`docker build`
documentation](https://docs.docker.com/engine/reference/builder/#automatic-platform-args-in-the-global-scope)
for the full description of automatic platform argument variants .
The formatting for the platform specifier is defined in the [containerd source
Replace `alpine:latest` with a pinned one:
code](https://github.com/containerd/containerd/blob/v1.4.3/platforms/platforms.go#L63).
**Examples**
```console
$ docker buildx build --build-context alpine=docker-image://alpine@sha256:0123456789 .
```
Expose a secondary local source directory:
```console
```console
$ docker buildx build --platform=linux/arm64 .
$ docker buildx build --build-context project=path/to/project/source .
$ docker buildx build --platform=linux/amd64,linux/arm64,linux/arm/v7 .
# docker buildx build --build-context project=https://github.com/myuser/project.git .
$ docker buildx build --platform=darwin .
```
```
### < a name = "progress" > < / a > Set type of progress output (--progress)
```Dockerfile
FROM alpine
COPY --from=project myfile /
```
### < a name = "builder" > < / a > Override the configured builder instance (--builder)
Same as [`buildx --builder` ](buildx.md#builder ).
### < a name = "cache-from" > < / a > Use an external cache source for a build (--cache-from)
```
```
--progress=VALUE
--cache-from=[NAME|type=TYPE[,KEY=VALUE]]
```
```
Set type of progress output (auto, plain, tty). Use plain to show container
Use an external cache source for a build. Supported types are `registry` ,
output (default "auto").
`local` and `gha`
> You can also use the `BUILDKIT_PROGRESS` environment variable to set
- [`registry` source ](https://github.com/moby/buildkit#registry-push-image-and-cache-separately )
> its value.
can import cache from a cache manifest or (special) image configuration on the
registry.
- [`local` source ](https://github.com/moby/buildkit#local-directory-1 ) can
import cache from local files previously exported with `--cache-to` .
- [`gha` source ](https://github.com/moby/buildkit#github-actions-cache-experimental )
can import cache from a previously exported cache with `--cache-to` in your
GitHub repository
The following example uses `plain` output during the build:
If no type is specified, `registry` exporter is used with a specified reference.
`docker` driver currently only supports importing build cache from the registry.
```console
```console
$ docker buildx build --load --progress=plain .
$ docker buildx build --cache-from=user/app:cache .
$ docker buildx build --cache-from=user/app .
$ docker buildx build --cache-from=type=registry,ref=user/app .
$ docker buildx build --cache-from=type=local,src=path/to/cache .
$ docker buildx build --cache-from=type=gha .
```
#1 [internal] load build definition from DockerfileMore info about cache exporters and available attributes: https://github.com/moby/buildkit#export-cache
#1 transferring dockerfile: 227B 0.0s done
#1 DONE 0.1s
#2 [internal] load .dockerignore### < a name = "cache-to" > < / a > Export build cache to an external cache destination (--cache-to)
#2 transferring context: 129B 0.0s done
#2 DONE 0.0s```
...
--cache-to=[NAME|type=TYPE[,KEY=VALUE]]
```
Export build cache to an external cache destination. Supported types are
`registry` , `local` , `inline` and `gha` .
- [`registry` type ](https://github.com/moby/buildkit#registry-push-image-and-cache-separately ) exports build cache to a cache manifest in the registry.
- [`local` type ](https://github.com/moby/buildkit#local-directory-1 ) type
exports cache to a local directory on the client.
- [`inline` type ](https://github.com/moby/buildkit#inline-push-image-and-cache-together )
type writes the cache metadata into the image configuration.
- [`gha` type ](https://github.com/moby/buildkit#github-actions-cache-experimental )
type exports cache through the [Github Actions Cache service API ](https://github.com/tonistiigi/go-actions-cache/blob/master/api.md#authentication ).
`docker` driver currently only supports exporting inline cache metadata to image
configuration. Alternatively, `--build-arg BUILDKIT_INLINE_CACHE=1` can be used
to trigger inline cache exporter.
Attribute key:
- `mode` - Specifies how many layers are exported with the cache. `min` on only
exports layers already in the final build stage, `max` exports layers for
all stages. Metadata is always exported for the whole build.
```console
$ docker buildx build --cache-to=user/app:cache .
$ docker buildx build --cache-to=type=inline .
$ docker buildx build --cache-to=type=registry,ref=user/app .
$ docker buildx build --cache-to=type=local,dest=path/to/cache .
$ docker buildx build --cache-to=type=gha .
```
```
More info about cache exporters and available attributes: https://github.com/moby/buildkit#export-cache
### < a name = "load" ></ a > Load the single-platform build result to `docker images` (--load)
Shorthand for [`--output=type=docker` ](#docker ). Will automatically load the
single-platform build result to `docker images` .
### < a name = "output" > < / a > Set the export action for the build result (-o, --output)
### < a name = "output" > < / a > Set the export action for the build result (-o, --output)
```
```
@ -148,8 +205,6 @@ If just the path is specified as a value, `buildx` will use the local exporter
with this path as the destination. If the value is "-", `buildx` will use `tar`
with this path as the destination. If the value is "-", `buildx` will use `tar`
exporter and write to `stdout` .
exporter and write to `stdout` .
**Examples**
```console
```console
$ docker buildx build -o . .
$ docker buildx build -o . .
$ docker buildx build -o outdir .
$ docker buildx build -o outdir .
@ -203,7 +258,7 @@ The most common usecase for multi-platform images is to directly push to a regis
Attribute keys:
Attribute keys:
- `dest` - destination path where tarball will be written. If not specified the
- `dest` - destination path where tarball will be written. If not specified the
tar will be loaded automatically to the current docker instance.
tar will be loaded automatically to the current docker instance.
- `context` - name for the docker context where to import the result
- `context` - name for the docker context where to import the result
#### `image`
#### `image`
@ -221,146 +276,78 @@ Attribute keys:
The `registry` exporter is a shortcut for `type=image,push=true` .
The `registry` exporter is a shortcut for `type=image,push=true` .
### < a name = "platform" > < / a > Set the target platforms for the build (--platform)
### < a name = "push" > < / a > Push the build result to a registry (--push)
Shorthand for [`--output=type=registry` ](#registry ). Will automatically push the
build result to registry.
### < a name = "load" ></ a > Load the single-platform build result to `docker images` (--load)
Shorthand for [`--output=type=docker` ](#docker ). Will automatically load the
single-platform build result to `docker images` .
### < a name = "cache-from" > < / a > Use an external cache source for a build (--cache-from)
```
--cache-from=[NAME|type=TYPE[,KEY=VALUE]]
```
Use an external cache source for a build. Supported types are `registry` ,
`local` and `gha` .
- [`registry` source ](https://github.com/moby/buildkit#registry-push-image-and-cache-separately )
can import cache from a cache manifest or (special) image configuration on the
registry.
- [`local` source ](https://github.com/moby/buildkit#local-directory-1 ) can
import cache from local files previously exported with `--cache-to` .
- [`gha` source ](https://github.com/moby/buildkit#github-actions-cache-experimental )
can import cache from a previously exported cache with `--cache-to` in your
GitHub repository
If no type is specified, `registry` exporter is used with a specified reference.
`docker` driver currently only supports importing build cache from the registry.
**Examples**
```console
$ docker buildx build --cache-from=user/app:cache .
$ docker buildx build --cache-from=user/app .
$ docker buildx build --cache-from=type=registry,ref=user/app .
$ docker buildx build --cache-from=type=local,src=path/to/cache .
$ docker buildx build --cache-from=type=gha .
```
More info about cache exporters and available attributes: https://github.com/moby/buildkit#export-cache
### < a name = "cache-to" > < / a > Export build cache to an external cache destination (--cache-to)
```
```
--cache-to=[NAME|type=TYPE[,KEY=VALUE] ]
--platform=value[,value]
```
```
Export build cache to an external cache destination. Supported types are
Set the target platform for the build. All `FROM` commands inside the Dockerfile
`registry` , `local` , `inline` and `gha` .without their own `--platform` flag will pull base images for this platform and
this value will also be the platform of the resulting image. The default value
- [`registry` type ](https://github.com/moby/buildkit#registry-push-image-and-cache-separately ) exports build cache to a cache manifest in the registry.
will be the current platform of the buildkit daemon.
- [`local` type ](https://github.com/moby/buildkit#local-directory-1 ) type
exports cache to a local directory on the client.
- [`inline` type ](https://github.com/moby/buildkit#inline-push-image-and-cache-together )
type writes the cache metadata into the image configuration.
- [`gha` type ](https://github.com/moby/buildkit#github-actions-cache-experimental )
type exports cache through the [Github Actions Cache service API ](https://github.com/tonistiigi/go-actions-cache/blob/master/api.md#authentication ).
`docker` driver currently only supports exporting inline cache metadata to imageWhen using `docker-container` driver with `buildx` , this flag can accept multiple
configuration. Alternatively, `--build-arg BUILDKIT_INLINE_CACHE=1` can be used
values as an input separated by a comma. With multiple values the result will be
to trigger inline cache exporter.
built for all of the specified platforms and joined together into a single manifest
list.
Attribute key:
If the `Dockerfile` needs to invoke the `RUN` command, the builder needs runtime
support for the specified platform. In a clean setup, you can only execute `RUN`
commands for your system architecture.
If your kernel supports [`binfmt_misc` ](https://en.wikipedia.org/wiki/Binfmt_misc )
launchers for secondary architectures, buildx will pick them up automatically.
Docker desktop releases come with `binfmt_misc` automatically configured for `arm64`
and `arm` architectures. You can see what runtime platforms your current builder
instance supports by running `docker buildx inspect --bootstrap` .
- `mode` - Specifies how many layers are exported with the cache. `min` on only
Inside a `Dockerfile` , you can access the current platform value through
exports layers already in the final build stage, `max` exports layers for
`TARGETPLATFORM` build argument. Please refer to the [`docker build`
all stages. Metadata is always exported for the whole build.
documentation](https://docs.docker.com/engine/reference/builder/#automatic-platform-args-in-the-global-scope)
for the full description of automatic platform argument variants .
**Examples**
The formatting for the platform specifier is defined in the [containerd source
code](https://github.com/containerd/containerd/blob/v1.4.3/platforms/platforms.go#L63).
```console
```console
$ docker buildx build --cache-to=user/app:cache .
$ docker buildx build --platform=linux/arm64 .
$ docker buildx build --cache-to=type=inline .
$ docker buildx build --platform=linux/amd64,linux/arm64,linux/arm/v7 .
$ docker buildx build --cache-to=type=registry,ref=user/app .
$ docker buildx build --platform=darwin .
$ docker buildx build --cache-to=type=local,dest=path/to/cache .
$ docker buildx build --cache-to=type=gha .
```
```
More info about cache exporters and available attributes: https://github.com/moby/buildkit#export-cache
### < a name = "progress" > < / a > Set type of progress output (--progress)
### < a name = "build-context" > < / a > Additional build contexts (--build-context)
```
```
--build-context=name =VALUE
--progress=VALUE
```
```
Define additional build context with specified contents. In Dockerfile the context can be accessed when `FROM name` or `--from=name` is used.
Set type of progress output (auto, plain, tty). Use plain to show container
When Dockerfile defines a stage with the same name it is overwritten.
output (default "auto").
The value can be a local source directory, container image (with docker-image:// prefix), Git or HTTP URL.
**Examples**
Replace `alpine:latest` with a pinned one:
```console
> You can also use the `BUILDKIT_PROGRESS` environment variable to set
$ docker buildx build --build-context alpine=docker-image://alpine@sha256:0123456789 .
> its value.
```
Expose a secondary local source directory :The following example uses `plain` output during the build:
```console
```console
$ docker buildx build --build-context project=path/to/project/source .
$ docker buildx build --load --progress=plain .
# docker buildx build --build-context project=https://github.com/myuser/project.git .
```
```Dockerfile
FROM alpine
COPY --from=project myfile /
```
### < a name = "allow" > < / a > Allow extra privileged entitlement (--allow)
#1 [internal] load build definition from Dockerfile
#1 transferring dockerfile: 227B 0.0s done
#1 DONE 0.1s
```
#2 [internal] load .dockerignore
--allow=ENTITLEMENT
#2 transferring context: 129B 0.0s done
#2 DONE 0.0s
...
```
```
Allow extra privileged entitlement. List of entitlements:
### < a name = "push" > < / a > Push the build result to a registry (--push)
- `network.host` - Allows executions with host networking.
- `security.insecure` - Allows executions without sandbox. See
[related Dockerfile extensions ](https://github.com/moby/buildkit/blob/master/frontend/dockerfile/docs/experimental.md#run---securityinsecuresandbox ).
For entitlements to be enabled, the `buildkitd` daemon also needs to allow them
with `--allow-insecure-entitlement` (see [`create --buildkitd-flags` ](buildx_create.md#buildkitd-flags ))
**Examples**
```console
Shorthand for [`--output=type=registry` ](#registry ). Will automatically push the
$ docker buildx create --use --name insecure-builder --buildkitd-flags '--allow-insecure-entitlement security.insecure'
build result to registry.
$ docker buildx build --allow security.insecure .
```
### < a name = "secret" > < / a > Secret to expose to the build (` --secret` )
### < a name = "secret" > < / a > Secret to expose to the build (--secret)
```
```
--secret=[type=TYPE[,KEY=VALUE]
--secret=[type=TYPE[,KEY=VALUE]
@ -386,8 +373,8 @@ RUN --mount=type=secret,id=aws,target=/root/.aws/credentials \
aws s3 cp s3://... ...
aws s3 cp s3://... ...
```
```
```shell
```console
docker buildx build --secret id=aws,src=$HOME/.aws/credentials .
$ docker buildx build --secret id=aws,src=$HOME/.aws/credentials .
```
```
#### `env`
#### `env`
@ -405,11 +392,11 @@ RUN --mount=type=bind,target=. \
SECRET_TOKEN=$(cat /run/secrets/SECRET_TOKEN) yarn run test
SECRET_TOKEN=$(cat /run/secrets/SECRET_TOKEN) yarn run test
```
```
```shell
```console
SECRET_TOKEN=token docker buildx build --secret id=SECRET_TOKEN .
$ SECRET_TOKEN=token docker buildx build --secret id=SECRET_TOKEN .
```
```
### < a name = "shm-size" a > Size of ` ` (--shm-size)
### < a name = "shm-size" a > Size of /dev/shm (--shm-size)
The format is `<number><unit>` . `number` must be greater than `0` . Unit is
The format is `<number><unit>` . `number` must be greater than `0` . Unit is
optional and can be `b` (bytes), `k` (kilobytes), `m` (megabytes), or `g`
optional and can be `b` (bytes), `k` (kilobytes), `m` (megabytes), or `g`
CrazyMax
3 years ago