はじめに
2026年11月、AWS公式のローカルエミュレーター「AWS Emulator」が公開されました。AWS CLIやSDKの接続先をローカルのHTTPSエンドポイントへ向けることで、AWSアカウントや実リソースを使わずにAPIを試せます。
今回は実際に、AWS EmulatorでCloudFormationの基本操作がどこまで動くかを試してみました。S3バケット1個だけを含むテンプレートを使い、CreateStack、DescribeStacks、UpdateStack、DeleteStackと、S3 APIから見た実体を確認します。
1. AWS Emulatorとは
AWS Emulatorは、AWS APIをローカルで提供する開発・テスト向けのプログラムです。作成したリソースはエミュレーター内に保持され、AWSアカウントへは送信されません。AWS CLIやSDKから既存のAWS APIを呼び出せます。
一方で、AWS公式ドキュメントでは、本番利用やセキュリティ検証には使わないよう説明されています。リソースはメモリ上に保持され、停止すると失われます。また、リージョンやアカウントは実AWSのようには分離されず、AWSとの一致度もサービスや機能によって異なります。CloudFormationも、基本APIが呼べることと、実AWSの全機能・全リソースが同じように動くことは別です。
2. 今回使った環境
以下は検証時(2026年11月13日)の環境です。
| 項目 | 値 |
|---|---|
| OS | macOS 15.6 / Apple Silicon arm64 |
| AWS CLI | 2.36.25 |
| Docker CLI / Colima | 29.9.3 / 0.10.3 |
| AWS Emulator | aws-emulator-1.0.343-1.aarch64 |
| リージョン | us-east-1 |
| エンドポイント | https://127.0.0.1:9297 |
3. AWS Emulatorをセットアップする
HomebrewとAWS CLI v2が使えるApple SiliconのMacを前提に進めます。
macOSでAWS Emulatorを動かすには、Dockerの実行環境が必要です。以下のコマンドでColimaとDocker CLIをインストールし、検証用VMを起動します。Dockerの接続先をそのVMへ切り替え、作業用ディレクトリを作成します。
Colimaとは:Mac上でLinux VMを起動し、Dockerなどのコンテナ実行環境を用意するツールです。今回はその環境をMacのDocker CLIから操作します。Colima公式README
brew install colima docker
colima start --profile aws-emulator-cfn --cpu 2 --memory 4 --disk 15
docker context use colima-aws-emulator-cfn
mkdir -p aws-emulator-cfn
cd aws-emulator-cfn
VMには2 CPU、メモリ4 GiB、ディスク15 GiBを割り当てています。以降のファイルは、この作業ディレクトリに保存します。
Dockerfileは、コンテナイメージの作り方と起動するコマンドを定義するファイルです。公式Docker手順をもとに、次の内容をDockerfileとして保存します。
Mac上のDockerで、Amazon Linux 2023のコンテナを動かします。そのコンテナにAWS Emulatorをインストールします。今回はApple Silicon搭載Macを使用するため、Linux向けのArm64版RPMパッケージ(aarch64)を使います。
FROM public.ecr.aws/amazonlinux/amazonlinux:2023-minimal
ADD https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/latest/aws-emulator-aarch64.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", "--telemetry", "off"]
USER 1000で非rootユーザーを指定し、ENTRYPOINTでEmulatorを起動します。--telemetry offは利用状況の送信を無効化する指定です。
RPMの取得先はLTS/latestのため、再現時には検証時のv1.0.343と異なる版が入る可能性があります。
以下をDockerfileの保存先で実行します。docker buildでaws-emulator-cfn:localというイメージを作り、docker runで起動します。mkdirでは、Mac側の作業ディレクトリ内にruntimeディレクトリを作成します。
docker build -t aws-emulator-cfn:local .
mkdir -p runtime
docker run --rm --memory=2g --memory-swap=2g \
-p 127.0.0.1:9297:9297 \
-e HOME=/home/emulator \
-v "$PWD/runtime:/home/emulator/.aws/emulator" \
aws-emulator-cfn:local -p 9297
-pはMacのローカルアドレスに9297番ポートを公開します。-vは、Macの作業ディレクトリ内のruntimeをコンテナ内の/home/emulator/.aws/emulatorにマウントする指定です。メモリ上限は2 GiBで、追加のswapは使いません。
Emulatorは起動時に、専用のアクセスキー・シークレットキーとTLS証明書を自動生成します。手動でキーを作る必要はありません。生成ファイルは共有ディレクトリ内に書き込まれるため、Mac側からも次のパスで参照できます。
| Mac側のファイル | 用途 |
|---|---|
runtime/9297/emulator_credentials |
Emulatorへのリクエスト署名に使う専用の認証情報 |
runtime/9297/ca.pem |
EmulatorのTLS証明書を検証するためのCA証明書 |
runtime/9297/config |
CLI・SDK向けに生成された接続設定 |
次の手順では、MacのAWS CLIにこれらのファイルを指定します。認証情報は起動ごとに生成されるため、再起動後は次の設定手順も再実行します。
起動したターミナルはそのままにして、別のターミナルで同じ作業ディレクトリを開きます。
認証情報と証明書は、先ほどEmulatorを起動した際にruntime/9297/へ生成されています。ここでは、そのファイルをAWS CLIが読み込むように設定します。公式接続手順に沿って、既存の認証環境変数を解除してから、各ファイルのパスを指定します。
unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN AWS_PROFILE AWS_DEFAULT_PROFILE
export AWS_CONFIG_FILE="$PWD/runtime/9297/config"
export AWS_SHARED_CREDENTIALS_FILE="$PWD/runtime/9297/emulator_credentials"
export AWS_CA_BUNDLE="$PWD/runtime/9297/ca.pem"
export AWS_EC2_METADATA_DISABLED=true
export AWS_DISABLE_HOST_PREFIX_INJECTION=true
export AWS_PAGER=""
mkdir -p runtime
sed 's/^\[.*\]$/[aws-emulator-cfn-only]/' "$AWS_SHARED_CREDENTIALS_FILE" > runtime/credentials
chmod 600 runtime/credentials
export AWS_SHARED_CREDENTIALS_FILE="$PWD/runtime/credentials"
sedでprofile名をaws-emulator-cfn-onlyに変更した認証情報のコピーをruntime/credentialsへ保存します。chmod 600は所有者だけに読み書きを許可する指定です。AWS_CA_BUNDLEはTLS証明書の検証に使い、IMDSからの認証取得と接続先へのホスト名プレフィックス追加も無効にしています。
次に、STSのGetCallerIdentityで接続先を確認します。以降のAWS CLIコマンドも、--endpoint-urlでローカル接続先、--profileで専用認証情報、--regionでリージョンを指定します。
aws --endpoint-url https://127.0.0.1:9297 \
--profile aws-emulator-cfn-only --region us-east-1 \
sts get-caller-identity
EmulatorのアカウントID000000000000が返ることを確認します。実AWSのアカウントIDが返った場合は、接続設定を見直してください。以下の出力では、UserId・バケット名のランダムな末尾・StackIdのUUIDを<masked>に置き換えています。
$ aws --endpoint-url https://127.0.0.1:9297 \
--profile aws-emulator-cfn-only --region us-east-1 \
sts get-caller-identity
{
"UserId": "<masked>",
"Account": "000000000000",
"Arn": "arn:aws:iam::000000000000:user/emulator"
}
4. CloudFormationを操作する
CloudFormationテンプレートは、作成するリソースを定義するファイルです。以下を作業ディレクトリのcreate.yamlとして保存します。Resources内のTestBucketはリソースを識別する論理ID、Type: AWS::S3::BucketはS3バケットを作る指定です。
AWSTemplateFormatVersion: '2010-09-09'
Description: Local emulator S3 lifecycle test only
Resources:
TestBucket:
Type: AWS::S3::Bucket
1つ目のコマンドはcreate.yamlを読み込み、emulator-s3-lifecycleというスタックを作成します。2つ目で状態を取得し、CREATE_COMPLETEを確認します。
aws --endpoint-url https://127.0.0.1:9297 --profile aws-emulator-cfn-only --region us-east-1 \
cloudformation create-stack --stack-name emulator-s3-lifecycle \
--template-body file://create.yaml
aws --endpoint-url https://127.0.0.1:9297 --profile aws-emulator-cfn-only --region us-east-1 \
cloudformation describe-stacks --stack-name emulator-s3-lifecycle
次のコマンドは、スタックのリソース一覧から実際のバケット名(物理ID)を取り出し、シェル変数BUCKETに保存します。今回はリソースが1個なので一覧の先頭を取得します。続くhead-bucketでS3側にもバケットが存在することを確認します。以降も同じターミナルでこの変数を使います。
BUCKET=$(aws --endpoint-url https://127.0.0.1:9297 --profile aws-emulator-cfn-only --region us-east-1 cloudformation list-stack-resources --stack-name emulator-s3-lifecycle --query 'StackResourceSummaries[0].PhysicalResourceId' --output text)
aws --endpoint-url https://127.0.0.1:9297 --profile aws-emulator-cfn-only --region us-east-1 s3api head-bucket --bucket "$BUCKET"
実行結果です。S3 APIからバケットARNとリージョンを取得できました。
$ BUCKET=$(aws --endpoint-url https://127.0.0.1:9297 --profile aws-emulator-cfn-only --region us-east-1 cloudformation list-stack-resources --stack-name emulator-s3-lifecycle --query 'StackResourceSummaries[0].PhysicalResourceId' --output text)
$ aws --endpoint-url https://127.0.0.1:9297 --profile aws-emulator-cfn-only --region us-east-1 s3api head-bucket --bucket "$BUCKET"
{
"BucketArn": "arn:aws:s3:::emulator-s3-lifecycle-testbucket-<masked>",
"BucketRegion": "us-east-1",
"AccessPointAlias": false
}
以下を作業ディレクトリのupdate.yamlとして保存します。同じ論理IDTestBucketに、Propertiesでバケットの設定を追加します。今回変更するのはTagsで、キーがVerification、値がupdatedのタグを付けます。
AWSTemplateFormatVersion: '2010-09-09'
Description: Local emulator S3 lifecycle test only
Resources:
TestBucket:
Type: AWS::S3::Bucket
Properties:
Tags:
- Key: Verification
Value: updated
保存したupdate.yamlを指定して既存のスタックを更新します。続けて状態を照会します。
aws --endpoint-url https://127.0.0.1:9297 --profile aws-emulator-cfn-only --region us-east-1 \
cloudformation update-stack --stack-name emulator-s3-lifecycle \
--template-body file://update.yaml
aws --endpoint-url https://127.0.0.1:9297 --profile aws-emulator-cfn-only --region us-east-1 \
cloudformation describe-stacks --stack-name emulator-s3-lifecycle
UPDATE_COMPLETEを確認したら、S3 APIからバケットのタグを取得します。結果にVerification=updatedが含まれていれば、更新内容が反映されています。
aws --endpoint-url https://127.0.0.1:9297 --profile aws-emulator-cfn-only --region us-east-1 s3api get-bucket-tagging --bucket "$BUCKET"
実行結果です。追加したタグと、CloudFormationが付けた管理用タグを確認できました。
$ aws --endpoint-url https://127.0.0.1:9297 --profile aws-emulator-cfn-only --region us-east-1 s3api get-bucket-tagging --bucket "$BUCKET"
{
"TagSet": [
{
"Key": "Verification",
"Value": "updated"
},
{
"Key": "aws:cloudformation:stack-name",
"Value": "emulator-s3-lifecycle"
},
{
"Key": "aws:cloudformation:stack-id",
"Value": "arn:aws:cloudformation:us-east-1:000000000000:stack/emulator-s3-lifecycle/<masked>"
},
{
"Key": "aws:cloudformation:logical-id",
"Value": "TestBucket"
}
]
}
最後に、delete-stackで検証用スタックを削除します。続くdescribe-stacksで削除の進行状況を確認します。
aws --endpoint-url https://127.0.0.1:9297 --profile aws-emulator-cfn-only --region us-east-1 \
cloudformation delete-stack --stack-name emulator-s3-lifecycle
aws --endpoint-url https://127.0.0.1:9297 --profile aws-emulator-cfn-only --region us-east-1 \
cloudformation describe-stacks --stack-name emulator-s3-lifecycle
保存しておいたバケット名でhead-bucketを実行します。404 Not Foundが返ることで、S3側でも削除されたことを確認します。
aws --endpoint-url https://127.0.0.1:9297 --profile aws-emulator-cfn-only --region us-east-1 s3api head-bucket --bucket "$BUCKET"
実行結果です。削除後のバケット照会は、期待どおり404になりました。
$ aws --endpoint-url https://127.0.0.1:9297 --profile aws-emulator-cfn-only --region us-east-1 s3api head-bucket --bucket "$BUCKET"
aws: [ERROR]: An error occurred (404) when calling the HeadBucket operation: Not Found
確認後、Emulatorを起動したターミナルでCtrl+Cを押します。コンテナは自動で削除されます。続けて、次のコマンドで検証用のColima VMも停止します。
colima stop --profile aws-emulator-cfn
AWS CLIの設定に使ったターミナルも閉じます。設定した環境変数はEmulatorの停止だけでは解除されないためです。
正常終了するとEmulatorが生成した認証情報・証明書・接続設定は削除されますが、コピーしたruntime/credentialsは残ります。Colima VMとDockerイメージも残り、Dockerの接続先は専用contextのままです。必要に応じて元のcontextへ戻してください。
5. 検証結果
検証結果は次のとおりです。
| 確認項目 | 確認できた内容 |
|---|---|
| Emulatorへの接続 | STSのGetCallerIdentityでアカウントID000000000000を取得 |
| バケットの作成 | S3のHeadBucketでバケットARNとリージョンus-east-1を取得 |
| タグの更新 | S3のGetBucketTaggingでVerification=updatedとCloudFormationの管理用タグを確認 |
| バケットの削除 | 削除後のS3のHeadBucketで404 Not Foundを確認 |
6. 考察
今回の検証では、実AWSの環境を変更せずに、CloudFormationテンプレートからS3バケットを作成し、更新・削除まで試せました。テンプレートの静的解析と組み合わせれば、構文や設定のチェックに加えて、リソースを操作した結果も事前に確認できます。
EmulatorをCI/CDパイプラインに組み込むことで、本番デプロイ前に気づける問題が増え、手戻りを減らせるのではないかと思いました。AIエージェントがテンプレートをレビュー・修正し、Emulatorで動作を確認する流れとも相性がよさそうです。こうした使い方は、今後試してみたいところです。
今回試したのは空のS3バケット1個とタグ更新です。他サービスや、リソース置換・ロールバック・変更セットなどの複雑な操作はまだ確認できていません。Emulatorで成功しても、実AWSでのデプロイ成功を保証するものではありません。公式ドキュメントでもIAMやリソースポリシーの評価は実AWSと異なると説明されているため、権限やセキュリティ設定は実AWSで確認する必要があります。
7. まとめ
AWS Emulator v1.0.343では、今回の最小テンプレートに限ればCloudFormationのCreateStack、DescribeStacks、UpdateStack、DeleteStackが動作しました。S3側の実体も確認できたため、単なる成功レスポンスの確認にとどまりません。
静的解析と組み合わせてCI/CDに組み込めば、本番デプロイ前の確認に役立ちそうです。今後は、より複雑なテンプレートや、AIエージェントによるレビューと組み合わせた検証も試してみたいと思います。