Docker Buildx Bake入門:複数イメージの自動化と並行ビルド実践ガイド

Docker tutorial - IT technology blog
Docker tutorial - IT technology blog

複数Dockerイメージビルドにおける課題

プロジェクトがモノリスからマイクロサービスへ分割されるにつれて、Dockerfileの数は急速に増加します。その結果、イメージのパッケージング工程が大きなボトルネックになり始めます。docker build コマンドが順次実行されることでCI/CDランナーは何十分も待たされることになります。さらに、大量のbuild-argsの管理、バージョンのタグ付け、マルチアーキテクチャ(multi-arch)マトリックスの手動設定はミスが頻発しやすい作業です。

実際のエンジニアリングチームでは、主に次の3つのアプローチがよく見られます:

  • アプローチ1:Bashスクリプトまたはバックグラウンドジョブ(&)の利用 — 各ディレクトリをループで回してビルドコマンドを実行する。
  • アプローチ2:docker compose build の活用 — ビルド設定のすべてを docker-compose.yml に集約する。
  • アプローチ3:Docker Buildx Bake の導入 — BuildKit公式ツールを使い、HCLファイルでターゲットを宣言して並行処理とレイヤーキャッシュの完全な再利用を実現する。

3つのアプローチの実践比較

1. Bashスクリプト / Makefile

スクリプト作成は慣れ親しんでおり、新しい構文を学ぶ必要がないため、多くの開発者が最初にとるアプローチです。

  • メリット: 基本的なDocker CLIさえあれば、どのサーバーでもすぐに実行可能。
  • デメリット: 独立したステージ間でキャッシュを共有できない。順次実行すると時間がかかり、& と wait で無理にバックグラウンド実行するとCPUやRAMを食いつぶしてしまう。その上、エラーログの集約も非常に複雑になる。

2. Docker Compose Build

ローカル開発環境に既に設定ファイルが存在するため、多くのチームがそのままComposeを活用します。

  • メリット: 手軽で、新しい設定ファイルを追加作成する必要がない。最近のComposeバージョンでは parallel フラグもサポートされている。
  • デメリット: Composeはもともとコンテナのランタイム管理(ネットワーク、ボリューム、再起動ポリシーなど)のために設計されている。マルチプラットフォームビルド(amd64とarm64の組み合わせ)、ターゲットの継承、AWS ECRやGitHub Packagesなどのリモートレジストリへのキャッシュ保存といった高度な機能が必要になると、限界が浮き彫りになる。

3. Docker Buildx Bake

Buildx Bakeは、有向非巡回グラフ(DAG: Directed Acyclic Graph)モデルに基づいてビルドの依存関係を解決します。

  • メリット: BuildKitエンジンが独立した部分を自動的に計算して並行ビルドを行い、CPUコアを最大限に活用できる。HCL構文は直感的で、ターゲットのグループ化、共通設定の継承、そして1つのコマンドでレジストリへ一括プッシュすることが可能。
  • デメリット: チームがBakeのHCLまたはJSON構文に慣れるための学習コストが多少かかる。

Bake導入による実際の効果

リポジトリにサービスが1つしかない場合は、通常の docker build で十分です。しかし、サービス数が3〜4個以上に達すると、Bakeは圧倒的な違いを生み出します。

8つのマイクロサービス(Golangバックエンド、Next.jsフロントエンド、各種ワーカー)で構成されるプロジェクトでは、当初GitHub Actionsの実行に16分以上かかっていました。これを docker-bake.hcl と docker-container ドライバーの組み合わせに移行したところ、ビルド時間が4分30秒にまで短縮されました。これにより、ランナーの月間コストを60%以上削減することに成功しました。

Docker Buildx Bakeのステップバイステップ構築手順

ステップ1:Builderインスタンスの準備

Docker Desktopには現在Buildxが標準で同梱されています。ただし、デフォルトのbuilderは制約の多い docker ドライバーを使用しています。並行ビルドやリモートキャッシュの全機能を有効化するために、docker-container ドライバーを使用する新しいbuilderを作成しましょう:

# 現在のbuildxバージョンを確認
docker buildx version

# 新しいbuilderインスタンスを作成してデフォルトに設定
docker buildx create --name bake-builder --driver docker-container --use

# builderを起動して確認
docker buildx inspect --bootstrap

ステップ2:ディレクトリ構成の準備

バックエンド(Golang)とフロントエンド(Node.js)で構成される一般的なプロジェクト構成を考えます:

my-project/
├── backend/
│   └── Dockerfile
├── frontend/
│   └── Dockerfile
└── docker-bake.hcl

ステップ3:docker-bake.hcl設定ファイルの作成

リポジトリのルートディレクトリに docker-bake.hcl を作成します:

# フォールバック値を含むグローバル変数の定義
variable "TAG" {
  default = "latest"
}

variable "REGISTRY" {
  default = "myregistry.local/app"
}

# 共通設定を保持するベースターゲット
target "common" {
  platforms = ["linux/amd64"]
  args = {
    BUILD_ENV = "production"
  }
}

# commonから全設定を継承するバックエンドターゲット
target "api" {
  inherits   = ["common"]
  context    = "./backend"
  dockerfile = "Dockerfile"
  tags       = ["${REGISTRY}-api:${TAG}"]
}

# commonから継承するフロントエンドターゲット
target "web" {
  inherits   = ["common"]
  context    = "./frontend"
  dockerfile = "Dockerfile"
  tags       = ["${REGISTRY}-web:${TAG}"]
}

# 両方のサービスをまとめるデフォルトグループ
group "default" {
  targets = ["api", "web"]
}

ステップ4:ワンコマンドでのビルド実行

ルートディレクトリで以下のコマンドを実行するだけです:

docker buildx bake

BuildKitが直ちに依存関係ツリーを解析します。両サービスのベースレイヤーとソースコードの取得・コンパイルが並行して実行されます。CLI画面にはターゲットごとのプログレスバーが個別に表示され、ログが混ざって埋もれることもありません。

ステップ5:パラメータの柔軟なオーバーライド

環境変数を渡したり、デバッグ時に特定のターゲットのみを指定してビルドしたりすることも容易です:

# バージョンv1.2.0のAPIサービスのみをビルド
TAG=v1.2.0 docker buildx bake api

# ビルドと同時にコンテナレジストリへ直接プッシュ
docker buildx bake --push

ステップ6:リモートキャッシュによるCI/CDの高速化

CI/CDにおいてBakeの最も価値ある特徴は、集中キャッシュ管理機能にあります。次のように common ターゲットに追加定義するだけです:

target "common" {
  platforms  = ["linux/amd64"]
  cache-from = ["type=registry,ref=${REGISTRY}-cache:common"]
  cache-to   = ["type=registry,ref=${REGISTRY}-cache:common,mode=max"]
}

この設定により、npm install や go mod download などの変更がないレイヤーはレジストリから直接取得されます。以降のコミットでは、ランナーがわずか20〜30秒でビルド処理を完了できるようになります。

まとめ

Docker Buildx Bakeは、単に肥大化したシェルスクリプトを置き換えるだけのものではありません。CI/CDパイプラインに標準化と圧倒的な高速化をもたらします。マイクロサービスやモノレポを採用しているプロジェクトであれば、早い段階から docker-bake.hcl の設定に投資することで、毎日のビルド待ち時間を大幅に削減できるはずです。

Share: