インフラ・クラウド

AWS Emulatorとは：ローカルでAWS APIを動かす手順とLocalStackとの違い

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の記事によると、実装言語はRustで、ソースコードはGitHubで公開されています。aws/aws-emulatorリポジトリのライセンス表記はCC0-1.0で、同梱するvendor/配下のコードはApache License 2.0です。リポジトリはIssueでの不具合報告を受け付ける一方、外部からのプルリクエストは受け付けていません。

料金面では「追加のサービス料金はない」と公式ドキュメントのWhat is AWS Emulator?に書かれています。AWSアカウントも不要です。ただし既定では匿名の利用データとエラーデータを送信する設定になっており、aws-emulator --telemetry offか環境変数EMULATOR_TELEMETRY=offで止められます。社内規程で外部送信を制限している案件では、最初に止めておく項目です。

AWS APIモデルから作る対応範囲とコントロールプレーン寄りの忠実度

対応するのは、AWS API modelsリポジトリにAPIモデルがあるAWSサービスです。サービス名の一覧表は用意されておらず、実装済みかどうかは操作単位で決まります。未実装の操作を呼んだときの応答は、HTTP 501とエラーコードNotImplementedです。黙って成功したふりをしないため、テストはその場で失敗します。

実装の厚みは、どのサービスでも一様というわけではありません。Fidelity in AWS Emulatorでは、現時点で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に従うと、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に載っている短い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が示す設定は次のとおりです。エミュレーターは起動のたびにアクセスキーと自己署名証明書を作り直し、ポート番号のディレクトリへ書き出します。

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でビルド・自動テストを設定する方法で、実AWSへのデプロイまで自動化する構成はTerraformをGitHub Actionsで自動化しAWSへ反映する手順で解説しています。テストはエミュレーター、デプロイは実AWSと、ジョブを分けて持つのが素直な形です。

本物の認証情報をテストジョブに置かないためのシークレット分離

公式は、テストジョブの環境に本物の認証情報を置かないよう求めています。上の例でもsecretsを一切参照していません。デプロイ用のOIDCロールは別ジョブにだけ渡し、テストジョブからは物理的に届かない状態にします。

エミュレーターは既定で自分が発行したキーで署名されたリクエストしか受け付けません。--auth offで署名検証を外せますが、ブラウザや他のローカルプログラムから勝手に呼ばれる経路が開くため、共有ランナーでは使わない方が安全です。

忠実度スコアの読み方とIAM未評価・単一アカウントという制約

「動いた」と「AWSと同じ」は別物です。どこまで信じてよいかは、公開されている忠実度スコアで判断します。

リリースごとに公開されるk of n表記の合格数と比べ方の注意

忠実度テストは、AWS SDKで短いワークフローを実行し、結果・作られたリソース・エラーコードとメッセージまでAWSと一致するかを確かめるプログラムです。テストは米国西部（オレゴン）リージョンの実AWSで検証して作られ、aws-emulator-evaluation-suiteリポジトリに未合格のものも含めて公開されています。

スコアはサービスごとに「50件中40件」のような形で、GitHubの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の料金は公式の料金ページで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とは？有料化後の料金と判断基準で詳しく比べています。

AWS Emulatorの採用を見送るべき3つの案件条件と代わりの手段

次のどれかに当てはまる案件では、AWS Emulatorを主役にしません。

  • 権限設計そのものが納品物の中心にある。IAMの評価が無いため、検証の意味が薄い
  • CloudFormationやCDKのスタック全体を毎回ローカルでデプロイしたい。IaC対応はサービスごとに差がある段階で、AWS SAMのローカル実行や実AWSの検証環境の方が確実
  • 既にLocalStackのCloud Podsで状態のスナップショットを共有する運用が回っている。乗り換えの手間に見合う差が無い

Pythonだけで完結する単体寄りのテストなら、デコレーター1つで差し込めるmotoの方が軽く済みます。AWS Emulatorが勝つのは、複数言語のSDKやAWS CLIをまたいだ統合テストを、ライセンス費用なしでCIに載せたい場面です。

受託開発でローカル検証環境を設計するときの採用判断と検証分担の順番

実務での決め方は単純です。まず案件が使うサービスの忠実度スコアを見て、主要なAPIが合格していればテスト基盤をAWS Emulatorで組みます。次に切り出すのは、実AWSの検証アカウントで行う権限とIaCの検証だけです。最後に、両者をCIのジョブで分けます。

この3層の切り分けを、既存システムのテスト資産やTerraform構成に合わせて設計するところで迷う場合は、AWS・Google Cloud・Azureのインフラ構築支援でご相談いただけます。Terraformで検証アカウントを用意する手順はTerraformでAWSを構築する手順が参考になります。

よくある質問

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に置き、エミュレーターはテストのたびに起動と停止を繰り返す使い方に限ります。

関連記事

お気に入りに入れた記事の一覧

一創の公式 SNS

X では毎朝の新着記事と IT ニュースの速報を、YouTube・TikTok・Instagram・LinkedIn・Facebook では記事の解説動画を配信しています。

この記事は以下の記事からリンクされています

この記事に関連するサービス

資料請求

今日のトレンド記事 直近 24 時間で、いつもより多く読まれている記事

  1. 2026.01.21　コラム 税務調査の録音は禁止？判例・裁決と国税局マニュアルで見る、断られたときの対応
  2. 2026.11.09　テックブログ エディオン不正アクセス第2報：カード番号の対象確認とログ・決済画面の改ざん対策
  3. 2026.11.11　テックブログ Microsoft 2026年11月の月例更新：Outlookの悪用済みCVE-2026-124194と修正版の確認方法
  4. 2026.11.11　テックブログ JANISの不正アクセス：最大11,652名の医療機関情報と情報窃取プログラムの検知設定
  5. 2026.11.11　テックブログ SMBC日興証券の不正アクセス：持株会会員最大5.6万人の範囲と受託システムの分離設計

RELATED POSTS 関連記事

一覧へ戻る

目次