docker buildx bake¶

使い方 ¶

$ docker buildx bake [オプション] [対象...]

補足説明 ¶

bake はハイレベルな構築コマンドです。構築時に、それぞれの指定対象を並列実行します。

導入には High-level build options をご覧ください。

注意点として、今後に必要性があれば、 buildx bake コマンドに後方互換機能を追加する場合があります。私達は、このコマンドの改善や更なる機能拡張についてのフィードバックをお待ちしています。

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

オプション ¶

名前, 省略形	デフォルト	説明
`--file` , `-f`		構築定義ファイル
`--load`		`--set=*.output=type=docker` の簡易形
`--metadata-file`		構築結果のメタデータをファイルに書き込む
`--no-cache`		イメージ構築時、キャッシュを使用しない
`--print`		構築時以外のオプションを表示
`--progress`	`auto`	進行状況の表示種類を設定（ `auto` , `plain`, `tty` ）。plain を使うと、コンテナの出力を表示
`--pull`		常にイメージの新しいバージョンの取得を試みる
`--push`		`--set=*.output=type=registry` の簡易形
`--set`		対象の値を上書き（例： `targetpattern.key=value` ）
`--builder`		ビルダー・インスタンスの設定を上書き

使用例 ¶

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

buildx --builder と同じです。

構築定義ファイル(build definition file) を指定 (-f, --file)¶

デフォルトでは、 buildx bake は現在のディレクトリで、次のような定義ファイルを探します。

docker-compose.yml
docker-compose.yaml
docker-bake.json
docker-bake.override.json
docker-bake.hcl
docker-bake.override.hcl

構築定義ファイルとして使うファイルを、 -f または --file オプションを使って指定します。ここでのファイルとは、Docker Compose、JSON、HCL ファイルです。複数のファイが指定された場合には、読み込み可能な設定すべてを連結します。

以下の例は、 docker-compose.dev.yaml という名前の Docker Compose ファイルを構築定義ファイルとして使い、ファイル内の全てのターゲットを構築します。

$  docker buildx bake -f docker-compose.dev.yaml

[+] Building 66.3s (30/30) FINISHED
  =>  [frontend internal] load build definition from Dockerfile  0.1s
  => => transferring dockerfile: 36B                            0.0s
  => [backend internal] load build definition from Dockerfile   0.2s
  => => transferring dockerfile: 3.73kB                         0.0s
  => [database internal] load build definition from Dockerfile  0.1s
  => => transferring dockerfile: 5.77kB                         0.0s
  ...

構築対象の名前を指定すると、指定したターゲット（対象）のみ構築します。以下の例は、 docker-compose.dev.yaml ファイル内で定義された、 backend と database ターゲットを構築します。 frontend ターゲットは構築をスキップします。

$ docker buildx bake -f docker-compose.dev.yaml backend database

[+] Building 2.4s (13/13) FINISHED
  =>  [backend internal] load build definition from Dockerfile  0.1s
  =>  => transferring dockerfile: 81B                           0.0s
  =>  [database internal] load build definition from Dockerfile 0.2s
  =>  => transferring dockerfile: 36B                           0.0s
  =>  [backend internal] load .dockerignore                     0.3s
  ...

また、リモート bake 定義も使えます。

$ docker buildx bake "git://github.com/docker/cli#v20.10.11" --print
1 [internal] load git source git://github.com/docker/cli#v20.10.11
1 0.745 e8f1871b077b64bcb4a13334b7146492773769f7       refs/tags/v20.10.11
1 2.022 From git://github.com/docker/cli
1 2.022  * [new tag]         v20.10.11  -> v20.10.11
1 DONE 2.9s
{
  "group": {
    "default": {
      "targets": [
        "binary"
      ]
    }
  },
  "target": {
    "binary": {
      "context": "git://github.com/docker/cli#v20.10.11
      "dockerfile": "Dockerfile",
      "args": {
        "BASE_VARIANT": "alpine",
        "GO_STRIP": "",
        "VERSION": ""
      },
      "target": "binary",
      "platforms": [
        "local"
      ],
      "output": [
        "build"
      ]
    }
  }
}

見ての通り、定義においてコンテクストが存在していない場合でも、 git://github.com/docker/cli をコンテクストとします。

bake コマンドを使い、リモートから読み込む bake ファイルが主となるコンテクストを使いたい場合には、内蔵されている変数 BAKE_CMD_CONTEXT が利用できます。

$ cat https://raw.githubusercontent.com/tonistiigi/buildx/remote-test/docker-bake.hcl
target "default" {
  context = BAKE_CMD_CONTEXT
  dockerfile-inline = &lt;&lt;EOT
FROM alpine
WORKDIR /src
COPY . .
RUN ls -l &amp;&amp; stop
EOT
}

$ docker buildx bake "git://github.com/tonistiigi/buildx#remote-test" --print
{
  "target": {
    "default": {
      "context": ".",
      "dockerfile": "Dockerfile",
      "dockerfile-inline": "FROM alpine\nWORKDIR /src\nCOPY . .\nRUN ls -l \u0026\u0026 stop\n"
    }
  }
}

$ touch foo bar
$ docker buildx bake "git://github.com/tonistiigi/buildx#remote-test"
...
  > [4/4] RUN ls -l && stop:
#8 0.101 total 0
#8 0.102 -rw-r--r--    1 root     root             0 Jul 27 18:47 bar
#8 0.102 -rw-r--r--    1 root     root             0 Jul 27 18:47 foo
#8 0.102 /bin/sh: stop: not found

$ docker buildx bake "git://github.com/tonistiigi/buildx#remote-test" "git://github.com/docker/cli#v20.10.11" --print
#1 [internal] load git source git://github.com/tonistiigi/buildx#remote-test
#1 0.429 577303add004dd7efeb13434d69ea030d35f7888       refs/heads/remote-test
#1 CACHED
{
  "target": {
    "default": {
      "context": "git://github.com/docker/cli#v20.10.11
      "dockerfile": "Dockerfile",
      "dockerfile-inline": "FROM alpine\nWORKDIR /src\nCOPY . .\nRUN ls -l \u0026\u0026 stop\n"
    }
  }
}

$ docker buildx bake "git://github.com/tonistiigi/buildx#remote-test" "git://github.com/docker/cli#v20.10.11"
...
 >  [4/4] RUN ls -l && stop:
#8 0.136 drwxrwxrwx    5 root     root          4096 Jul 27 18:31 kubernetes
#8 0.136 drwxrwxrwx    3 root     root          4096 Jul 27 18:31 man
#8 0.136 drwxrwxrwx    2 root     root          4096 Jul 27 18:31 opts
#8 0.136 -rw-rw-rw-    1 root     root          1893 Jul 27 18:31 poule.yml
#8 0.136 drwxrwxrwx    7 root     root          4096 Jul 27 18:31 scripts
#8 0.136 drwxrwxrwx    3 root     root          4096 Jul 27 18:31 service
#8 0.136 drwxrwxrwx    2 root     root          4096 Jul 27 18:31 templates
#8 0.136 drwxrwxrwx   10 root     root          4096 Jul 27 18:31 vendor
#8 0.136 -rwxrwxrwx    1 root     root          9620 Jul 27 18:31 vendor.conf
#8 0.136 /bin/sh: stop: not found

イメージ構築時にキャッシュを使わない(--no-cache)¶

build --no-cahe と同じです。イメージの構築中にキャッシュを使いません。

構築時のオプションを表示 (--print)¶

任意のターゲットを構築するにあたり、構築せずに結果を JSON 形式で表示します。

$  docker buildx bake -f docker-bake.hcl --print db
{
  "group": {
    "default": {
      "targets": [
        "db"
      ]
    }
  },
  "target": {
    "db": {
      "context": "./",
      "dockerfile": "Dockerfile",
      "tags": [
        "docker.io/tiborvass/db"
      ]
    }
  }
}

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

build --progress と同じです。進捗の出力形式（auto, plain, tty）を指定します。plain を使うとコンテナの出力を表示します（デフォルトは auto ）。

注釈

``BUILDKIT_PROGRESS` 環境変数を使っても値が指定できます。

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

$ docker buildx bake --progress=plain

#2 [backend internal] load build definition from Dockerfile.test
#2 sha256:de70cb0bb6ed8044f7b9b1b53b67f624e2ccfb93d96bb48b70c1fba562489618
#2 ...

#1 [database internal] load build definition from Dockerfile.test
#1 sha256:453cb50abd941762900a1212657a35fc4aad107f5d180b0ee9d93d6b74481bce
#1 transferring dockerfile: 36B done
#1 DONE 0.1s
...

常にイメージの新しいバージョンの取得を試みる (--pull)¶

build --pull と同じです。

コマンドラインからターゲットの設定を上書き (--set)¶

--set targetpattern.key[.subkey]=value

コマンドラインからターゲットの設定を上書きします。パターンマッチ構文は https://golang.org/pkg/path/#Match で定義されています。

例 ¶

$ docker buildx bake --set target.args.mybuildarg=value
$ docker buildx bake --set target.platform=linux/arm64
$ docker buildx bake --set foo*.args.mybuildarg=value # 「foo」で始まる全てのターゲットに対し、構築の引数を上書き
$ docker buildx bake --set *.platform=linux/arm64     # 全てのターゲットに対するプラットフォームを上書き
$ docker buildx bake --set foo*.no-cache              #「with」で始まるターゲットのみ、キャッシュをしない（回避）

上書きできるフィールドの一覧はこちらです： args , `` cache-from`` , `` cache-to`` , `` context`` , `` dockerfile`` , `` labels`` , `` no-cache`` , `` output`` , `` platform`` , `` pull`` , `` secrets`` , `` ssh`` , `` tags`` , `` target``

ファイル定義 ¶

構築グループとターゲットを定義するため bake がサポートしているのは、 compose ファイルに加え、JSON 形式と HCL ファイル互換形式です。

ターゲットに対しては、単一の docker build として、 docker build . を指定した時と同じオプションで実行した結果が反映されます。グループはターゲットをグループにしたものです。

複数のファイルに、同じターゲットと最終構築オプションを記載できます。これらは最終的に1つにまとめられます。

compose ファイルの各サービスは、ターゲットに相当します。

グループは targets オプションでターゲット一覧を指定できます。ターゲットでは構築オプションに inherits （継承）オプションの設定を使えば、ターゲットやグループに対してそれぞれ継承できます。

メモ：bake コマンドの設計は作業を行っている途中のため、フィードバックを元に挙動が変わる場合があります。

HCL 定義例 ¶

group "default" {
    targets = ["db", "webapp-dev"]
}

target "webapp-dev" {
    dockerfile = "Dockerfile.webapp"
    tags = ["docker.io/username/webapp"]
}

target "webapp-release" {
    inherits = ["webapp-dev"]
    platforms = ["linux/amd64", "linux/arm64"]
}

target "db" {
    dockerfile = "Dockerfile.db"
    tags = ["docker.io/username/db"]
}

有効なターゲット・フィールドの一覧はこちらです。

args , cache-from , cache-to , context , dockerfile , inherits , labels , no-cache , output , platform , pull , secrets , ssh , tags , target

グローバル範囲(global scope) の属性 ¶

HCL や JSON でグローバル範囲の属性（attribute）を定義し、それらをコードでの再利用や、変数の値の設定で利用できます。これが意味するのは、指定するか上書きしたい値が入った「データだけを持つ」HCL ファイルを利用し、それを通常のファイル出力に使えます。

# docker-bake.hcl
variable "FOO" {
    default = "abc"
}

target "app" {
    args = {
        v1 = "pre-${FOO}"
    }
}

このファイルは直接使えます。

$ docker buildx bake --print app
{
  "group": {
    "default": {
      "targets": [
        "app"
      ]
    }
  },
  "target": {
    "app": {
      "context": ".",
      "dockerfile": "Dockerfile",
      "args": {
        "v1": "pre-abc"
      }
    }
  }
}

あるいは、上書き用の設定ファイルを作成します。

# env.hcl
WHOAMI="myuser"
FOO="def-${WHOAMI}"

それから、両方のファイルを使って bake を実行します。

$ docker buildx bake -f docker-bake.hcl -f env.hcl --print app
{
  "group": {
    "default": {
      "targets": [
        "app"
      ]
    }
  },
  "target": {
    "app": {
      "context": ".",
      "dockerfile": "Dockerfile",
      "args": {
        "v1": "pre-def-myuser"
      }
    }
  }
}

HCL 変数とファンクション ¶

Terraform プロバイダで変数を定義するのと同じような方法で、HCL フェア形式も変数ブロック定義(variable block definition) をサポートしています。これにより、現在の環境上で提供されている値を元に変数を定義したり、変数の定義がなければデフォルト値を指定できます。

HCL ファイルでは go-cty によって提供されている広く役立つ機能群が使えます。さらに、ユーザ定義ファンクションもサポートされています。

イメージのタグに git sha を書き込むには ¶

bake はマッチした環境変数やデフォルト値を割り当てる、変数ブロックをサポートしています。

# docker-bake.hcl
variable "TAG" {
    default = "latest"
}

group "default" {
    targets = ["webapp"]
}

target "webapp" {
    tags = ["docker.io/username/webapp:${TAG}"]
}

$ docker buildx bake --print webapp
{
  "group": {
    "default": {
      "targets": [
        "webapp"
      ]
    }
  },
  "target": {
    "webapp": {
      "context": ".",
      "dockerfile": "Dockerfile",
      "tags": [
        "docker.io/username/webapp:latest"
      ]
    }
  }
}

$ TAG=$(git rev-parse --short HEAD) docker buildx bake --print webapp
{
  "group": {
    "default": {
      "targets": [
        "webapp"
      ]
    }
  },
  "target": {
    "webapp": {
      "context": ".",
      "dockerfile": "Dockerfile",
      "tags": [
        "docker.io/username/webapp:985e9e9"
      ]
    }
  }
}

`add` ファンクションを使う ¶

go-cty stdlib ファンクションを使えます。以下は add ファンクションを使っています。

# docker-bake.hcl
variable "TAG" {
    default = "latest"
}

group "default" {
    targets = ["webapp"]
}

target "webapp" {
    args = {
        buildno = "${add(123, 1)}"
    }
}

$ docker buildx bake --print webapp
{
  "group": {
    "default": {
      "targets": [
        "webapp"
      ]
    }
  },
  "target": {
    "webapp": {
      "context": ".",
      "dockerfile": "Dockerfile",
      "args": {
        "buildno": "124"
      }
    }
  }
}

`increment` ファンクションの定義 ¶

ユーザ定義ファンクションもサポートしています。以下の例はシンプルな increment ファンクションを定義する例です。

# docker-bake.hcl
function "increment" {
    params = [number]
    result = number + 1
}

group "default" {
    targets = ["webapp"]
}

target "webapp" {
    args = {
        buildno = "${increment(123)}"
    }
}

$ docker buildx bake --print webapp
{
  "group": {
    "default": {
      "targets": [
        "webapp"
      ]
    }
  },
  "target": {
    "webapp": {
      "context": ".",
      "dockerfile": "Dockerfile",
      "args": {
        "buildno": "124"
      }
    }
  }
}

変数が空でない場合のみ `notequal` を使ってタグを追加 ¶

以下は条件付きの notequal ファンクションを使い、 equal と同等の働きをします。

# docker-bake.hcl
variable "TAG" {default="" }

group "default" {
    targets = [
        "webapp",
    ]
}

target "webapp" {
    context="."
    dockerfile="Dockerfile"
    tags = [
        "my-image:latest",
        notequal("",TAG) ? "my-image:${TAG}": "",
    ]
}

$ docker buildx bake --print webapp
{
  "group": {
    "default": {
      "targets": [
        "webapp"
      ]
    }
  },
  "target": {
    "webapp": {
      "context": ".",
      "dockerfile": "Dockerfile",
      "tags": [
        "my-image:latest"
      ]
    }
  }
}

ファンクションで変数を使う ¶

他の変数をターゲット・ブロックにように扱い、変数を参照できます。stdlib ファンクションも呼び出せますが、その場合にユーザ・ファンクションは使えません。

# docker-bake.hcl
variable "REPO" {
    default = "user/repo"
}

function "tag" {
    params = [tag]
    result = ["${REPO}:${tag}"]
}

target "webapp" {
    tags = tag("v1")
}

{
  "group": {
    "default": {
      "targets": [
        "webapp"
      ]
    }
  },
  "target": {
    "webapp": {
      "context": ".",
      "dockerfile": "Dockerfile",
      "tags": [
        "user/repo:v1"
      ]
    }
  }
}

ファイルを横断して変数を使う ¶

複数のファイルを指定する場合は、あるファイル定義した変数が、別のファイルでも使えます。

# docker-bake1.hcl
variable "FOO" {
    default = upper("${BASE}def")
}

variable "BAR" {
    default = "-${FOO}-"
}

target "app" {
    args = {
        v1 = "pre-${BAR}"
    }
}

# docker-bake2.hcl
variable "BASE" {
    default = "abc"
}

target "app" {
    args = {
        v2 = "${FOO}-post"
    }
}

$ docker buildx bake -f docker-bake1.hcl -f docker-bake2.hcl --print app
{
  "group": {
    "default": {
      "targets": [
        "app"
      ]
    }
  },
  "target": {
    "app": {
      "context": ".",
      "dockerfile": "Dockerfile",
      "args": {
        "v1": "pre--ABCDEF-",
        "v2": "ABCDEF-post"
      }
    }
  }
}

typed 変数を使う ¶

文字列以外の変数も利用できます。この値は適切なタイプの env （環境変数）に渡されます。

# docker-bake.hcl
variable "FOO" {
    default = 3
}

variable "IS_FOO" {
    default = true
}

target "app" {
    args = {
        v1 = FOO > 5 ? "higher" : "lower"
        v2 = IS_FOO ? "yes" : "no"
    }
}

$ docker buildx bake --print app
{
  "group": {
    "default": {
      "targets": [
        "app"
      ]
    }
  },
  "target": {
    "app": {
      "context": ".",
      "dockerfile": "Dockerfile",
      "args": {
        "v1": "lower",
        "v2": "yes"
      }
    }
  }
}

Compose での拡張フィールド ¶

special extention フィールド x-bake は compose ファイルでフィールドとして使えますが、（まだ今は） build 定義では使えません。

# docker-compose.yml
services:
  addon:
    image: ct-addon:bar
    build:
      context: .
      dockerfile: ./Dockerfile
      args:
        CT_ECR: foo
        CT_TAG: bar
      x-bake:
        tags:
          - ct-addon:foo
          - ct-addon:alp
        platforms:
          - linux/amd64
          - linux/arm64
        cache-from:
          - user/app:cache
          - type=local,src=path/to/cache
        cache-to: type=local,dest=path/to/cache
        pull: true

  aws:
    image: ct-fake-aws:bar
    build:
      dockerfile: ./aws.Dockerfile
      args:
        CT_ECR: foo
        CT_TAG: bar
      x-bake:
        secret:
          - id=mysecret,src=./secret
          - id=mysecret2,src=./secret2
        platforms: linux/arm64
        output: type=docker
        no-cache: true

$ docker buildx bake --print
{
  "group": {
    "default": {
      "targets": [
        "aws",
        "addon"
      ]
    }
  },
  "target": {
    "addon": {
      "context": ".",
      "dockerfile": "./Dockerfile",
      "args": {
        "CT_ECR": "foo",
        "CT_TAG": "bar"
      },
      "tags": [
        "ct-addon:foo",
        "ct-addon:alp"
      ],
      "cache-from": [
        "user/app:cache",
        "type=local,src=path/to/cache"
      ],
      "cache-to": [
        "type=local,dest=path/to/cache"
      ],
      "platforms": [
        "linux/amd64",
        "linux/arm64"
      ],
      "pull": true
    },
    "aws": {
      "context": ".",
      "dockerfile": "./aws.Dockerfile",
      "args": {
        "CT_ECR": "foo",
        "CT_TAG": "bar"
      },
      "tags": [
        "ct-fake-aws:bar"
      ],
      "secret": [
        "id=mysecret,src=./secret",
        "id=mysecret2,src=./secret2"
      ],
      "platforms": [
        "linux/arm64"
      ],
      "output": [
        "type=docker"
      ],
      "no-cache": true
    }
  }
}

x-bake で有効なフィールドの全一覧：

tags , cache-from , cache-to , secret , ssh , platforms , output , pull , no-cache

内蔵している変数 ¶

BAKE_CMD_CONTEXT はリモートから読み込んだ bake ファイルから、メインの context （コンテクスト）に bake コマンドでアクセスできるようにします。
BAKE_LOCAL_PLATFORM は現在のプラットフォームとして指定されているデフォルトのプラットフォームを返します（例： linux/amd64 ）。

親コマンド ¶

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