[アップデート] AWS SAM CLI でコンテナイメージビルド時に BuildKit が使えるようになりました

[アップデート] AWS SAM CLI でコンテナイメージビルド時に BuildKit が使えるようになりました

2026.05.12

いわさです。

SAM CLI で Lambda 関数のパッケージタイプとしてコンテナイメージを選択した場合、sam build コマンドで Dockerfile からイメージをビルドすることが出来ます。

https://dev.classmethod.jp/articles/lambda-container-pkgfmt-with-sam-cli/

Docker のイメージビルドには Legacy builder と BuildKit の 2 つのビルドエンジンがあります。
BuildKit は Docker 18.09 で導入された次世代のビルドエンジンで、ビルドステップの並列実行やキャッシュの効率化など、Legacy builder に対して多くの改善が提供されています。

BuildKit is the builder backend used by Docker. BuildKit provides improved functionality and improves your builds' performance over the legacy builder used in earlier versions of Docker.

https://docs.docker.com/build/buildkit/

現在の Docker CLI では BuildKit がデフォルトですが、SAM CLI はこれまで Docker SDK 経由で Legacy builder を使ってビルドを行っていました。

By default, builds uses the legacy builder from the SDK.

https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-cli-command-reference-sam-build.html

今回のアップデートで、SAM CLI 1.159.0 以降に --use-buildkit フラグが追加され、Docker CLI(または Finch CLI)経由で BuildKit を使ったコンテナイメージビルドが可能になりました。

https://aws.amazon.com/about-aws/whats-new/2026/05/aws-sam-cli-buildkit-aws-lambda/

これにより、マルチステージビルドの最適化、キャッシュの効率化、ビルドステップの並列化、クロスアーキテクチャビルド、ビルド時のシークレット利用などが sam build でも活用出来るようになります。

今回こちらを確認してみたので紹介します。

実際に確認してみる

では早速 --use-buildkit フラグを使ってビルドしてみましょう。

https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-cli-command-reference-sam-build.html

SAM CLI のバージョン確認

まず SAM CLI のバージョンを確認します。
1.159.0 以上が必要です。

% sam --version
SAM CLI, version 1.159.1

サンプルプロジェクトの準備

今回は以下のようなマルチステージビルドの Dockerfile を用意してみました。
builder ステージで依存パッケージをインストールし、最終ステージにコピーするパターンです。

hello_world/Dockerfile
FROM public.ecr.aws/lambda/python:3.12 AS builder

COPY requirements.txt /tmp/
RUN pip install --target /tmp/deps -r /tmp/requirements.txt

FROM public.ecr.aws/lambda/python:3.12

COPY --from=builder /tmp/deps ${LAMBDA_TASK_ROOT}/
COPY app.py ${LAMBDA_TASK_ROOT}/

CMD ["app.lambda_handler"]
template.yaml
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31

Resources:
  HelloWorldFunction:
    Type: AWS::Serverless::Function
    Properties:
      PackageType: Image
      Architectures:
        - x86_64
    Metadata:
      DockerTag: python3.12-v1
      DockerContext: ./hello_world
      Dockerfile: Dockerfile

従来のビルダーでビルド

まず比較のために、従来の Legacy builder でビルドしてみます。

% sam build --no-use-buildkit
Building image for HelloWorldFunction function
Setting DockerBuildArgs for HelloWorldFunction function
Step 1/7 : FROM public.ecr.aws/lambda/python:3.12 AS builder
 ---> ceec420c0ff3
Step 2/7 : COPY requirements.txt /tmp/
 ---> 7abb3f927c67
Step 3/7 : RUN pip install --target /tmp/deps -r /tmp/requirements.txt
 ---> Running in 7f3def8d126c
...
Step 4/7 : FROM public.ecr.aws/lambda/python:3.12
 ---> ceec420c0ff3
Step 5/7 : COPY --from=builder /tmp/deps ${LAMBDA_TASK_ROOT}/
 ---> 2000febe5bbe
Step 6/7 : COPY app.py ${LAMBDA_TASK_ROOT}/
 ---> 6ad423c36888
Step 7/7 : CMD ["app.lambda_handler"]
 ---> Running in 72f1705d2622
Successfully built ff81d223976c
Successfully tagged helloworldfunction:python3.12-v1

Build Succeeded

従来のビルダーでは Step 1/7, Step 2/7... のように逐次的にステップが実行されます。

BuildKit でビルド

次に --use-buildkit フラグを付けてビルドしてみます。

% sam build --use-buildkit
Building image for HelloWorldFunction function
Setting DockerBuildArgs for HelloWorldFunction function
#0 building with "default" instance using docker driver

#1 [internal] load build definition from Dockerfile
#1 transferring dockerfile: 331B done
#1 DONE 0.0s

#2 [internal] load metadata for public.ecr.aws/lambda/python:3.12
#2 DONE 0.0s

#3 [internal] load .dockerignore
#3 transferring context: 2B done
#3 DONE 0.0s

#4 [builder 1/3] FROM public.ecr.aws/lambda/python:3.12
#4 CACHED

#5 [internal] load build context
#5 transferring context: 63B done
#5 DONE 0.0s

#6 [builder 2/3] COPY requirements.txt /tmp/
#6 DONE 0.0s

#7 [builder 3/3] RUN pip install --target /tmp/deps -r /tmp/requirements.txt
#7 2.535 Collecting requests (from -r /tmp/requirements.txt (line 1))
...
#7 DONE 6.4s

#8 [stage-1 2/3] COPY --from=builder /tmp/deps /var/task/
#8 DONE 0.0s

#9 [stage-1 3/3] COPY app.py /var/task/
#9 DONE 0.0s

#10 exporting to image
#10 exporting layers 0.0s done
#10 writing image sha256:8d99dbbe21f28a07fe3c4e2c9f3362008f5b0fa4c999078cc2ec969c149e7d9d done
#10 naming to docker.io/library/helloworldfunction:python3.12-v1 done
#10 DONE 0.0s

Build Succeeded

BuildKit の出力形式になっていることがわかります。
[builder 2/3], [stage-1 2/3] のようにステージ名が表示され、各ステップが並列に処理される様子が確認できます。

なお、公式ドキュメントによると --use-buildkit フラグはコンテナイメージビルド専用で、zip 関数を --use-container でビルドする場合には効果がないみたいです。

The --use-buildkit flag is for container image builds only. It will not have any effect for zip functions being built with --use-container.

https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/using-sam-cli-build.html

samconfig.toml での設定

公式ドキュメントによると、samconfig.tomluse_buildkit = true を設定しておくことで、毎回フラグを指定しなくても BuildKit を使うことが出来るみたいです。
--no-use-buildkit を指定すると設定を上書きして Legacy builder に戻せるとのこと。

By default, builds uses the legacy builder from the SDK. If the --no-use-buildkit option is invoked, it overrides the use-buildkit = true setting in samconfig.toml.

https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-cli-command-reference-sam-build.html

さいごに

本日は AWS SAM CLI にコンテナイメージビルド時の BuildKit サポートが追加されたので確認してみました。

--use-buildkit フラグを付けるだけで BuildKit が有効になり、マルチステージビルドやキャッシュの効率化、ビルドステップの並列化が使えるようになります。
コンテナイメージタイプの Lambda 関数を使っている場合は、ビルド時間の短縮が期待できそうです。

この記事をシェアする

関連記事