docker buildx build

説明

構築を開始します。

使い方

$ docker buildx build [OPTIONS] PATH | URL | -

補足説明

buildx build コマンドは BuildKit を使って構築を開始します。このコマンドは docker build コマンドの見た目と似ており、いくつかのフラグや引数が同じです。

ほとんどのフラグに関するドキュメントは docker build のドキュメント をご覧ください。ここでは新しいフラグのサブセットを説明します。

コマンドの使用例は、以下の 使用例のセクション をご覧ください。

オプション

名前, 省略形

デフォルト

説明

--add-host

任意のホストに対し IP を割り当てを追加(書式: host:ip

--allow

拡張特権資格(extra privileged entitlement) を許可(例: network.host , security.insecure

--build-arg

構築時の変数を設定

--cache-from

外部キャッシュのソース(例: ser/app:cache , type=local,src=path/to/dir

--cache-to

外部キャッシュの宛先(例: ser/app:cache , type=local,src=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 配分(share) (相対ウェイト)

--cpuset-cpus

アクセスを許可する CPU を指定( 0-3, 0, 1 )

--cpuset-mems

アクセスを許可するメモリノードを指定( 0-3, 0, 1 )

--file-f

Dockerfile の名前(デフォルトは パス/Dockerfile

--force-rm

中間コンテナを常に削除

--iidfile

イメージ ID をファイルに書き込む

--isolation

コンテナ分離技術

--label

イメージにメタデータを設定

--load

--output=type=docker の省略形

--memory-m

メモリの上限

--memory-swap

スワップの上限は、メモリとスワップの合計と同じ: -1 はスワップを無制限にする

--metadata-file

構築結果のメタデータをファイルに書き込む

--network

構築中の RUN 命令で使うネットワークモードを指定

--no-cache

イメージの構築時にキャッシュを使用しない

--output-o

アウトプット先を指定(書式:type=local,dest=path)

--platform

サーバがマルチプラットフォーム対応であれば、プラットフォームを指定

--progress

auto

進行状況の出力タイプを設定(auto、plain、tty)。plain を使うと、コンテナの出力を表示

--pull

イメージは、常に新しいバージョンのダウンロードを試みる

--push

--output=type=registry の省略形

--quiet-q

構築時の出力と成功時のイメージ ID 表示を抑制

--rm

true

構築に成功後、中間コンテナを削除

--secret

構築時に利用するシークレットファイル(書式: id=mysecret,src=/local/secret

--security-opt

セキュリティのオプション

--shm-size

/dev/shm の容量

--squash

構築するレイヤを、単一の新しいレイヤに 押し込む(squash)

--ssh

構築時に利用する SSH エージェントのソケットやキー(書式: default | <id>[=<socket>] | <key>[,<key>]]

--tag-t

名前と、オプションでタグを 名前:タグ の形式で指定

--target

構築する対象の構築ステージを指定

--ulimit

ulimit オプション

--builder

ビルダー・インスタンス設定を上書き

使用例

builder 対象の設定を上書き (--builder)

buildx --builder と同じです。

構築対象のプラットフォームを指定

--platform=value[,value]

構築対象のプラットフォームを指定します。Dockerfile 内にある全ての FROM 命令は、 --platform フラグがなければ、自身のプラットフォーム用のイメージを取得します。そして、最終的なイメージのプラットフォームも自身のものとなります。デフォルトの値は、buildkit デーモンが動作しているプラットフォームです。

buildxdocker-container ドライバを使う場合は、フラグに対してカンマ区切りで複数の値を指定できます。複数の値を指定した結果は、指定したプラットフォームすべてに対して構築し、1つのマニフェストリストに連結します。

DockerfileRUN 命令を実行する必要がある場合、ビルダは指定したプラットフォーム用のランタイムをサポートする必要があります。クリーンセットアップの場合、ビルダは自らのシステムアーキテクチャ用のランタイムのサポートが必要です。カーネルが binfmt_misc ランチャーをセカンダリ・アーキテクチャとしてサポートしている場合、buildx はそれらを自動的に対応します。Docker デスクトップ版は binfmt_misc を備えており、 arm64arm アーキテクチャに自動的に対応しています。現在のビルダ・インスタンスが対応しているランタイム・プラットフォームを確認するには、 docker buildx inspect --bootstrap を実行します。

Dockerfile 内では、 ``TARGETPLATFORM `` build 引数よって現在のプラットフォーム値を取得できます。自動プラットフォーム引数の種類は、 docker build ドキュメント をご覧ください。

プラットフォームの指定形式は containerd ソースコード で定義されています。

使用例

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

進捗の出力形式を指定(--progress)

--progress=VALUE

進捗の出力形式を指定します( auto、plain、tty)。plain を使うとコンテナの出力を表示します(デフォルトは auto )。

注釈

値を指定するには、BUILDKIT_PROGRESS 環境変数の値も利用できます。

以下は、構築中に plain 出力を使う例です。

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

構築結果の出力方法を指定(-o, --output)

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

build 結果の出力処理を設定します。 docker build で全ての構築が終わると、コンテナのイメージを作成し、それを docker images に出力します。 buildx ではこの手順が設定できるようになっており、処理結果を直接クライアントや、oci イメージ・tar ボールやレジストリ等に出力できます。

Buildx の docker ドライバが現時点でサポートしているのは、 local 、 tar ボール・エクスポータ(tarball exporter)イメージ・エクスポータ(image exporter) のみです。 docker-container ドライバは全てのエクスポータをサポートします。

値にパスを指定した場合には、 buidxローカル・エクスポータ(local exporter) でこのパスを出力先に使います。もしも値が「-」であれば、 buildxtar エクスポータを使い 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

サポートしているエクスポータは以下の通りです。

local

local エクスポート型は、全ての結果をクライアント上のディレクトリにあるファイルへ書き出します。新しいファイルの所有者は現在のユーザになります。マルチプラットフォーム・ビルドでは、各プラットフォーム用のサブディレクトリに結果が出力されます。

属性のキー:

  • dest - ファイル出力先のディレクトリ

tar

tar エクスポート型は、全ての結果をクライアント上の tar ボールに書き出します。マルチプラットフォーム・ビルドでは、各プラットフォーム用のサブディレクトリに結果が出力されます。

属性のキー:

  • dest - tar ボール出力先のディレクトリ。 - は標準出力に書き出す

oci

oci エクスポート型は、全ての結果をクライアント上の OCI イメージ・レイアウト に書き出します。

属性のキー:

  • dest - tar ボール出力先のディレクトリ。 - は標準出力に書き出す

docker

docker エクスポート型は、特定のプラットフォームに対する Docker イメージ仕様 のイメージとしてクライアント上に書き出します。このエクスポータによって作成される tar ボールは、 OCI 互換性もあります。

現時点では、マルチプラットフォーム・イメージは docker エクスポート型はでは出力できません。マルチプラットフォーム対応イメージの最も一般的な利用方法は、レジストリに直接送信する場合です( registry をご覧ください。)。

属性のキー:

  • dest - tarボール出力先のパス。このパスの指定が無い場合、tar は現在の Docker インスタンスへ自動的に読み込む

  • context - 結果をインポートする docker コンテクスト名です

image

image エクスポータは、構築結果をイメージまたはマニフェストリストとして出力します。 docker ドライバでイメージを使う場合は、docker イメージとして出力されます。オプションとして、属性の指定によってイメージを自動的にレジストリに送信できます。

属性のキー:

  • name - 新しいイメージの名前(リファレンス)

  • push - 自動的にイメージを送信するかどうかを bollean(0か1)で指定

registry

registry エクスポータは type=image,push=true の省略形です。

構築結果をレジストリに送信(--push)

--output=type=registry の省略形です。構築結果をレジストリに自動送信します。

単一プラットフォームの構築結果を docker images に読み込む(--load)

--output=type=docker の省略形です。単一プラットフォーム向けの構築結果を docker images に読み込みます。

構築用に外部のキャッシュソースを使用(--cache-from)

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

構築用に外部のキャッシュソースを使います。サポートしている型は registrylocalgha です。

  • registryregistry ソース は、キャッシュ・マニフェストやレジストリ上の(特別な)設定からキャシュを取り込めます。

  • locallocal ソース は、以前に --cache-to で出力済みのロールファイルから、キャッシュを取り込めます。

  • ghagha ソース は、以前に --cache-to で GitHub リポジトリに出力済みのキャッシュから、キャッシュを取り込めます。

型(タイプ)を指定しなければ、 registry エクスポータが指定された参照先として使われます。

docker ドライバでは、現時点でサポートしているのは、レジストリからの構築キャッシュ取り込みだけです。

使用例

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

キャッシュエクスポータと利用可能な属性については、こちらをご覧ください:https://github.com/moby/buildkit#export-cache

構築キャッシュを外部のキャッシュ先へ出力(--cache-to)

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

外部のキャッシュ先に構築キャッシュを出力します。サポートしている型は registrylocalinlinegha です。

  • registryregistry 型 は、構築キャッシュをレジストリ内のキャッシュ・マニフェストに出力します。

  • locallocal 型 は、クライアント上のローカルディレクトリへキャッシュを出力します。

  • inlineinline 型 は、イメージ設定内部のキャッシュ・メタデータに出力します。

  • ghagha 型Github Actions Cache service API を通してキャッシュを出力します。

docker ドライバが現時点でサポートしているのは、イメージ設定内部のキャッシュ・メタデータに直接(インラインに)出力するだけです。別の方法として、 --build-arg BUILDKIT_INLINE_CACHE=1 をインライン・キャッシュ・エクスポータのトリガとして使えます。

属性のキー:

  • mode … キャッシュがどれだけのレイヤに対応するかを指定します。 min は最終構築ステージのレイヤのみ出力します。 max は全ステージのレイヤを出力します。メタデータは構築全体を通し、常に出力します。

使用例

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

キャッシュ・エクスポータと利用可能な属性については、 https://github.com/moby/buildkit#export-cache をご覧ください。

拡張特権資格(extra privileged entitlement) を許可(--allow)

--allow=ENTITLEMENT

拡張特権資格(extra privileged entitlement) を許可します。資格(entitlement)の一覧はこちらです:

  • network.host … ホストネットワーク機能の実行を許可します。

  • security.insecure … サンドボックス無しでの実行を許可。 関連する Dockerfile 拡張 をご覧ください。

資格の有効化には、 buildkit デーモンも --allow-insecure-entitlement を許可する必要があります( create --buildkit-flags をご覧ください)。

使用例

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

/dev/shm の容量(--shm-size)

書式は <数値><単位> です。 数値0 より大きい必要があります。単位はオプションで指定でき、 b (バイト)、 k (キロバイト)、 m (メガバイト)、 g (ギガバイト)が使えます。単位を省略すると、システムはバイトとして扱います。

ulimit の設定(--ulimit)

--ulimitソフトリミット(soft limit)ハードリミット(hard limit) を指定します。書式は <type>=<ソフトリミット>[:<ハードリミット>] です。以下は例です。

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

注釈

hard limit を指定しない場合、 soft limit が両方の値として用いられます。 ulimits の指定が無ければ、デーモン上のデフォルト ulimits を継承します。

親コマンド

コマンド

説明

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 バージョン情報を表示