--- title: "AWS Emulatorとは：ローカルでAWS APIを動かす手順とLocalStackとの違い" url: "https://www.issoh.co.jp/tech/details/19653/" published: 2026-11-12 updated: 2026-11-12 categories: ["インフラ・クラウド"] publisher: "株式会社一創" --- # AWS Emulatorとは：ローカルでAWS APIを動かす手順とLocalStackとの違い AWS Emulatorは、AWSが2026年11月11日に一般提供を始めたローカル用のエミュレーターです。手元のPCやCIのジョブで127.0.0.1の9297番ポートを開き、AWS CLIやAWS SDKのリクエストをAWSの代わりに受け取ります。この記事では、LinuxパッケージとDockerでの起動手順、SDKの向け先を環境変数で切り替える設定、GitHub Actionsで統合テストを回す構成例を、公式ドキュメントの記述に沿ってまとめました。後半では忠実度スコアの読み方とIAMポリシーを評価しない制約、LocalStackやmotoと比べたときの採用条件まで判断を示します。 ## まとめ：AWS Emulatorを開発とCIに入れる条件と実AWSで確かめる範囲 S3・DynamoDB・SQSなどを呼ぶアプリの統合テストを、AWSアカウントも課金も無しで回したいチームには、まず試す価値があります。エミュレーター自体に追加料金はかからず、商用の受託開発でもライセンス費用が発生しません。LocalStackのHobbyプランが非商用限定になった現在、無償で使える公式の選択肢が増えた意味は小さくありません。 ただし、権限の検証には使えません。AWS EmulatorはIAMポリシーとリソースベースポリシーをAWSと同じようには評価しないと公式に明記しています。権限エラーの再現、クロスアカウント構成、リージョンごとの差分は、実AWSの検証アカウントで確かめる前提で組み合わせます。 導入前に見るべき数字は、使うサービスの忠実度スコアです。リリースごとにサービス単位の合格数が公開されるので、自分のプロジェクトが呼ぶAPIの合否を先に確認してから、CIへ組み込む順番が安全です。 ## AWS EmulatorがAWS APIをローカルの9297番ポートで受ける仕組み AWS Emulatorは画面を持たないコマンドラインのプログラムで、起動するとAWS APIと同じ形のHTTPSエンドポイントを手元に立てます。リクエストはAWSへ送られず、作ったリソースはエミュレーターのメモリ上に保持されます。 ### Rust製・追加料金なしでGitHubに公開された公式エミュレーターの位置づけ 発表した[AWS News Blogの記事](https://aws.amazon.com/blogs/aws/test-your-applications-against-aws-locally-with-aws-emulator/)によると、実装言語はRustで、ソースコードはGitHubで公開されています。[aws/aws-emulatorリポジトリ](https://github.com/aws/aws-emulator)のライセンス表記はCC0-1.0で、同梱する`vendor/`配下のコードはApache License 2.0です。リポジトリはIssueでの不具合報告を受け付ける一方、外部からのプルリクエストは受け付けていません。 料金面では「追加のサービス料金はない」と[公式ドキュメントのWhat is AWS Emulator?](https://docs.aws.amazon.com/emulator/latest/userguide/what-is-service.html)に書かれています。AWSアカウントも不要です。ただし既定では匿名の利用データとエラーデータを送信する設定になっており、`aws-emulator --telemetry off`か環境変数`EMULATOR_TELEMETRY=off`で止められます。社内規程で外部送信を制限している案件では、最初に止めておく項目です。 ### AWS APIモデルから作る対応範囲とコントロールプレーン寄りの忠実度 対応するのは、[AWS API modelsリポジトリ](https://github.com/aws/api-models-aws)にAPIモデルがあるAWSサービスです。サービス名の一覧表は用意されておらず、実装済みかどうかは操作単位で決まります。未実装の操作を呼んだときの応答は、HTTP 501とエラーコード`NotImplemented`です。黙って成功したふりをしないため、テストはその場で失敗します。 実装の厚みは、どのサービスでも一様というわけではありません。[Fidelity in AWS Emulator](https://docs.aws.amazon.com/emulator/latest/userguide/fidelity.html)では、現時点でAWSに最も近いのはバケット作成のようなコントロールプレーンのAPIで、オブジェクトの読み書きのようなデータプレーンのAPIや、CloudFormation・Terraform・AWS CDKといったIaCツールへの対応はサービスごとに差があると説明しています。AWS側のAIエージェントが更新を回しており、リリースは1日に何度も出ます。GitHubのReleasesで確認した最新は2026年11月11日時点で1.0.322、つまり1.0系です。 ## LinuxパッケージとDockerでAWS Emulatorを起動する手順と確認 導入経路は、AIコーディングエージェント用スキル、Linuxパッケージ、Docker、Rustテスト内の組み込みモードの4つです。チームで手順を揃えやすいのはLinuxパッケージとDockerの2つなので、ここではこの2つを扱います。 ### Debian・RPMパッケージを入れてaws-emulatorを起動するLinuxの流れ [Getting started on Linux](https://docs.aws.amazon.com/emulator/latest/userguide/getting-started-linux.html)に従うと、Ubuntu系では次の3行で導入から起動まで進みます。x86\_64とaarch64の両方にRPMとDebianパッケージが用意されており、Arm機ではファイル名の`amd64`を`arm64`に替えます。 ``` # Debian/Ubuntu（amd64） curl -fsSLo aws-emulator.deb https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/latest/aws-emulator_amd64.deb sudo apt-get install -y ./aws-emulator.deb aws-emulator -v # 起動（127.0.0.1:9297 で HTTPS を待ち受ける。Ctrl+C で停止） aws-emulator --telemetry off ``` Amazon Linux 2023やRHEL系なら`sudo dnf install -y`にRPMのURLを渡すだけです。停止するとエミュレーターは`~/.aws/emulator/9297/`に書いた認証情報と証明書を消し、メモリ上のリソースも全て捨てます。テストのたびに空の状態から始まるので、前回のデータが残って結果が揺れる問題は起きません。待機時のメモリ使用量は約160MiBと公式に記載があります。 ### macOS・Windows向け自前Dockerビルドと127.0.0.1限定公開 macOSとWindowsにはネイティブのパッケージがなく、公式のビルド済みイメージも公開されていません。[Getting started with Docker](https://docs.aws.amazon.com/emulator/latest/userguide/getting-started-docker.html)に載っている短いDockerfileで、自分でイメージを作ります。 ``` FROM public.ecr.aws/amazonlinux/amazonlinux:2023-minimal ADD https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/latest/aws-emulator-x86_64.rpm /tmp/aws-emulator.rpm RUN rpm -i /tmp/aws-emulator.rpm && rm /tmp/aws-emulator.rpm \ && mkdir -p /home/emulator && chown 1000 /home/emulator USER 1000 ENV HOME=/home/emulator EXPOSE 9297 ENTRYPOINT ["aws-emulator", "-b", "0.0.0.0"] ``` Apple siliconでは`ADD`行のファイル名を`aws-emulator-aarch64.rpm`にします。`docker build -t aws-emulator .`でビルドしたら、ポート公開時の指定は`-p 127.0.0.1:9297:9297`の形です。`-p 9297:9297`と省略すると社内LANの他の端末からも届く状態になると公式が注意しています。認証情報と証明書を手元のSDKから読めるよう、ホストの`~/.aws/emulator`をボリュームでつなぐ点も忘れないでください。公式手順のdocker runは`--memory=2g`で上限を掛けており、超えると終了コード137で止まってリソースが消えます。 ## 環境変数でAWS CLIとSDKの向け先を変えてS3とDynamoDBを試す手順 アプリのコードには手を入れません。テストを流すシェルの環境変数だけで、AWS CLIとSDKの宛先をエミュレーターへ切り替えます。 ### AWS\_ENDPOINT\_URLと証明書の変数をまとめて設定する8行のシェル設定 [Pointing your AWS SDK at AWS Emulator](https://docs.aws.amazon.com/emulator/latest/userguide/point-sdk-to-emulator.html)が示す設定は次のとおりです。エミュレーターは起動のたびにアクセスキーと自己署名証明書を作り直し、ポート番号のディレクトリへ書き出します。 ``` export AWS_ENDPOINT_URL=https://127.0.0.1:9297 export AWS_SHARED_CREDENTIALS_FILE=~/.aws/emulator/9297/emulator_credentials export AWS_CONFIG_FILE=~/.aws/emulator/9297/config export AWS_CA_BUNDLE=~/.aws/emulator/9297/ca.pem export AWS_EC2_METADATA_DISABLED=true export AWS_DISABLE_HOST_PREFIX_INJECTION=true export AWS_REGION=us-east-1 export AWS_DEFAULT_REGION=us-east-1 unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN AWS_PROFILE # 動作確認 aws sts get-caller-identity aws s3api create-bucket --bucket demo-bucket-20261112 aws dynamodb create-table --table-name orders \ --attribute-definitions AttributeName=id,AttributeType=S \ --key-schema AttributeName=id,KeyType=HASH --billing-mode PAY_PER_REQUEST ``` 最後の`unset`行は省けません。環境変数の認証情報は認証情報ファイルより優先されるため、残っていると本物のキーで署名され、エミュレーターはそのリクエストを拒否します。`AWS_CONFIG_FILE`を差し替えると自分のconfigにあるリトライ設定なども効かなくなるので、必要ならエミュレーターのconfigを複製して追記します。 ### get-caller-identityの初回確認と000000000000の応答 設定漏れのまま進むと、テストは実AWSへ向かいます。`AWS_ENDPOINT_URL`が未設定のシェルでは、SDKが見つけた認証情報で本番アカウントを呼んでしまうからです。エミュレーターは単一アカウント`000000000000`として振る舞い、ARNは`arn:aws:iam::000000000000:user/emulator`になります。自社のアカウントIDが表示されたら、その時点でテストを止めて変数を見直します。 CIのスクリプトでは、この確認をテストの前段に1行入れておくと事故を防げます。起動待ちには`/__admin/health`がHTTP 200と本文`ok`を返す仕様を使います。 ### Node.js・Java・.NETで追加する証明書設定とS3のホスト名の落とし穴 AWS CLI v2、Boto3、Go v2は`AWS_CA_BUNDLE`だけで証明書を信頼します。言語によっては追加の変数が要ります。 | クライアント | 追加で必要な設定 | | ---------------------- | ---------------------- | | AWS CLI v2・Boto3・Go v2 | 不要 | | JavaScript v3（Node.js） | NODE\_EXTRA\_CA\_CERTS | | Java 2.x | JAVA\_TOOL\_OPTIONSで指定 | | Rust・.NET | SSL\_CERT\_FILE | 見落としやすいのはS3です。エンドポイントを`localhost`と書くと、JavaScript・Java・GoのSDKはバケット名をホスト名側に入れるため、リクエストが届きません。`127.0.0.1`のまま使います。Javaで`truststore.p12`の指定に使う環境変数は`JAVA_TOOL_OPTIONS`です。このトラストストア指定はJVMの既定ストアを置き換えるので、同じプロセスから実AWSへも接続するテストでは`PKIX path building failed`になります。S3 Controlはアカウント ID をホスト名に入れる仕様で、エミュレーターには届きません。 ## GitHub ActionsでAWS Emulatorを起動して統合テストを回す設定例 CIではAWSアカウントもOIDCロールも用意せずに統合テストを回せます。ここが最も効く使い道です。 ### ヘルスチェックで起動を待ってからpytestを流すワークフロー定義 次は、公式のLinux手順と起動待ちのループを1つのジョブにまとめた構成例です。エミュレーターはバックグラウンドで起動し、同じステップの中でテストまで流します。 ``` name: integration-test on: [pull_request] jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Run tests against AWS Emulator run: | curl -fsSLo aws-emulator.deb https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/latest/aws-emulator_amd64.deb sudo apt-get install -y ./aws-emulator.deb aws-emulator --telemetry off > emulator.log 2>&1 & for i in $(seq 30); do curl -sf --cacert $HOME/.aws/emulator/9297/ca.pem https://127.0.0.1:9297/__admin/health && break sleep 1 done export AWS_ENDPOINT_URL=https://127.0.0.1:9297 export AWS_SHARED_CREDENTIALS_FILE=$HOME/.aws/emulator/9297/emulator_credentials export AWS_CONFIG_FILE=$HOME/.aws/emulator/9297/config export AWS_CA_BUNDLE=$HOME/.aws/emulator/9297/ca.pem export AWS_EC2_METADATA_DISABLED=true export AWS_DISABLE_HOST_PREFIX_INJECTION=true export AWS_REGION=us-east-1 AWS_DEFAULT_REGION=us-east-1 aws sts get-caller-identity --query Account --output text | grep -qx 000000000000 python -m pytest tests/integration ``` `grep -qx 000000000000`の行は、宛先がエミュレーターでなければジョブを落とす安全装置です。ワークフローの書き方そのものは[GitHub Actionsでビルド・自動テストを設定する方法](https://www.issoh.co.jp/tech/details/2497/)で、実AWSへのデプロイまで自動化する構成は[TerraformをGitHub Actionsで自動化しAWSへ反映する手順](https://www.issoh.co.jp/tech/details/2715/)で解説しています。テストはエミュレーター、デプロイは実AWSと、ジョブを分けて持つのが素直な形です。 ### 本物の認証情報をテストジョブに置かないためのシークレット分離 公式は、テストジョブの環境に本物の認証情報を置かないよう求めています。上の例でも`secrets`を一切参照していません。デプロイ用のOIDCロールは別ジョブにだけ渡し、テストジョブからは物理的に届かない状態にします。 エミュレーターは既定で自分が発行したキーで署名されたリクエストしか受け付けません。`--auth off`で署名検証を外せますが、ブラウザや他のローカルプログラムから勝手に呼ばれる経路が開くため、共有ランナーでは使わない方が安全です。 ## 忠実度スコアの読み方とIAM未評価・単一アカウントという制約 「動いた」と「AWSと同じ」は別物です。どこまで信じてよいかは、公開されている忠実度スコアで判断します。 ### リリースごとに公開されるk of n表記の合格数と比べ方の注意 忠実度テストは、AWS SDKで短いワークフローを実行し、結果・作られたリソース・エラーコードとメッセージまでAWSと一致するかを確かめるプログラムです。テストは米国西部（オレゴン）リージョンの実AWSで検証して作られ、[aws-emulator-evaluation-suiteリポジトリ](https://github.com/aws/aws-emulator-evaluation-suite)に未合格のものも含めて公開されています。 スコアはサービスごとに「50件中40件」のような形で、[GitHubのReleasesページ](https://github.com/aws/aws-emulator/releases)に毎リリース載ります。比べてよいのは、同じ版のテストスイートを使ったスコア同士だけです。テストが追加されると合格率は下がって見えることがあり、40/50が45/60になれば合格数は5件増えています。自分の案件で使うサービスの行だけを確認し、リポジトリの`fidelity_tests_runner`で手元のビルドに対して再実行することもできます。 ### IAMポリシー未評価と1アカウント・1リージョン運用で再現できない失敗 公式の制約一覧で、設計に響くのは次の4点です。上ほど影響が大きい順に並べています。 - IAMポリシーとリソースベースポリシーをAWSと同じように評価しない。AWSで拒否されるリクエストが通ることがある - アカウントとリージョンでリソースを分けない。複数リージョンを試すならポートを変えて別プロセスを立てる - 挙動の検証はオレゴン（グローバルサービスはバージニア北部）だけで、東京リージョン固有の提供差は反映されない - 長時間稼働と負荷試験は未検証。テストのたびに起動と停止を繰り返す前提 つまり「Lambdaの実行ロールに権限が足りず本番で落ちる」類の失敗は、ここでは見つかりません。権限まわりは実AWSの検証アカウントで、最小権限のロールを付けた状態で一度は通す工程を残します。 ## LocalStack・motoと比べたAWS Emulatorの採用条件と見送る場面 ローカルでAWSを再現する手段は、AWS Emulatorの登場で3択になりました。判断の材料を並べ、どの案件で何を選ぶかを言い切ります。 ### 料金・商用利用・IAM検証で並べたLocalStack・motoとの比較表 LocalStackの料金は[公式の料金ページ](https://www.localstack.cloud/pricing)で2026年11月12日に確認した表記です。 | 観点 | AWS Emulator | LocalStack Base | moto | | --------- | ----------------- | --------------- | ----------- | | 料金 | 追加料金なし | 月39ドル（年払い） | 無償 | | 商用利用 | 可 | 可（Hobbyは不可） | 可 | | IAMポリシー評価 | 評価しない | 基本的な評価あり | 本記事では未確認 | | 提供元 | AWS | LocalStack社 | OSSコミュニティ | | 主な起動方法 | Linuxパッケージ・Docker | Docker | pip・サーバーモード | LocalStackのHobbyプランは非商用限定で、受託開発では使えません。IAMポリシーの適用もBase以上です。このため「商用で無償、かつAWSが保守する」という条件をAWS Emulatorだけが満たします。LocalStackの起動手順やCloud Podsの容量は[LocalStackとは？有料化後の料金と判断基準](https://www.issoh.co.jp/tech/details/17634/)で詳しく比べています。 ### AWS Emulatorの採用を見送るべき3つの案件条件と代わりの手段 次のどれかに当てはまる案件では、AWS Emulatorを主役にしません。 - 権限設計そのものが納品物の中心にある。IAMの評価が無いため、検証の意味が薄い - CloudFormationやCDKのスタック全体を毎回ローカルでデプロイしたい。IaC対応はサービスごとに差がある段階で、[AWS SAM](https://www.issoh.co.jp/tech/details/3823/)のローカル実行や実AWSの検証環境の方が確実 - 既にLocalStackのCloud Podsで状態のスナップショットを共有する運用が回っている。乗り換えの手間に見合う差が無い Pythonだけで完結する単体寄りのテストなら、デコレーター1つで差し込める[moto](https://github.com/getmoto/moto)の方が軽く済みます。AWS Emulatorが勝つのは、複数言語のSDKやAWS CLIをまたいだ統合テストを、ライセンス費用なしでCIに載せたい場面です。 ### 受託開発でローカル検証環境を設計するときの採用判断と検証分担の順番 実務での決め方は単純です。まず案件が使うサービスの忠実度スコアを見て、主要なAPIが合格していればテスト基盤をAWS Emulatorで組みます。次に切り出すのは、実AWSの検証アカウントで行う権限とIaCの検証だけです。最後に、両者をCIのジョブで分けます。 この3層の切り分けを、既存システムのテスト資産やTerraform構成に合わせて設計するところで迷う場合は、[AWS・Google Cloud・Azureのインフラ構築支援](https://www.issoh.co.jp/service/system/aws/)でご相談いただけます。Terraformで検証アカウントを用意する手順は[TerraformでAWSを構築する手順](https://www.issoh.co.jp/tech/details/1900/)が参考になります。 ## よくある質問 AWS Emulatorの導入前によく出る疑問を、公式ドキュメントの記述をもとに回答します。 ### AWS Emulatorは無料で使えますか？ エミュレーター自体に追加のサービス料金はなく、AWSアカウントも不要です。料金が発生するのは、テストを終えたアプリを実際のAWSへデプロイしてリソースを使ったときだけです。ソースコードはGitHubでCC0-1.0として公開されています。なお既定で匿名の利用データを送るため、気になる場合は`--telemetry off`で止めてから使ってください。 ### AWS EmulatorとLocalStackの違いは何ですか？ 提供元と費用が大きく違います。AWS EmulatorはAWSが保守し、商用でも追加料金がかかりません。LocalStackは商用利用にBase（年払いで月39ドル）以上が必要で、その代わりIAMポリシーの評価やCloud Podsといった機能を持ちます。エンドポイントもAWS Emulatorは9297番のHTTPS、LocalStackは4566番と異なります。 ### WindowsやMacでAWS Emulatorを動かせますか？ 動かせますが、Docker経由になります。ネイティブのパッケージはLinux向けのRPMとDebianだけで、公式のビルド済みイメージもありません。公式ドキュメントのDockerfileで自分でイメージを作り、`-p 127.0.0.1:9297:9297`で起動します。Apple siliconではaarch64のRPMを指定します。 ### AWS Emulatorで通ったテストは本番でも通りますか？ 保証はありません。IAMポリシーを評価しないため、本番で権限エラーになる処理が通ることがあります。データプレーンのAPIやIaCツールの対応にもサービスごとの差があります。使うサービスの忠実度スコアを確認したうえで、権限とデプロイは実AWSの検証アカウントで確かめる工程を残してください。 ### AWS Emulatorを本番環境やステージング環境の代わりに使えますか？ 使えません。公式は開発とテスト専用と明記し、本番ワークロードでの利用を禁じています。リソースはメモリに置かれ、停止すると全て消えます。長時間稼働や負荷試験も未検証です。ステージングは実AWSに置き、エミュレーターはテストのたびに起動と停止を繰り返す使い方に限ります。 ## 関連記事 - [LocalStackとは？AWSをローカルで動かす手順と有料化後の料金・判断基準](https://www.issoh.co.jp/tech/details/17634/)：もう1つの選択肢の料金とプラン差を確認したいとき - [AWS SAMとは？CloudFormationとの違い・SAM CLIの使い方を実例で解説](https://www.issoh.co.jp/tech/details/3823/)：Lambdaをローカルで実行して確かめたいとき - [AWS CDK（cdk）とは？スタックの仕組みとcdk deployの使い方](https://www.issoh.co.jp/column/details/2892/)：IaCのスタックを実AWSで検証する前提知識 - [GitHub Actionsでビルド・自動テストを設定する方法](https://www.issoh.co.jp/tech/details/2497/)：統合テストを載せるワークフローの基本 - [TerraformをGitHub Actionsで自動化しAWSへ反映する手順](https://www.issoh.co.jp/tech/details/2715/)：テストの後段に置くデプロイジョブの組み方 --- 出典: [AWS Emulatorとは：ローカルでAWS APIを動かす手順とLocalStackとの違い]()（株式会社一創）