[AWS] How far can CDK/Terraform stacks run on AWS Emulator? [AWSEmulator]

This article is a machine translation of the contents of the following URL, which I wrote in Japanese:

【AWS】AWS EmulatorでCDK/Terraformのスタックはどこまで動くか【AWSEmulator】 #DevTools - Qiita

はじめに 2026年11月11日、AWSからAWS Emulatorが公式にリリースされました。AWS SDKやAWS CLIの呼び出しを、AWSアカウントなしで、ローカルやCI上のエミュレーターに向けられるツールです。公式は、実装されているAPIには有効な呼び出しにAW...

qiita.com

Introduction

On November 11, 2026, AWS officially released AWS Emulator. It is a tool that lets you point AWS SDK and AWS CLI calls at an emulator running locally or in CI, without an AWS account. According to AWS, for implemented APIs it returns the same result as AWS for valid calls and the same error for invalid ones, and APIs that are not implemented fail with 501. There is no additional charge.

If you are hearing about it for the first time, questions like these come up.

• Does it really behave the same as AWS?
• What works and what doesn't?
• Will my own IaC (CDK or Terraform) go through?

The third one is especially important in practice. The official documentation says that support for IaC tools varies by service.

"Fidelity for data plane APIs, and support for infrastructure as code tools such as AWS CloudFormation, Terraform, and the AWS CDK, varies by service."
Source: https://docs.aws.amazon.com/emulator/latest/userguide/fidelity.html

So in this article, with IaC compatibility as the main focus, I summarize the results of actually trying it on Windows 11 + Docker. To help readers who are new to the emulator get the overall picture, I also checked how the emulator itself behaves.

• Deploy resources with CDK in stages and tabulate how far it goes and where it stops
• Build an API with API Gateway + Lambda + DynamoDB and confirm that it works by actually calling it
• Check the emulator's behavior: errors, unimplemented APIs, authentication, running multiple instances, and the lifetime of state
• Try Terraform in the same way
• Compare the results with the fidelity data and known issues published by AWS

This article assumes basic knowledge of the AWS SDK, the AWS CLI, and CDK (or Terraform), as well as basic Docker operations.

What is AWS Emulator?

How to read the diagram: your code and tools go to different destinations depending on whether the environment variable AWS_ENDPOINT_URL is set. If it is not set, they go to real AWS. If you set it to https://127.0.0.1:9297, they go to the local emulator.

What are the benefits of using AWS Emulator?

Before the verification, let me organize what AWS Emulator improves. I matched the use cases described in posts by AWS-affiliated authors (the AWS News Blog, a guest post by Swami Sivasubramanian, an AWS executive, on Werner Vogels' blog, and an article from the AWS organization on DEV.to) with what I could confirm in this verification. The source names used in the table and the URLs I referred to are as follows. All of them were published on 2026-11-11.

The posts from AWS are all explanations from the provider. The right column of the table shows the results of trying each item once on Windows 11 + Docker, and I did not compare them with real AWS.

At the same time, the posts from AWS do not say that the emulator can do everything.

• They suggest keeping mocks for "the logic that you control" and using the emulator for the parts that depend on the behavior of AWS services (DEV.to)
• It does not evaluate IAM policies or resource-based policies the way AWS does, so do not use it for security testing (AWS News Blog)
• One emulator acts as a single account, and there is no cross-account or cross-Region behavior (AWS News Blog)

These benefits also depend on the fidelity of the services you use. Whether each benefit holds for your own configuration is something I check in the following steps.

How to read fidelity

AWS measures how closely the emulator matches AWS with "fidelity tests", and publishes the number of passed tests out of the total for each service with every release.

Scores can only be compared between the same versions of the fidelity tests.

Verification environment

The emulator is released several times a day, so the results depend on the verification date and the release.

Step 1: Start the emulator

I built the image from the official Dockerfile and started it with docker run. I used the Dockerfile as is (for x86_64; for Arm, change the rpm name to aarch64). A NOKEY warning about the rpm signature appeared during the build, but the build completed.

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"] 

docker build -t aws-emulator . docker run -d --name emu --memory=2g --memory-swap=2g -p 127.0.0.1:9297:9297 ` -v "$env:USERPROFILE\.aws\emulator:/home/emulator/.aws/emulator" ` aws-emulator -p 9297 --telemetry off 

This is the startup log (docker logs emu).

{"timestamp":"2026-11-11T22:33:58.891517Z","level":"INFO","fields":{"message":"aws-emulator emulator starting"},"target":"aws_emulator"} This emulator collects usage and error telemetry: disabled (via the embedding configuration) — to turn it back on, remove every opt-out setting and restart {"timestamp":"2026-11-11T22:33:58.944196Z","level":"INFO","fields":{"message":"request authentication enabled","credentials_file":"/home/emulator/.aws/emulator/9297/emulator_credentials"},"target":"aws_emulator_server"} {"timestamp":"2026-11-11T22:33:58.963607Z","level":"INFO","fields":{"message":"emulator server information","endpoint_url":"https://127.0.0.1:9297","health_check_url":"https://127.0.0.1:9297/__admin/health","config_file":"/home/emulator/.aws/emulator/9297/config","ca_file":"/home/emulator/.aws/emulator/9297/ca.pem","java_truststore_file":"/home/emulator/.aws/emulator/9297/truststore.p12"},"target":"aws_emulator_server"} {"timestamp":"2026-11-11T22:33:58.963668Z","level":"WARN","fields":{"message":"the emulator listens on 0.0.0.0, not loopback: other machines that can reach port 9297 can call it; bind 127.0.0.1 (-b 127.0.0.1) unless that is intended","bind_address":"0.0.0.0"},"target":"aws_emulator_server"} 

The log shows that telemetry is disabled, that request authentication is enabled, and that the endpoint is https://127.0.0.1:9297. The last warning about 0.0.0.0 appears because -b 0.0.0.0 in the Dockerfile makes the emulator listen on all addresses inside the container. On the host side, the port is published only to my own PC with -p 127.0.0.1:9297:9297, so it is not reachable from outside.

Next, I pointed the SDK and CLI at the emulator with environment variables, following the official procedure. The variables that can hold real credentials are removed.

$env:AWS_ENDPOINT_URL = "https://127.0.0.1:9297" $env:AWS_SHARED_CREDENTIALS_FILE = "$env:USERPROFILE\.aws\emulator\9297\emulator_credentials" $env:AWS_CONFIG_FILE = "$env:USERPROFILE\.aws\emulator\9297\config" $env:AWS_CA_BUNDLE = "$env:USERPROFILE\.aws\emulator\9297\ca.pem" $env:AWS_EC2_METADATA_DISABLED = "true" $env:AWS_DISABLE_HOST_PREFIX_INJECTION = "true" $env:AWS_REGION = "us-east-1" 

These are the results of the connectivity check.

The last row was different from what I expected. You cannot create a bucket with the name used in the official documentation examples. This is not a defect of the emulator: the S3 bucket naming rules reserve names that start with amzn-s3-demo- (source: https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucketnamingrules.html ). It also means that the emulator validates even this rule in the same way as AWS.

The official documentation gives the following points to watch out for.

• If you run tests in a shell where AWS_ENDPOINT_URL is not set, they call real AWS with whatever credentials are found
• If environment variables such as AWS_ACCESS_KEY_ID remain set, the emulator rejects the requests
• Publish the port in the form -p 127.0.0.1:9297:9297 (the short form exposes it to the whole network)

Step 2: Deploy with CDK in stages

I add resources to a single stack in stages with -c stage=N.

cdk bootstrap

cdk bootstrap aws://000000000000/us-east-1 succeeded in 17 seconds. The CDKToolkit stack that was created contains an S3 bucket, an ECR repository, IAM roles (five of them), and an SSM parameter, and I could also read the SSM parameter /cdk-bootstrap/hnb659fds/version.

Note: the combination of CDK CLI 2.1148.1 and aws-cdk-lib 2.276.0 failed, because the library requires CLI 2.1148.2, which had not been published yet. This is a CDK-side issue and unrelated to the emulator. In this article, I pinned the library to 2.275.0.

Results by stage

This is the output when I redeployed the stage 8 stack with no changes.

CdkSampleStack: deploying... [1/1] ✅ CdkSampleStack (no changes) ✨ Deployment time: 0s Outputs: CdkSampleStack.BucketName = cdksamplestack-bucket83908e77-db9d1636caba CdkSampleStack.FnAssetName = CdkSampleStack-FnAssetDC7A43AF-BEA29F2C2421 CdkSampleStack.FnName = CdkSampleStack-Fn9270CBC0-3ADA671FD9E8 CdkSampleStack.LogGroupName = CdkSampleStack-Lg419948D3-9E819B94EA09 CdkSampleStack.QueueUrl = https://sqs.us-east-1.amazonaws.com/000000000000/CdkSampleStack-Queue4A7E3555-148DCCAAE08B CdkSampleStack.SmArn = arn:aws:states:us-east-1:000000000000:stateMachine:CdkSampleStack-SM934E715A-EFE2C378FC2A CdkSampleStack.TableName = CdkSampleStack-TableCD117FA1-A02DF716D6D7 CdkSampleStack.TopicArn = arn:aws:sns:us-east-1:000000000000:CdkSampleStack-TopicBFC7AF6E-7C0061677BC0 

You can also check the contents of the deployed stack with list-stack-resources. At stage 8, all 18 resources in the template were CREATE_COMPLETE. However, as described above, the alarm does not appear in describe-alarms even though it is CREATE_COMPLETE.

$ aws cloudformation list-stack-resources --stack-name CdkSampleStack --query "StackResourceSummaries[].[ResourceType,ResourceStatus]" --output table --------------------------------------------------------- | ListStackResources | +-----------------------------------+-------------------+ | AWS::CloudWatch::Alarm | CREATE_COMPLETE | | AWS::S3::Bucket | CREATE_COMPLETE | | AWS::CDK::Metadata | CREATE_COMPLETE | | AWS::Lambda::Function | CREATE_COMPLETE | | AWS::Lambda::Function | CREATE_COMPLETE | | AWS::Logs::LogGroup | CREATE_COMPLETE | | AWS::IAM::Role | CREATE_COMPLETE | | AWS::Logs::LogGroup | CREATE_COMPLETE | | AWS::IAM::Role | CREATE_COMPLETE | | AWS::Logs::LogGroup | CREATE_COMPLETE | | AWS::SQS::Queue | CREATE_COMPLETE | | AWS::SNS::Subscription | CREATE_COMPLETE | | AWS::SQS::QueuePolicy | CREATE_COMPLETE | | AWS::Events::Rule | CREATE_COMPLETE | | AWS::StepFunctions::StateMachine | CREATE_COMPLETE | | AWS::IAM::Role | CREATE_COMPLETE | | AWS::DynamoDB::Table | CREATE_COMPLETE | | AWS::SNS::Topic | CREATE_COMPLETE | +-----------------------------------+-------------------+ $ aws cloudwatch describe-alarms { "MetricAlarms": [], "CompositeAlarms": [], "LogAlarms": [] } 

Where it stopped, or what was noteworthy

I did not check how the same code behaves on real AWS, so I cannot say whether the Lambda inline code behavior is a difference in the emulator.

Checking that it works: does HelloEmulator come back?

Even if a deployment succeeds, that does not mean it works. So I confirmed that Lambda returns HelloEmulator and that it can be called through API Gateway.

This is the Lambda code (lambda/hello.js).

exports.handler = async () => ({ statusCode: 200, headers: { 'Content-Type': 'text/plain' }, body: 'HelloEmulator', }); 

In CDK, this Lambda is connected to a LambdaRestApi, with only a single GET defined on the root (/).

This is an example curl command. To call API Gateway, you send the request to the emulator's single endpoint and specify the target API with the Host header.

curl.exe -i --cacert $env:AWS_CA_BUNDLE ` -H "Host: <restApiId>.execute-api.us-east-1.amazonaws.com" ` https://127.0.0.1:9297/prod/ 

HTTP/1.1 200 OK content-type: text/plain content-length: 13 x-amzn-requestid: 863869a5-ede1-4e56-bf04-151a017052da date: Wed, 11 Nov 2026 22:58:41 GMT HelloEmulator 

If you open the URL that CDK outputs (https://<id>.execute-api.us-east-1.amazonaws.com/prod/) as is, the request goes to real AWS. To send it to the emulator, connect to 127.0.0.1 and specify the API with the Host header, as shown above.

Step 3: Check how the emulator behaves

So far, the question was whether the IaC can be deployed. For readers who are new to AWS Emulator, I also checked the behavior of the emulator itself from several angles. All the examples below were run in a shell with the environment variables from Step 1 set.

1. Point your code at the emulator without changing it

You do not write an endpoint or credentials in the application code; the destination is decided by environment variables alone. The following Python (boto3) is code that would work as is on real AWS if you removed the environment variables.

import boto3, uuid s3 = boto3.client("s3"); ddb = boto3.client("dynamodb"); sqs = boto3.client("sqs") sfx = uuid.uuid4().hex[:8] s3.create_bucket(Bucket=f"demo-{sfx}") s3.put_object(Bucket=f"demo-{sfx}", Key="a.txt", Body=b"hello") print(s3.get_object(Bucket=f"demo-{sfx}", Key="a.txt")["Body"].read()) ddb.create_table(TableName=f"demo-{sfx}", BillingMode="PAY_PER_REQUEST", AttributeDefinitions=[{"AttributeName": "id", "AttributeType": "S"}], KeySchema=[{"AttributeName": "id", "KeyType": "HASH"}]) ddb.put_item(TableName=f"demo-{sfx}", Item={"id": {"S": "1"}}) 

These are the results (a single measurement, on local Docker, in milliseconds).

AWS says that calls come back in milliseconds. In this measurement, too, a single call took from a few milliseconds to the low twenties of milliseconds. I did not compare this with real AWS.

2. Invalid calls return errors in the AWS format

Unlike a mock that simply succeeds when you call it, the implemented APIs run validation and produce errors. I have not confirmed that they match AWS exactly, but the error codes are in the same format as AWS.

3. Unimplemented APIs fail clearly

AWS says that unimplemented APIs return HTTP 501. When I tried 27 APIs, 4 of them returned 501.

Responding without an error does not mean the behavior is correct. Still, it is an advantage of 501 that an unimplemented API does not silently succeed and a test can notice immediately as a failure.

4. Authentication is required and changes with every startup

According to the official documentation, this design prevents other web pages or local programs from calling the emulator without your knowledge.

5. Multiple emulators are independent

I started a second emulator (9298) on a different port and checked.

If you start one emulator per agent, per CI job, or per branch, their resources are not visible to each other.

6. State lives in memory only and is lost on restart

The restart completed in 2 seconds. You can start from an initial state every time, but if you restart in the middle of a test, everything is lost. There is no persistence (as stated in the official documentation).

7. An application that spans services works (API Gateway → Lambda → DynamoDB)

I built a small API that registers and retrieves items. Lambda saves the value received by POST into DynamoDB, and GET retrieves it.

const { DynamoDBClient, PutItemCommand, GetItemCommand } = require('@aws-sdk/client-dynamodb'); const ddb = new DynamoDBClient({}); exports.handler = async (event) => { if (event.httpMethod === 'POST') { const { id, text } = JSON.parse(event.body || '{}'); await ddb.send(new PutItemCommand({ TableName: process.env.TABLE_NAME, Item: { id: { S: id }, text: { S: text } } })); return { statusCode: 201, body: JSON.stringify({ saved...