LocalStack 入門 !
AWS Lambda と Amazon S3 を組み合わせたサーバーレスアプリケーションを体験しよう
Author : 吉田 慶章
こんにちは ! 吉田慶章 (カック) です。趣味はテックブログを書くことです。普段はソフトウェアエンジニアとして働いています。
LocalStack とは
皆さんは LocalStack をご存知でしょうか。LocalStack はローカル環境や CI 環境で実行できる AWS エミュレーターです。現在、100 種類以上の AWS サービスをサポートしていて *1、無料で使える LocalStack Community Edition でも、よく使う主要な AWS サービスはサポートされています。また、非商用であればすべての AWS サービスがサポートされた Hobby プランも選択できます。
LocalStack は、AWS の公式ドキュメントにも登場します。たとえば LocalStack と Terraform を組み合わせた AWS Prescriptive Guidance や、LocalStack と AWS Cloud Development Kit (AWS CDK) を組み合わせた GitHub リポジトリもあります。また、2024 年 11 月に発表された AWS Step Functions の新機能 JSONata 構文の リリース記事 では、LocalStack 上の AWS Step Functions でも JSONata 構文が同時に使えるようになったというアナウンスが出ていたことも記憶に新しいのではないでしょうか。
LocalStack を使うのは簡単です。LocalStack はデフォルトで http://localhost:4566 に起動されるため、たとえば AWS CLI であれば --endpoint-url オプションを指定するだけです👌 簡単に表現すると、皆さんのラップトップ上に AWS をデプロイできるようなイメージでしょうか。
$ aws --endpoint-url=http://localhost:4566 s3 ls*1 Emulating 100+ AWS Services を引用
LocalStack のユースケース
LocalStack にはさまざまなユースケースがあります。代表的なものとして「アプリケーションのローカル環境として」や「JUnit / pytest などを実行するテスト環境として」、そして「Terraform / AWS CDK / AWS Serverless Application Model (AWS SAM) / AWS CloudFormation などの Infrastructure as Code (IaC) 動作確認環境として」が挙げられます。私自身は、特に「テスト環境として」LocalStack を活用することが多いです。
また、別のユースケースとして「サンドボックス環境として」LocalStack を活用することもできます。AWS を学ぶときに、個人の AWS アカウントを使ったり、会社から貸与されている検証アカウントを使ったりすると思いますが、設定ミスやリソースの消し忘れによる思わぬ課金が発生してしまう不安や設定ミスによってセキュリティ事故が起きてしまう不安があるのではないでしょうか。
LocalStack であれば、設定ミスをしても課金されることはありません。何度でも試行錯誤できます。特に本記事は「How to be a Developer」という初学者向けのカテゴリに寄稿しているため、「早く LocalStack を試してみたくなった !」と思ってもらえるのではないでしょうか。
私自身は 2023 年まで AWS を教えるテクニカルインストラクターとして働いていたため、特にこれから AWS を学びたいという初学者の皆さんからこういった不安に対する相談を受けていました。そして、もう一つよくある相談としては、AWS Identity and Access Management (IAM) の難しさです。もちろん IAM は AWS の根幹とも言える重要なサービスですが、AWS を学び始めたときに IAM 関連のエラーでつまづいてしまうと挫折しやすいという側面もあります。LocalStack では基本的に IAM の制御を考慮せずに使うことができ *2、簡単に AWS サービス同士を連携できるというメリット (学びやすさ) もあります。
💡もちろん LocalStack は AWS エミュレーターで、100% の互換性があるわけではありません。そのため、実際に AWS アカウントにデプロイした後にも最終確認が必要になり、このプロセスが「二度手間」に感じられる方もいると思います。 AWS Service Feature Coverage というドキュメントがあり、カバレッジレベルが公開されています。もし挙動が異なる機能があれば、積極的に Issues · localstack/localstack から報告しましょう。私も報告したことがあります。ぜひ LocalStack を検証してみて、導入するメリットがあるかどうかをチームでディスカッションしてみることをおすすめします。
LocalStack を試そう
さて、ここからは実際に LocalStack を体験してみましょう。テーマとしては、AWS でも LocalStack でも実行できることを前提にするため、AWS 公式で提供されているチュートリアル「サーバーレスアプリケーション “file-processing-python”」を使います。以下のドキュメントに載っています。
サーバーレスファイル処理アプリケーションを作成する - AWS Lambda »
1. 概要
このチュートリアルでは、Amazon Simple Storage Service (Amazon S3) バケットに PDF ファイルをアップロードすると、自動的に PDF ファイルにパスワードを設定して、また別の Amazon S3 バケットにアップロードされるというサーバーレスアプリケーションです。アーキテクチャ図をドキュメントから引用しました。
ドキュメントでは、マネジメントコンソールを使ってデプロイする手順と、AWS SAM を使ってデプロイする手順が紹介されていますが、今回は AWS SAM を使います。LocalStack は AWS CloudFormation をサポートしているため、AWS SAM もサポートしています。なお、チュートリアルで使うコードは GitHub リポジトリ awsdocs/aws-lambda-developer-guide に公開されています。
2. 環境
私は以下の環境で動作確認をしています。
3. 準備
まず最初に、GitHub リポジトリをクローンします。
$ git clone https://github.com/awsdocs/aws-lambda-developer-guide.git
$ cd aws-lambda-developer-guide/sample-apps/file-processing-python次に LocalStack CLI を使って LocalStack を起動します。
$ localstack start -dそして、template.yaml を開き、以下のように Amazon S3 バケット名のプレースホルダを置き換えます。
| 行数 | Before | After |
| 29 | EXAMPLE-BUCKET | pdf-files |
| 34 | EXAMPLE-BUCKET-encrypted | pdf-files-encrypted |
さらに、aws configure コマンドで認証情報のセットアップをします。LocalStack ではアクセスキーは使わないため、DUMMY で大丈夫です。リージョンは東京リージョンにしておきます。
$ aws configure --profile localstack
AWS Access Key ID [None]: DUMMY
AWS Secret Access Key [None]: DUMMY
Default region name [None]: ap-northeast-1
Default output format [None]: json4. デプロイ
さっそく AWS SAM CLI でデプロイしましょう。今回は AWS_ENDPOINT_URL 環境変数に LocalStack を指定しています。インタラクティブに入力を求められる部分は、Stack Name に file-processing-python と入力する以外はデフォルトのまま Enter を押して大丈夫です👌最終的に Successfully created/updated stack - file-processing-python in ap-northeast-1 と表示されていればデプロイ完了です。
$ export AWS_PROFILE=localstack
$ export AWS_ENDPOINT_URL=http://localhost:4566
$ sam build
$ sam deploy --guided
Configuring SAM deploy
======================
Looking for config file [samconfig.toml] : Not found
Setting default arguments for 'sam deploy'
=========================================
Stack Name [sam-app]: file-processing-python
AWS Region [ap-northeast-1]:
#Shows you resources changes to be deployed and require a 'Y' to initiate deploy
Confirm changes before deploy [y/N]:
#SAM needs permission to be able to create roles to connect to the resources in your template
Allow SAM CLI IAM role creation [Y/n]:
#Preserves the state of previously provisioned resources when an operation fails
Disable rollback [y/N]:
Save arguments to configuration file [Y/n]:
SAM configuration file [samconfig.toml]:
SAM configuration environment [default]:
（中略）
Successfully created/updated stack - file-processing-python in ap-northeast-15. デプロイ確認
もうデプロイ完了 ? と思われたかもしれません ! そうなんです😀 AWS SAM CLI で AWS にサーバーレスアプリケーションをデプロイするのと同じ体験で LocalStack にデプロイできています。さっそく AWS リソースを確認していきましょう。
まずは Amazon S3 バケットです。aws s3 ls コマンドを使って確認します。すると、期待通りに Amazon S3 バケット pdf-files と Amazon S3 バケット pdf-files-encrypted がデプロイされています。
$ aws --endpoint-url=http://localhost:4566 s3 ls
2025-03-23 17:00:13 aws-sam-cli-managed-default-samclisourcebucket-94fd1396
2025-03-23 17:00:30 pdf-files-encrypted
2025-03-23 17:00:35 pdf-files次に AWS Lambda 関数です。aws lambda list-functions コマンドを使って確認します。すると、期待通りに AWS Lambda 関数 EncryptPDF がデプロイされています。なお、LocalStack ではアカウント ID は 000000000000 になります。
$ aws --endpoint-url=http://localhost:4566 lambda list-functions --query "Functions[0].{FunctionName: FunctionName, FunctionArn: FunctionArn}"
{
"FunctionName": "EncryptPDF",
"FunctionArn": "arn:aws:lambda:ap-northeast-1:000000000000:function:EncryptPDF"
}6. 動作確認
では、LocalStack にデプロイしたサーバーレスアプリケーションの動作確認をしてみましょう。
今回は Amazon Web Services の概要 - AWS ホワイトペーパー (aws-overview.pdf) を使うため、今いるディレクトリにダウンロードします。
$ curl -O https://docs.aws.amazon.com/ja_jp/whitepapers/latest/aws-overview/aws-overview.pdfそして、Amazon S3 バケット pdf-files にアップロードします。
$ aws --endpoint-url=http://localhost:4566 s3api put-object --bucket pdf-files --key aws-overview.pdf --body ./aws-overview.pdf
{
"ETag": "\"1636fff6d13cf64518ce916ad03cc2f5\"",
"ServerSideEncryption": "AES256"
}念のため、アップロードしたファイルを確認しておきましょう。
$ aws --endpoint-url=http://localhost:4566 s3api list-objects-v2 --bucket pdf-files --query "Contents[0].{Key: Key}"
{
"Key": "aws-overview.pdf"
}今回のサーバーレスアプリケーションでは、Amazon S3 バケット pdf-files に PDF ファイルをアップロードすると、自動的に Amazon S3 バケット pdf-files-encrypted にアップロードされる仕組みになっています。Amazon S3 バケット pdf-files-encrypted のオブジェクトを確認すると、期待通りに PDF ファイルがアップロードされているはずです。
$ aws --endpoint-url=http://localhost:4566 s3api list-objects-v2 --bucket pdf-files-encrypted --query "Contents[0].{Key: Key}"
{
"Key": "aws-overview_encrypted.pdf"
}PDF ファイルをダウンロードしてみましょう。
$ aws --endpoint-url=http://localhost:4566 s3api get-object --bucket pdf-files-encrypted --key aws-overview_encrypted.pdf aws-overview_encrypted.pdfおめでとうございます ! 期待通りに PDF にパスワードが設定されています。設定されているパスワードは lambda_function.py に実装されている my-secret-password です。このように、LocalStack でチュートリアルを進めることができました😀
付録
LocalStack AWS CLI と LocalStack AWS SAM CLI
今回は LocalStack を使っていることを意識しやすいように、AWS CLI を実行するときに --endpoint-url=http://localhost:4566 というオプションを付けていましたが、少し長くなってしまいます。また、AWS SAM CLI を実行するときには AWS_ENDPOINT_URL=http://localhost:4566 環境変数を設定していました。LocalStack は、エンドポイントの指定を暗黙的に行う LocalStack AWS CLI (awslocal コマンド) と LocalStack AWS SAM CLI (samlocal コマンド) を提供しています。他にも LocalStack Terraform CLI (tflocal コマンド) もあります。
以下のように実行できてシンプルです。私はいつも使っています😀
$ awslocal s3 ls
$ samlocal build
$ samlocal deployLocalStack Resource Browser
LocalStack には、Resource Browser という機能もあります。AWS マネジメントコンソールとは機能もデザインも異なりますが、LocalStack にデプロイしたリソースの確認や操作などを行えます。Amazon S3 バケットを確認したり、Amazon S3 バケットのオブジェクトをダウンロードすることもできます。
まとめ
今回の記事では、LocalStack の紹介と LocalStack を実際に体験するために、AWS 公式で提供されているチュートリアル「サーバーレスアプリケーション “file-processing-python”」を動かしてみました。LocalStack にはさまざまなユースケースがあります。ぜひ試してみてください😀
そして、私は LocalStack をさらに活用するための実践的な入門書をいくつか公開しています。もし今回の記事を読んで LocalStack に興味を持ってもらえたら、こちらもぜひあわせて読んでみてください。
謝辞
本記事のレビューは AWS テクニカルインストラクターの杉本圭太さんにお願いしました。ありがとうございました。
筆者プロフィール
吉田 慶章 (カック @kakakakakku)
ソフトウェアエンジニア／AWS Community Builders 2025 (Serverless)／趣味は毎週テックブログを書くこと
AWS を無料でお試しいただけます