docker buildx build

読む時間の目安: 17 分

説明

ビルドを開始します。

利用方法

$ docker buildx build [オプション] PATH | URL | -

追加説明

The buildx build command starts a build using BuildKit. This command is similar to the UI of docker build command and takes the same flags and arguments.

For documentation on most of these flags, refer to the docker build documentation. In here we’ll document a subset of the new flags.

本コマンドの利用例については、以下に示す 利用例の節 を参照してください。

オプション

名前/省略形 デフォルト 説明
--add-host ホスト-IP マッピングのカスタム設定を追加します。(フォーマット: host:ip)
--allow 追加の権限資格を許可します。(たとえばnetwork.host, security.insecureなど)
--build-arg ビルド時の変数を設定します。
--build-context Additional build contexts (e.g., name=path)
--cache-from 外部キャッシュソース。(user/app:cache, type=local,src=path/to/dirなど。)
--cache-to キャッシュのエクスポート先。(たとえばuser/app:cache, type=local,dest=path/to/dir
--cgroup-parent 任意に指定するコンテナーの親 cgroup。
--compress ビルドコンテキストを gzip を使って圧縮します。
--cpu-period CPU の CFS(Completely Fair Scheduler)間隔を制限します。
--cpu-quota CPU の CFS(Completely Fair Scheduler)クォータを制限します。
--cpu-shares , -c CPU 配分。(相対的な重みづけ)
--cpuset-cpus 利用を許容する CPU 数。(0-3, 0,1
--cpuset-mems 利用を許容するメモリ数。(0-3, 0,1
--file , -f Dockerfile 名。(デフォルトはPATH/Dockerfile
--force-rm 中間コンテナーを常に削除します。
--iidfile イメージ ID をファイルに出力します。
--isolation コンテナーの分離技術(isolation technology)方式。
--label イメージに対してメタデータを設定します。
--load --output=type=dockerの短縮形。
--memory , -m メモリ上限。
--memory-swap メモリとスワップの総量を制限します。-1設定時はスワップ無制限。
--metadata-file ビルド結果のメタデータをファイルに出力します。
--network ビルド時のRUN命令に対してネットワークモードを設定します。
--no-cache イメージビルド時にキャッシュを利用しません。
--no-cache-filter 指定されたステージをキャッシュしません。
--output , -o 出力先。(フォーマット: type=local,dest=path
--platform ビルドにおける対象プラットフォームを設定します。
--progress auto 処理経過の出力タイプを設定します(auto, plain, tty)。コンテナー出力には plain が用いられます。
--pull 常に関連イメージすべてのプルを試みます。
--push --output=type=registryの短縮形。
--quiet , -q ビルド出力を省略し、処理成功時にはイメージ ID を表示します。
--rm true ビルド成功後に中間コンテナーを削除します。
--secret ビルド時に公開する Secret。(フォーマット: id=mysecret[,src=/local/secret])
--security-opt セキュリティオプション。
--shm-size /dev/shmのサイズ。
--squash ビルドしたレイヤーを単一の新レイヤーに押し込みます(squash します)。
--ssh ビルド時に公開する SSH エージェントソケットまたは SSH 鍵(BuildKit 有効時のみ)。(フォーマット: default|<id>[=<socket>|<key>[,<key>]]
--tag , -t 名前および任意のタグを指定します (フォーマット: name:tag)。
--target ビルド対象とするビルドステージを指定します。
--ulimit ulimit オプション。
--builder 設定された builder インスタンスをオーバーライドします。

利用例

Allow extra privileged entitlement (--allow)

--allow=ENTITLEMENT

Allow extra privileged entitlement. List of entitlements:

  • network.host - Allows executions with host networking.
  • security.insecure - Allows executions without sandbox. See related Dockerfile extensions.

For entitlements to be enabled, the buildkitd daemon also needs to allow them with --allow-insecure-entitlement (see create --buildkitd-flags)

Examples

$ docker buildx create --use --name insecure-builder --buildkitd-flags '--allow-insecure-entitlement security.insecure'
$ docker buildx build --allow security.insecure .

Set build-time variables (--build-arg)

Same as docker build command.

There are also useful built-in build args like:

  • BUILDKIT_CONTEXT_KEEP_GIT_DIR=<bool> trigger git context to keep the .git directory
  • BUILDKIT_INLINE_BUILDINFO_ATTRS=<bool> inline build info attributes in image config or not
  • BUILDKIT_INLINE_CACHE=<bool> inline cache metadata to image config or not
  • BUILDKIT_MULTI_PLATFORM=<bool> opt into determnistic output regardless of multi-platform output or not
$ docker buildx build --build-arg BUILDKIT_MULTI_PLATFORM=1 .

More built-in build args can be found in dockerfile frontend docs.

Additional build contexts (--build-context)

--build-context=name=VALUE

Define additional build context with specified contents. In Dockerfile the context can be accessed when FROM name or --from=name is used. When Dockerfile defines a stage with the same name it is overwritten.

The value can be a local source directory, container image (with docker-image:// prefix), Git or HTTP URL.

Replace alpine:latest with a pinned one:

$ docker buildx build --build-context alpine=docker-image://alpine@sha256:0123456789 .

Expose a secondary local source directory:

$ docker buildx build --build-context project=path/to/project/source .
# docker buildx build --build-context project=https://github.com/myuser/project.git .
FROM alpine
COPY --from=project myfile /

Override the configured builder instance (--builder)

Same as buildx --builder.

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 can import cache from a cache manifest or (special) image configuration on the registry.
  • local source can import cache from local files previously exported with --cache-to.
  • gha source 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.

$ 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

Export build cache to an external cache destination (--cache-to)

--cache-to=[NAME|type=TYPE[,KEY=VALUE]]

Export build cache to an external cache destination. Supported types are registry, local, inline and gha.

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.
$ 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

Load the single-platform build result to docker images (--load)

Shorthand for --output=type=docker. Will automatically load the single-platform build result to docker images.

Write build result metadata to the file (--metadata-file)

To output build metadata such as the image digest, pass the --metadata-file flag. The metadata will be written as a JSON object to the specified file. The directory of the specified file must already exist and be writable.

$ docker buildx build --load --metadata-file metadata.json .
$ cat metadata.json
{
  "containerimage.buildinfo": {
    "frontend": "dockerfile.v0",
    "attrs": {
      "context": "https://github.com/crazy-max/buildkit-buildsources-test.git#master",
      "filename": "Dockerfile",
      "source": "docker/dockerfile:master"
    },
    "sources": [
      {
        "type": "docker-image",
        "ref": "docker.io/docker/buildx-bin:0.6.1@sha256:a652ced4a4141977c7daaed0a074dcd9844a78d7d2615465b12f433ae6dd29f0",
        "pin": "sha256:a652ced4a4141977c7daaed0a074dcd9844a78d7d2615465b12f433ae6dd29f0"
      },
      {
        "type": "docker-image",
        "ref": "docker.io/library/alpine:3.13",
        "pin": "sha256:026f721af4cf2843e07bba648e158fb35ecc876d822130633cc49f707f0fc88c"
      }
    ]
  },
  "containerimage.config.digest": "sha256:2937f66a9722f7f4a2df583de2f8cb97fc9196059a410e7f00072fc918930e66",
  "containerimage.descriptor": {
    "annotations": {
      "config.digest": "sha256:2937f66a9722f7f4a2df583de2f8cb97fc9196059a410e7f00072fc918930e66",
      "org.opencontainers.image.created": "2022-02-08T21:28:03Z"
    },
    "digest": "sha256:19ffeab6f8bc9293ac2c3fdf94ebe28396254c993aea0b5a542cfb02e0883fa3",
    "mediaType": "application/vnd.oci.image.manifest.v1+json",
    "size": 506
  },
  "containerimage.digest": "sha256:19ffeab6f8bc9293ac2c3fdf94ebe28396254c993aea0b5a542cfb02e0883fa3"
}

Set the export action for the build result (-o, --output)

-o, --output=[PATH,-,type=TYPE[,KEY=VALUE]

Sets the export action for the build result. In docker build all builds finish by creating a container image and exporting it to docker images. buildx makes this step configurable allowing results to be exported directly to the client, oci image tarballs, registry etc.

Buildx with docker driver currently only supports local, tarball exporter and image exporter. docker-container driver supports all the exporters.

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 exporter and write to stdout.

$ docker buildx build -o . .
$ docker buildx build -o outdir .
$ docker buildx build -o - - > out.tar
$ docker buildx build -o type=docker .
$ docker buildx build -o type=docker,dest=- . > myimage.tar
$ docker buildx build -t tonistiigi/foo -o type=registry

Supported exported types are:

local

The local export type writes all result files to a directory on the client. The new files will be owned by the current user. On multi-platform builds, all results will be put in subdirectories by their platform.

Attribute key:

  • dest - destination directory where files will be written

tar

The tar export type writes all result files as a single tarball on the client. On multi-platform builds all results will be put in subdirectories by their platform.

Attribute key:

  • dest - destination path where tarball will be written. “-” writes to stdout.

oci

The oci export type writes the result image or manifest list as an OCI image layout tarball on the client.

Attribute key:

  • dest - destination path where tarball will be written. “-” writes to stdout.

docker

The docker export type writes the single-platform result image as a Docker image specification tarball on the client. Tarballs created by this exporter are also OCI compatible.

Currently, multi-platform images cannot be exported with the docker export type. The most common usecase for multi-platform images is to directly push to a registry (see registry).

Attribute keys:

  • dest - destination path where tarball will be written. If not specified the tar will be loaded automatically to the current docker instance.
  • context - name for the docker context where to import the result

image

The image exporter writes the build result as an image or a manifest list. When using docker driver the image will appear in docker images. Optionally, image can be automatically pushed to a registry by specifying attributes.

Attribute keys:

  • name - name (references) for the new image.
  • push - boolean to automatically push the image.

registry

The registry exporter is a shortcut for type=image,push=true.

Set the target platforms for the build (--platform)

--platform=value[,value]

Set the target platform for the build. All FROM commands inside the Dockerfile 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 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 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 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 TARGETPLATFORM build argument. Please refer to the docker build documentation for the full description of automatic platform argument variants .

The formatting for the platform specifier is defined in the containerd source code.

$ docker buildx build --platform=linux/arm64 .
$ docker buildx build --platform=linux/amd64,linux/arm64,linux/arm/v7 .
$ docker buildx build --platform=darwin .

Set type of progress output (--progress)

--progress=VALUE

Set type of progress output (auto, plain, tty). Use plain to show container output (default “auto”).

You can also use the BUILDKIT_PROGRESS environment variable to set its value.

The following example uses plain output during the build:

$ docker buildx build --load --progress=plain .

#1 [internal] load build definition from Dockerfile
#1 transferring dockerfile: 227B 0.0s done
#1 DONE 0.1s

#2 [internal] load .dockerignore
#2 transferring context: 129B 0.0s done
#2 DONE 0.0s
...

Push the build result to a registry (--push)

Shorthand for --output=type=registry. Will automatically push the build result to registry.

Secret to expose to the build (--secret)

--secret=[type=TYPE[,KEY=VALUE]

Exposes secret to the build. The secret can be used by the build using RUN --mount=type=secret mount.

If type is unset it will be detected. Supported types are:

file

Attribute keys:

  • id - ID of the secret. Defaults to basename of the src path.
  • src, source - Secret filename. id used if unset.
# syntax=docker/dockerfile:1.3
FROM python:3
RUN pip install awscli
RUN --mount=type=secret,id=aws,target=/root/.aws/credentials \
  aws s3 cp s3://... ...
$ docker buildx build --secret id=aws,src=$HOME/.aws/credentials .

env

Attribute keys:

  • 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.
# syntax=docker/dockerfile:1.3
FROM node:alpine
RUN --mount=type=bind,target=. \
  --mount=type=secret,id=SECRET_TOKEN \
  SECRET_TOKEN=$(cat /run/secrets/SECRET_TOKEN) yarn run test
$ SECRET_TOKEN=token docker buildx build --secret id=SECRET_TOKEN .

Size of /dev/shm (--shm-size)

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 (gigabytes). If you omit the unit, the system uses bytes.

SSH agent socket or keys to expose to the build (--ssh)

--ssh=default|<id>[=<socket>|<key>[,<key>]]

This can be useful when some commands in your Dockerfile need specific SSH authentication (e.g., cloning a private repository).

--ssh exposes SSH agent socket or keys to the build and can be used with the RUN --mount=type=ssh mount.

Example to access Gitlab using an SSH agent socket:

# syntax=docker/dockerfile:1.3
FROM alpine
RUN apk add --no-cache openssh-client
RUN mkdir -p -m 0700 ~/.ssh && ssh-keyscan gitlab.com >> ~/.ssh/known_hosts
RUN --mount=type=ssh ssh -q -T git@gitlab.com 2>&1 | tee /hello
# "Welcome to GitLab, @GITLAB_USERNAME_ASSOCIATED_WITH_SSHKEY" should be printed here
# with the type of build progress is defined as `plain`.
$ eval $(ssh-agent)
$ ssh-add ~/.ssh/id_rsa
(Input your passphrase here)
$ docker buildx build --ssh default=$SSH_AUTH_SOCK .

Set ulimits (--ulimit)

--ulimit is specified with a soft and hard limit as such: <type>=<soft limit>[:<hard limit>], for example:

$ docker buildx build --ulimit nofile=1024:1024 .

Note

If you do not provide a hard limit, the soft limit is used for both values. If no ulimits are set, they are inherited from the default ulimits set on the daemon.

上位コマンド

コマンド 説明
docker buildx Docker Buildx
コマンド 説明
docker buildx bake ファイルからビルドします。
docker buildx build ビルドを開始します。
docker buildx create 新規にビルダーインスタンスを生成します。
docker buildx du ディスク利用量。
docker buildx imagetools レジストリ上のイメージを操作するコマンドです。
docker buildx inspect 現在のビルダーインスタンスを確認します。
docker buildx ls ビルダーインスタンスを一覧表示します。
docker buildx prune ビルドキャッシュを削除します。
docker buildx rm ビルダーインスタンスを削除します。
docker buildx stop ビルダーインスタンスを停止します。
docker buildx use 現在のビルダーインスタンスを設定します。
docker buildx version Buildx のバージョンを表示します。