developersIO
[アップデート]AWS SAM CLIがFinchをサポートしました

[アップデート]AWS SAM CLIがFinchをサポートしました

AWS SAM CLIDockerfinchAWS
FacebookHatena blogX
2025.11.13

初めに

従来AWS SAM CLIでローカル実行・ビルド等各種操作でコンテナを利用する場合はDockerのみをサポートしFinchは未対応となっていたのですが、先月のアップデートでめでたく正式にサポートという形になりました。
対応バージョンはv1.145.0からとなります。

https://aws.amazon.com/jp/about-aws/whats-new/2025/10/aws-sam-cli-finch-support/

https://github.com/aws/aws-sam-cli/releases/tag/v1.145.0

ここでは詳細は割愛しますがFinchはAWSが開発元となっているコンテナランタイムとなります。Macのネイティブ対応もありDocker Desktopの企業利用が有償化した少し後にリリースされた流れで触った人も多いのではないでしょうか。

https://aws.amazon.com/jp/blogs/news/introducing-finch-an-open-source-client-for-container-development/

https://dev.classmethod.jp/articles/building-containers-for-aws-reinvent-2022/

このアップデート以前でははAWS SAM CLIではコンテナソケットを/var/run/docker.sockを固定で利用している、コンテナ周りの操作のためにdockerライブラリを利用する等Dockerの仕様に強く依存する形という形になっていましたが、今回のアップデートでこの辺りが抽象・汎用化されどちらも利用できる形となります。

https://github.com/aws/aws-sam-cli/pull/8285

※ と言いつつ実のところFinchとDockerではAPI含めほとんどの部分に互換性があり、v1.145.0以前でも実行時にDOCKER_HOSTでFinchのソケットを指定すると動くには動いたみたいですが、完全互換ではないので特定のケースでうまくハンドリングできない固有の問題に対処した形になります。

## 以前のバージョンでも動くには動く
 % /tmp/venv/bin/sam --version
SAM CLI, version 1.140.0

% DOCKER_HOST='unix://Applications/Finch/lima/data/finch/sock/finch.sock' /tmp/venv/bin/sam local invoke
/private/tmp/venv/lib/python3.14/site-packages/samtranslator/compat.py:2: UserWarning: Core Pydantic V1 functionality isn't compatible with Python 3.14 or greater.
  from pydantic import v1 as pydantic
Invoking app.lambda_handler (python3.12)
Local image was not found.
Removing rapid images for repo public.ecr.aws/sam/emulation-python3.12
Building image.........
Using local image: public.ecr.aws/lambda/python:3.12-rapid-arm64.

Mounting /Users/xxx/sam-app/.aws-sam/build/HelloWorldFunction as /var/task:ro,delegated, inside runtime container
START RequestId: 377b7835-df5a-45e3-ab40-a42d870c33ce Version: $LATEST
END RequestId: 54b92cd0-aaa6-46ab-9376-7fe403972d7f
REPORT RequestId: 54b92cd0-aaa6-46ab-9376-7fe403972d7f	Init Duration: 0.03 ms	Duration: 39.34 ms	Billed Duration: 40 ms	Memory Size: 256 MB	Max Memory Used: 256 MB
{"statusCode": 200, "body": "body_data"}

使ってみる

Finchのインストールはmacの場合はbrewからインストールが可能ですのでこちらからインストールしておきます。

https://runfinch.com/docs/managing-finch/macos/installation/

AWS SAM CLIの利用については特に意識することなくFinchを起動しておけば勝手に使われるだけであまり書くことがない...というのも寂しいので少し起動判定について触れておこうと思います。

なお今回環境としてはMacOSを利用しています。参照先パスなど一部OSにより異なる部分もありますのでご注意ください。

起動の優先順位について

さて、AWS SAM CLIがFinchを使うかDockerを利用するかについてですが、内部的には実際にソケットパスにアクセスできるかを都度確認して判定しています。

この判定についても順序があり以下のように判定されます。そのためDockerとFinchが両方起動している場合はDockerを優先して利用します。

  1. システム管理側で指定される種別(docker or finch)の起動判定
    • Macの場合/Library/Preferences/com.amazon.samcli.plist
    • この判定によるパスが決定した場合は2,3は行われない(実動作を見る限り)
  2. Dockerの起動判定(デフォルト: unix://var/run/docker.sock)
    • DOCKER_HOSTを指定する場合は代わりにそのパス
  3. Finchの起動判定(Macの場合は: unix:////Applications/Finch/lima/data/finch/sock/finch.sock)

https://github.com/aws/aws-sam-cli/blob/f0b3e6a1984ea16298ecab74a253584d216648ba/samcli/local/docker/container_client_factory.py#L35-L45

常にDockerとFinchを両方起動してるけどSAMでは基本Finchを使いたいという場合は以下のような形でFinchを優先起動するようにシステム設定ファイル(plistファイル)に書き込んでおくとこちらが最優先で利用されるようになります。

% sudo /usr/libexec/PlistBuddy -c "Add :DefaultContainerRuntime string finch" /Library/Preferences/com.amazon.samcli.plist

この辺りの優先順位の指定やplistを利用した最優先パスの指定については以下ドキュメントにも記載があるのでこちらをご参照ください。

https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-finch.html#install-finch-configuration

動作確認

まずはDocker(Rancher Desktop経由で起動)とFinch両方が実行されている状態にして起動してみます。


% docker ps
CONTAINER ID   IMAGE                        COMMAND                   CREATED          STATUS          PORTS     NAMES
930c1cc522c7   b41714cf6249                 "local-path-provisio…"   44 minutes ago   Up 44 minutes             k8s_local-path-provisioner_local-path-provisioner-774c6665dc-dsj8d_kube-system_4e6e33bb-3ce0-4a27-acf0-a43eea50b572_13
...

%  finch ps
CONTAINER ID    IMAGE    COMMAND    CREATED    STATUS    PORTS    NAMES

この状態でsam local invokeを実行してみると先に記載している通りDocker側で起動が行われます。

特に何も設定していなければplistファイルは存在せずAdmin preference: noneとなります。

% sam local invoke --debug
...
2025-11-12 20:11:03,960 | Admin preference: None
2025-11-12 20:11:03,961 | Using auto-detected client creation
2025-11-12 20:11:03,961 | Trying Docker client creation
2025-11-12 20:11:03,962 | Creating Docker container client from environment variable.
2025-11-12 20:11:03,962 | Creating container client with parameters: {'version': '1.35'}
2025-11-12 20:11:03,964 | DockerContainerClient created successfully
2025-11-12 20:11:03,968 | Using Docker as Container Engine.

Docker側を停止、Finchのみとした場合はどうでしょうか。

Docker側のソケットパスが表示されないのでわかりづらいですが({'version': '1.35'}の部分)がDockerのチェック部分となり、こちらに接続が失敗してるのでそのフォールバックとしてFinch利用される形になります。

この関係でFinchを起動する場合でもDocker起動のチェック分のオーバーヘッドはあるのですが、ログを見る限り数十ミリ秒とかの世界なので通常はあまり気にならないと思います。

% sam local invoke --debug
...
2025-11-12 20:13:04,479 | Admin preference: None
2025-11-12 20:13:04,479 | Using auto-detected client creation
2025-11-12 20:13:04,480 | Trying Docker client creation
2025-11-12 20:13:04,480 | Creating Docker container client from environment variable.
2025-11-12 20:13:04,480 | Creating container client with parameters: {'version': '1.35'}
2025-11-12 20:13:04,481 | DockerContainerClient created successfully
2025-11-12 20:13:04,482 | Container daemon availability check failed: ('Connection aborted.', FileNotFoundError(2, 'No such file or directory'))
2025-11-12 20:13:04,482 | Docker client not created, trying creating Finch client.
2025-11-12 20:13:04,482 | Creating Finch container client with base_url=unix:////Applications/Finch/lima/data/finch/sock/finch.sock
2025-11-12 20:13:04,483 | Creating container client with parameters: {'base_url': 'unix:////Applications/Finch/lima/data/finch/sock/finch.sock', 'version': '1.35'}
2025-11-12 20:13:04,483 | FinchContainerClient created successfully
2025-11-12 20:13:04,519 | Using Finch as Container Engine.
2025-11-12 20:13:04,520 | Set global container socket path: container_socket_path=unix:////Applications/Finch/lima/data/finch/sock/finch.sock
2025-11-12 20:13:04,521 | ContainerClientFactory.create_client() called

DOCKER_HOSTを指定した場合はあくまでDockerのソケットパスを代替的に指定する形になるのでステップが増えるというよりは2.のステップの探索先が変わるだけとなります。

% DOCKER_HOST='unix://var/run/dummy' sam local invoke --debug
...
2025-11-12 20:33:41,714 | Using auto-detected client creation
2025-11-12 20:33:41,714 | Trying Docker client creation
2025-11-12 20:33:41,714 | Creating Docker container client with base_url=unix://var/run/dummy.
2025-11-12 20:33:41,715 | Creating container client with parameters: {'base_url': 'unix://var/run/dummy', 'version': '1.35'}
2025-11-12 20:33:41,715 | DockerContainerClient created successfully
2025-11-12 20:33:41,716 | Container daemon availability check failed: ('Connection aborted.', FileNotFoundError(2, 'No such file or directory'))
2025-11-12 20:33:41,716 | Docker client not created, trying creating Finch client.
2025-11-12 20:33:41,717 | Creating Finch container client with base_url=unix:////Applications/Finch/lima/data/finch/sock/finch.sock
2025-11-12 20:33:41,717 | Creating container client with parameters: {'base_url': 'unix:////Applications/Finch/lima/data/finch/sock/finch.sock', 'version': '1.35'}
2025-11-12 20:33:41,717 | FinchContainerClient created successfully
2025-11-12 20:33:41,719 | Using Finch as Container Engine.

DOCKER_HOSTでFinchのソケットパスを指定し起動することも可能ですが、内部的にはDocker用のクライアントクラスとFinch用のクライアントクラスで分かれており、DOCKER_HOST指定のパスが利用される場合はDocker側のクライアントクラスが使われ互換問題が発生する可能性があるので避けた方が良さそうです。

https://github.com/aws/aws-sam-cli/blob/f0b3e6a1984ea16298ecab74a253584d216648ba/samcli/local/docker/container_client_factory.py#L124-L138

そのためFinchを最優先で起動したい場合は前述のplistファイルを利用する形にしておきましょう。

ただし現段階ではこの方法を利用して起動した場合かつFinchが起動していない場合は、Dockerでの起動にフォールバックされず実行に失敗する形になりますので注意が必要です。
(falling back to DOCKER_HOST detection: unix://var/run/docker.sockとは出るのですがv1.145.0現時点での実動作的にはフォールバックは確認できていません)

% sudo /usr/libexec/PlistBuddy -c "Add :DefaultContainerRuntime string finch" /Library/Preferences/com.amazon.samcli.plist
...

% cat /Library/Preferences/com.amazon.samcli.plist
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>DefaultContainerRuntime</key>
	<string>finch</string>
</dict>
</plist>

## Finchを未起動、Dockerを起動状態にしておく
 % finch ps
FATA[0000] instance "finch" is stopped, run `finch vm start` to start the instance
% docker ps
CONTAINER ID   IMAGE                        COMMAND                   CREATED          STATUS          PORTS     NAMES
...

%  DOCKER_HOST='unix://var/run/docker.sock' sam local invoke --debug
...
2025-11-13 12:04:53,124 | Set global container runtime info: admin_preference=finch
2025-11-13 12:04:53,124 | Stored admin container preference in global storage: finch
2025-11-13 12:04:53,125 | Admin preference: finch
2025-11-13 12:04:53,125 | Using enforced client creation
2025-11-13 12:04:53,125 | Creating Finch container client with base_url=unix:////Applications/Finch/lima/data/finch/sock/finch.sock
2025-11-13 12:04:53,125 | Creating container client with parameters: {'base_url': 'unix:////Applications/Finch/lima/data/finch/sock/finch.sock', 'version': '1.35'}
2025-11-13 12:04:53,126 | FinchContainerClient created successfully
2025-11-13 12:04:53,127 | Container daemon availability check failed: ('Connection aborted.', FileNotFoundError(2, 'No such file or directory'))
2025-11-13 12:04:53,127 | Telemetry endpoint configured to be https://aws-serverless-tools-telemetry.us-west-2.amazonaws.com/metrics
2025-11-13 12:04:53,176 | No container socket path in global storage, falling back to DOCKER_HOST detection: unix://var/run/docker.sock
2025-11-13 12:04:53,177 | Telemetry endpoint configured to be https://aws-serverless-tools-telemetry.us-west-2.amazonaws.com/metrics
2025-11-13 12:04:53,178 | Unable to find Click Context for getting session_id.
...
Error: Running AWS SAM projects locally requires Finch. Do you have Finch installed and running?

終わりに

Finchを利用してAWS SAM CLIを実行してみました。

Finch自体も今回の検証で初めて触ってみたのですが、検証しているとFinchなんか起動早いな...という感覚ではあるので結構良さそうです。

ユーザ側で設定すべきところもDockerと併用する場合にシステム設定を最初に入れるほどで、sudoを実行できる権限は必要なもののそこまで負荷なく入れられ速度向上による開発体験の向上にもつながるので試しても良いのではないでしょうか。

この記事をシェアする

FacebookHatena blogX

関連記事

SAM CLI 最新版を使って Python 3.14 の Lambda 関数を作成できるか確認してみた
いわさ
2025.11.10
AWS Lambdaのイベントソースマッピングのフィルタリング条件とZipデプロイパッケージがカスタマーマネージドキーによる暗号化に対応していたのでAWS SAMで実装してみた
じゅんや
2025.03.26
SAM Local Invoke は Lambda の環境変数に設定された Ref を認識できないため env.json を自動生成して samcofig.yaml で参照してみた
たかくに
2025.02.08
Python3.12 のスタンドアロン Lambda 関数を作成しつつ、SAM CLIを学んでみた
なかた
2024.11.08