aws-emulator について
ローカルで AWS サービス API を提供する AWS Emulator の実行と、CLI や SDK の接続を支援するスキルです。Linux、Docker、Rust の組み込みモードに対応し、アプリや個別操作の互換性を根拠に基づいて確認します。
主な機能
- 01HTTPS によるローカル AWS API の提供
- 02AWS CLI と SDK の接続
- 03Linux・Docker・Rust 組み込みモード
- 04根拠に基づくアプリ互換性チェック
- 05トラブルシューティングとアップグレード案内
活用シーン
- 01ローカルでの AWS API テスト
- 02CLI や SDK のエミュレーター接続
- 03現行ビルドでのプロジェクトや操作の対応確認
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/ / github.com/ aws/ agent-toolkit-for-aws --skill aws-emulatorインストール後、Claude Code で/aws-emulatorを入力して読み込まれたか確認します。
同梱ファイル
SKILL.md と一緒にインストールされる参考資料やスクリプト。
references/compatibility-check.mdcompatibility-classify-traces.mdcompatibility-find-usage.mdconnect.mdcontainer.mdlinux-package.mdrust-embedded.mdtroubleshooting.md詳細
AWS Emulator
AWS Emulator は、127.0.0.1:9297 で AWS サービス API を HTTPS 経由で提供する、aws-emulator という単一のコマンドです。ネイティブで動作するのは Linux(RPM または Debian パッケージ)のみです。macOS と Windows では、このパッケージからビルドされた Docker コンテナ内で動作します。また、Rust テストではプロセス内に組み込むこともできます(組み込みモード)。起動時に書き込まれる設定ファイルと認証情報ファイルを参照するよう、いくつかの環境変数を設定すれば、AWS CLI と SDK は変更せずに動作します。このスキルでは、起動と接続の方法、およびインストール済みビルドでプロジェクト(または単一のオペレーション)が動作するかどうかを、根拠とともに確認する方法を説明します。
ガードレール — このスキルのファイルの場所(MCP とローカルインストール)
このスキルに含まれるのはドキュメント(references/*.md)のみで、スクリプトはありません。読み込む方法は 2 通りあり、それぞれ異なる場所からファイルを取得します。
- AWS MCP の
retrieve_skillツール呼び出しを通じて読み込む場合。 スキルはローカルファイルシステムにインストールされていません。fileパラメーターを指定し、同じretrieve_skillツールを使って各リファレンスを取得する必要があります(例:file="references/linux-package.md")。これらのパスをローカルディレクトリや作業ディレクトリからfile_readしてはいけません。また、ファイルシステム内を検索してもいけません。名前が一致するローカルファイルがあっても、このスキルとは無関係です。 - ローカルにインストールされている場合(スキルが
.claude/skills/aws-emulator/、~/.claude/skills/aws-emulator/、.kiro/skills/aws-emulator/などのローカルスキルディレクトリにある場合)。リファレンスはローカルのスキルディレクトリから読み込みます。このスキルに記載されているすべてのパスは、references/*.md内のリンクを含め、リンクが記載されたファイルではなくスキルディレクトリ(このSKILL.mdがあるフォルダー)を基準とします。たとえば、references/connect.mdは<skill directory>/references/connect.mdです。
この違いが適用されるのは、スキルに含まれるファイルのみです。セッション中に作成された、またはユーザーから提供されたすべての成果物は、スキルの読み込み方法にかかわらず、ユーザーの作業ディレクトリから読み込み、そこに書き込みます。retrieve_skill を使って顧客データを取得したり書き込んだりしてはいけません。
意図から選ぶ
| ユーザーの目的 | 参照先 |
|---|---|
| Linux でインストール、起動、停止する、または最初のスモークテストを実行する | references/linux-package.md |
| macOS または Windows、あるいは Docker、CI、並列ジョブ、エージェントのサンドボックスでインストールまたは実行する | references/container.md |
| Rust のテスト内で実行する(組み込みモード:テストごとの状態、エンドポイントや証明書は不要) | references/rust-embedded.md |
| アップグレードする、バージョンを選択または固定する(CI の場合も含む)、最新リリースを確認する | references/linux-package.md(「Upgrade」)、Docker の場合は references/container.md、組み込みモードの場合は references/rust-embedded.md |
| AWS CLI または SDK(JS、Python、Java、Go、Rust、.NET など)を接続する | references/connect.md |
エラーを解決する:TLS/証明書、AccessDenied/SignatureDoesNotMatch、プロファイル、接続拒否、ポート使用中、Docker のファイル所有権、UnknownService、NotImplemented、状態の消失 | references/troubleshooting.md |
| アプリ、リポジトリ、テストが動作するか確認する | references/compatibility-check.md、references/compatibility-find-usage.md(ステップ 2)および references/compatibility-classify-traces.md(ステップ 4) |
| 1 つ以上の操作や動作が機能するか(「X に対応していますか?」)、または何ができないか確認する | references/compatibility-check.md の「Single operation (no app)」セクション |
何かをインストールまたは起動する前に、環境を確認し、不足しているものをユーザーに伝えてください:aws-emulator -v(インストール済みか)、aws --version またはプロジェクトの AWS SDK 依存関係(ユーザーが接続するクライアント)、macOS と Windows では docker info(Docker が起動しているか)、およびポート(デフォルトは 9297)が空いているかを確認します。組み込みモードで必要なのは、Cargo を含む Rust ツールチェーン、C コンパイラー、AWS SDK for Rust だけです。それ以外の場合は、AWS Emulator user guide に従ってください。
常に最新の AWS Emulator リリースを使用してください。バージョンを固定したり(CI の場合も、「再現性のため」という選択肢の場合も)、古いバージョン向けの回答をしたりしないでください。セキュリティ修正と新しい対応範囲が追加されるのは最新リリースのみであり、互換性チェックでも常に最新のレポートとコーパスを使用します。最新バージョンは gh release view -R aws/aws-emulator --json tagName,publishedAt で確認してください(gh が使えない場合は git ls-remote --tags --refs --sort=-v:refname https://github.com/aws/aws-emulator | sed 's,.*refs/tags/,,' | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | head -1 を使用します(リリースタグのみ、サフィックスなしの vX.Y.Z。何も表示されない場合は停止して、ユーザーにタグを尋ねてください))。インストール済みのエミュレーターがない、または古い場合はアップグレードしてください(コマンドは references/linux-package.md(Linux パッケージ、「Upgrade」)および references/container.md にあります)。ユーザーからインストール、セットアップ、アップグレードを依頼された場合はそのまま進めてください。ただし、最初の sudo コマンドを実行する前には一度確認してください。それ以外の場合は、アップグレードに sudo が必要な場合があり、実行中のエミュレーターを再起動すると状態が消去されるため、まず一度確認してください。アップグレードの手順は、エミュレーターを停止し、LTS/latest/ のインストールコマンドを再度実行して(古いバージョンを置き換えます)、aws-emulator -v を確認し、再び起動することです。Docker の場合は、docker build --pull --no-cache で再ビルドしてください。最新リリースを確認できない場合(リリースがない、またはアクセスできない)は、その旨を伝え、アップグレードコマンドを提示してから作業を続けてください。
ルール
- ユーザーからエミュレーターのインストール、起動、接続、修正方法を尋ねられた場合は、その環境で作業し、ヘルスチェックと
aws sts get-caller-identityの結果が000000000000であることを確認してから、実行した内容を報告してください。説明だけを求められた場合に限り、作業せずに説明してください。書き込み先は~/.aws/emulator/、<app>/.aws-emulator/、mktemp -dで作成したディレクトリ、イメージ、コンテナに限定してください。sudo、シェルプロファイルの編集、リポジトリやテストスクリプトの編集、その他の書き込みを行う前には、ユーザーに許可を求めてください。 - エミュレーターはバックグラウンドで起動してください(パッケージの場合はポートごとのログを指定して
nohup … &、Docker の場合はdocker run -d)。ヘルスチェックが通るまで待機してください。エミュレーターをフォアグラウンドで起動すると、シェルがブロックされます。起動時には、テレメトリーが有効であることと無効にする方法をユーザーに伝えてください(「セキュリティ」を参照)。CI ジョブとエージェントのサンドボックスでは、テレメトリーを無効にして起動してください。 - 実行のたびに変わる
config、emulator_credentials、ca.pemは、絶対にコミットしないでください。 NotImplemented(HTTP 501。SDK は再試行しません)という応答は、インストール済みビルドのカバレッジ不足であり、設定ミスではありません。その旨を伝え、アプリまたは該当操作の互換性チェックを提案してください。- 互換性について質問された場合は、チェックを実行し、そのルールに従って判定結果を提示してください(references/compatibility-check.md を参照)。記憶やこのファイルに基づいて回答してはいけません。
- チェックは厳格です。根拠が不明確な項目は UNVERIFIED となり、回答は「動作しません」となります。厳格さを適用するのは根拠に対してであり、項目を作り出すことに対してではありません。アプリが実際に依存している項目のみを記録してください。
- 判定後、以下の制限に関わる UNVERIFIED の前提項目ごとに、その制限を説明する文を1 文追加してください。判定自体は変更しないでください。
- 実際の AWS への AWS API 呼び出しには AWS MCP サーバーを推奨します(サンドボックス化、IAM 認証、監査ログ対応)が、必須ではありません。このマシン上のエミュレーターには接続できないため、エミュレーターへの呼び出しは、接続用の変数を設定したローカルの AWS CLI または SDK 経由で行ってください。
セキュリティ
- エミュレーターはループバック上で動作させてください。デフォルトのバインド先は
127.0.0.1です。-bを変更するのはコンテナ内に限り、コンテナのポートは127.0.0.1のみで公開してください。すべてのインターフェイスで公開してはいけません。 - TLS 検証をグローバルに、または AWS エンドポイントに対して無効にしないでください。また、
--no-verify-sslやverify=Falseを提案してはいけません。この実行で作成された~/.aws/emulator/<port>/ca.pemを、設定ファイル、AWS_CA_BUNDLE(Docker では常に使用)、または SDK 独自の設定で信頼してください。 - エミュレーターを呼び出すすべてのコマンドやジョブから、実際の AWS 認証情報を排除してください(references/connect.md の環境ファイルで対応しています)。
unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN AWS_PROFILEに加え、Web Identity とコンテナ認証情報の変数も解除してください(一覧は references/connect.md を参照)。その後、aws sts get-caller-identityの結果が000000000000であることを確認してください。 -a offを使用できるのは、127.0.0.1のみからアクセスできるローカルテストに限ります(Docker では、ポートを127.0.0.1で公開します)。他者がアクセスできる共有ホストや CI ホストでは使用しないでください。- テレメトリーはデフォルトで有効です。
-t offまたはEMULATOR_TELEMETRY=offで無効にできます(Docker では-e EMULATOR_TELEMETRY=off)。エミュレーターの起動時には、テレメトリーが有効であることと無効にする方法をユーザーに伝えてください。CI ジョブとエージェントのサンドボックスでは、デフォルトで-t off(Docker では-e EMULATOR_TELEMETRY=off)を指定して起動してください。テレメトリーで送信される情報については、AWS Emulator ユーザーガイドを案内してください。 - 本番データを使用したり、本番トラフィックをエミュレーターに送信したりしないでください。
- ログ、リクエスト、レスポンスを共有する前に、シークレット(キー、トークン、署名)と個人データを削除するか、マスキングしてください。
設計上の制限
これらはすべてのビルドに共通する制限です。対応範囲の一覧ではありません。
- オープンソースです。 ソースコードは aws/aws-emulator にあります。ライセンスについては LICENSE ファイルを参照してください。
- 状態はメモリ上にのみ保持されます。 プロセスが終了すると、すべての状態が失われます。リセット操作はありません。 初期状態に戻すにはプロセスを再起動してください。
- 本番環境向けではありません。 耐久性やセキュリティは保証されません。本番環境のトラフィックや データを送信しないでください。
- アカウントは1つです。 すべてのリクエストは、今回の実行用に発行されたキー(
emulator_credentials)で署名され、 アカウント000000000000で実行されます。 - エミュレーターごとにリージョンとアカウントは1つです。 エミュレーターは任意のリージョンとアカウント ID を受け付けますが、
どちらでリソースを分けて管理することもないため、リージョンやアカウントをまたぐ呼び出しには対応していません。
複数のリージョンをテストするには、リージョンごとにエミュレーターを1つ実行し、それぞれ異なるポートを使用してください。
動作の検証は
us-west-2の AWS との比較でのみ行われます。 - セキュリティテストの対象ではありません。 署名は検証されます(組み込みモードを除く)。また、エミュレーターは自身のキーで 署名されたリクエストを拒否しません。IAM ポリシー、アクセス許可の境界、リソースベースのポリシー(バケットポリシーなど)、 AWS KMS キーポリシー、アカウントやリージョンをまたぐアクセスのテストには使用しないでください。
- 実行するコードは分離されていません。 エミュレーターが実行する関数コードは、分離されずにユーザーの マシン上で実行されます。
- 対応範囲はビルドごとに異なります。 インストール済みのビルドで特定の操作や動作が機能するかどうかは、この一覧ではなく、 互換性チェックで確認してください。