docker buildx create

説明

新しい ビルダ・インスタンス(builder instance) を作成します。

使い方

$ docker buildx create [OPTIONS] [CONTEXT|ENDPOINT]

補足説明

docker コンテクストやエンドポイントを指定する、新しいビルダ・インスタンスを作成します。コンテクストとは docker context ls にあるコンテクスト名であり、エンドポイントとは docker ソケットの場所を示します(例: DOCKER_HOST の値)。

デフォルトでは、現在の Docker 設定がコンテクストとエンドポイントの値として使われます。

ビルダ・インスタンスとは、構築を処理時の 隔離環境(isolated environment) です。全ての Docker コンテクストもまた、デフォルトのビルダー・インスタンスを持っています。

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

オプション

名前, 省略形 デフォルト 説明
--append   ビルダを交代するノードを追加
--bootstrap   作成後のブート・ビルダ
--buildkit-flags   buildkitd デーモン用のフラグ
--config   BuildKit 設定ファイル
--driver   使用するドライバ(利用可能なもの: dockerdocker-containerkubernetes
--driver-opt   ドライバに対するオプション
--leave   ビルダを交代するノードの削除
--name   ビルダ・インスタンス名
--node   指定した名前でノードを作成・変更
--platform   現在のノードに対するプラットフォームを指定
--use   現在のビルダー・インスタンスを指定
--builder   ビルダー・インスタンス設定を上書き

使用例

既存のビルダーに新しいノードを追加(--append)

--append は命令の処理を変更するフラグで、 --name で指定された既存のビルダーに新しいノードを追加します。Buildx はサポートしているプラットフォームに基づき、適切な構築用のノードを選択します。

使用例

$ docker buildx create mycontext1
eager_beaver

$ docker buildx create --name eager_beaver --append mycontext2
eager_breaver

buildkitd デーモンに対するオプションを指定(--buildkitd-flags)

--buildkitd-flags FLAGS

buildkitd デーモンの起動時にフラグを追加します。これは --config で指定した設定よりも優先されます。利用可能なフラグは buildkitd --help をご覧ください。

使用例

--buildkitd-flags '--debug --debugaddr 0.0.0.0:6666'

buildkitd デーモン用の設定ファイルを指定(--config)

--config FILE

buildkitd デーモンが使うための設定ファイルを指定します。この設定は --buildkitd-flags で上書き出来ます。 buildkitd 設定ファイルの例 をご覧ください。

注意が必要なのは、 docker-container ビルダを作成し、 buildkitd.toml 設定でレジストリの証明書を指定している場合です。この設定ファイルは、コンテナ内の /etc/buildkit/certs 以下にコピーされ、更新された設定はそこに反映されます。

使用するビルダ・ドライバを指定(--driver)

--driver DRIVER

使用するビルダ・ドライバを指定します。複数のドライバが利用可能で、それぞれに設定があります。

docker ドライバ

ビルダは docker デーモンの中で構築します。ドライバに --load フラグがあれば、デフォルトの buildx build を意味します。しかし、マルチプラットフォームのイメージ構築や、既存のキャッシュに対しては、現時点ではサポートしていません。

docker-container ドライバ

docker を経由して実行する BuildKit コンテナを使います。このドライバでは、マルチプラットフォーム・イメージと出力されたキャッシュの両方をサポートしています。

docker ドライバとは異なり、構築イメージは自動的に docker images に反映されません。また、そこにイメージを反映するには biuld --load の指定が必要です。

kubernetes ドライバ

kubernets ポッドを使います。このドライバでは、イメージ構築構築用に、 BuidKit コンテナイメージを指定したポッドを起動できます。

docker ドライバとは異なり、構築イメージは自動的に docker images に反映されません。また、そこにイメージを反映するには biuld --load の指定が必要です。

ドライバ固有のオプションを追加設定(--driver-opt)

--driver-opt OPTIONS

ドライバ固有のオプションを追加します。各ドライバごとの詳細はこちらです。

  • docker … ドライバのオプションはありません。

  • docker-container

    • image=IMAGE … buildkit 実行用のコンテナ・イメージを指定します。
    • network=NETMODE … buidkit コンテナ実行時のネットワーク・モードを指定します。
    • cgroup-parent=CGROUP … docker が「cgroupfs」ドライバを使用している場合は、buildkit コンテナの親 cgroup を指定します。デフォルトは /docker/buildx です。
  • kubernetes

    • image=IMAGE … buidkit 実行用のコンテナ・イメージを指定します。
    • namespace=NS … Kubernetes 名前空間を指定します。デフォルトは現在の名前空間です。
    • replicas=NPod レプリカ数を指定します。デフォルトは 1 です。
    • requests.cpu … 要求する CPU の値を、Kubernetes CPU 単位で指定します。例 requests.cpu=100mrequests.cpu=2
    • requests.memory … 要求するメモリの値を、バイトあるいは有効な単位で指定します。例 requests.memory=500Mi````
    • limits.cpu … CPU 制限値を Kubernetes CPU 単位で指定します。例 limits.cpu=100mlimits.cpu=2
    • limits.memory … メモリ上限値を、バイトあるいは有効な単位で指定します。例 limits.memory=500Milimits.memory=4G
    • nodeselector="label1=value1,label2=value2Pod ノードセレクタの kv (キーと値)を指定します。デフォルトはありません。例 nodeselector=kubernetes.io/arch=arm64
    • rootless=(true|false)securityContext.privileged を使わず、root ではないユーザとしてコンテナを実行します。 Ubuntu ホスト・カーネルの利用を推奨します。 デフォルトは false です。
    • loadbalance=(sticky|random) … 負荷分散方式を設定します。 sticky に指定すると、ポッドはパスに含むハッシュを使って選ばれます。デフォルトは sticky です。
    • qemu.install=(true|false) … マルチプラットフォームをサポートするため、QEMU エミュレーションをインストールします。
    • qemu.image=IMAGE … QEMU エミュレーション・イメージを指定します。デフォルトは tonistiigi/binfmt:latest です。

カスタム・ネットワークを使用

$ docker network create foonet
$ docker buildx create --name builder --driver docker-container --driver-opt network=foonet --use
$ docker buildx inspect --bootstrap
$ docker inspect buildx_buildkit_builder0 --format={{.NetworkSettings.Networks}}
map[foonet:0xc00018c0c0]

OpenTelemetry サポート

Jaeger でトレースをキャプチャするには、 JAEGER_TRACE 環境変数を指定し、 driver-opt で収集用のアドレス(collection address)を指定します。

$ docker run -d --name jaeger -p 6831:6831/udp -p 16686:16686 jaegertracing/all-in-one
$ docker buildx create --name builder --driver docker-container --driver-opt network=host --driver-opt env.JAEGER_TRACE=localhost:6831 --use
$ docker buildx inspect --bootstrap
# buildx command should be traced at http://127.0.0.1:16686/

ビルダをノードから削除(--leave)

ビルダからノードを削除するには、 --leave フラグによって命令の処理を変更します。ビルダは --name の指定が必要であり、削除するノードは --node の指定が必要です。

使用例

$ docker buildx create --name mybuilder --node mybuilder0 --leave

ビルダ名を指定します(--name)

--name NAME

Specify the name of the node (--node)🔗

--name フラグは、作成もしくは変更するビルダの名前を指定します。 指定がなければ、何らかの名前が自動生成されます。

ノード名を指定(--node)

--node NODE

--node フラグは、作成もしくは変更するノードの名前を指定します。 指定がなければ、何らかの名前をインデックス値に基づき自動生成します。

ノードがサポートしているプラットフォームを設定

--platform PLATFORMS

--platform フラグは、ノードがサポートしているプラットフォームを指定します。プラットフォームの形式は OS/アーキテクチャ/派生 のカンマ区切りを想定しています。ノードはサポートしているプラットフォームを自動検出しますが、同じプラットフォームを複数のノードがサポートしている場合、手動でもプラットフォームを優先指定できます。

使用例

$ docker buildx create --platform linux/amd64
$ docker buildx create --platform linux/arm64,linux/arm/v8

新しく作成したビルダに自動的に切り替える

--use フラグを使うと、現在のビルダから新しく作成したビルダへと、自動的に切り替えます。これは docker buildx use $(docker buildx create ...) を実行するのと同等です。

親コマンド

コマンド 説明
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 バージョン情報を表示