docker buildx build

説明

構築を開始します。

使い方

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

補足説明

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

ほとんどのフラグに関するドキュメントは 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 フラグがなければ、自身のプラットフォーム用のイメージを取得します。そして、最終的なイメージのプラットフォームも自身のものとなります。デフォルトの値は、buidkit デーモンが動作しているプラットフォームです。

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