[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: id }) };
  }
  const id = event.pathParameters.k;
  const r = await ddb.send(new GetItemCommand({ TableName: process.env.TABLE_NAME, Key: { id: { S: id } } }));
  return r.Item ? { statusCode: 200, body: JSON.stringify({ id, text: r.Item.text.S }) } : { statusCode: 404, body: '{"message":"not found"}' };
};

To call the emulator's DynamoDB from inside Lambda, I had to specify environment variables explicitly. The emulator does not automatically pass an endpoint or credentials to the Lambda execution environment. These are the values I confirmed.

In the first deployment, I forgot to grant permissions to DynamoDB (grantReadWriteData). The emulator then detected the missing permissions of the Lambda role and returned 500.

AccessDeniedException: User: arn:aws:sts::000000000000:assumed-role/CdkSampleStack-AppServiceRole.../CdkSampleStack-App... is not authorized to perform: dynamodb:PutItem on resource: arn:aws:dynamodb:us-east-1:000000000000:table/... because no identity-based policy allows the dynamodb:PutItem action

These are the results after adding the permissions and redeploying.

With this, I confirmed that the whole flow of request → API Gateway → Lambda → DynamoDB → retrieval works. Here is the flow as a diagram.

However, AWS asks you not to use the emulator for security tests such as IAM policies. The emulator did detect the permission error this time, but its decision is not necessarily the same as AWS's (AWS states that policies are evaluated differently from AWS).

Step 4: Try Terraform

I pointed two resources, an S3 bucket and a DynamoDB table, at the emulator using only the AWS_ENDPOINT_URL environment variable. On the provider side, I set skip_credentials_validation, skip_requesting_account_id, skip_metadata_api_check, and s3_use_path_style.

This diff is recorded as a known issue in the official repository (Step 6). To isolate the cause, I ran describe-table directly, and OnDemandThroughput came back with MaxReadRequestUnits: -1 and MaxWriteRequestUnits: -1. The provider treats the fact that an unset item comes back with this value as a diff and tries to update it, but since the update is empty, UpdateTable fails; that is my interpretation. I have not confirmed how this item is returned for an unset table on real AWS.

This is the output when I ran terraform plan right after terraform apply.

$ terraform plan
aws_dynamodb_table.t: Refreshing state... [id=tf-emu-sample-table]
aws_s3_bucket.b: Refreshing state... [id=tf-emu-sample-bucket-20261112]

Terraform will perform the following actions:

  # aws_dynamodb_table.t will be updated in-place
  ~ resource "aws_dynamodb_table" "t" {
        id                          = "tf-emu-sample-table"
        name                        = "tf-emu-sample-table"
        tags                        = {}
        # (13 unchanged attributes hidden)

      - on_demand_throughput {
          - max_read_request_units  = -1 -> null
          - max_write_request_units = -1 -> null
        }

        # (3 unchanged blocks hidden)
    }

Plan: 0 to add, 1 to change, 0 to destroy.

If you run terraform apply once more in this state, it fails with the following error.

Error: updating AWS DynamoDB Table (tf-emu-sample-table): operation error DynamoDB: UpdateTable, https response error StatusCode: 400, RequestID: (omitted), api error ValidationException: At least one of ProvisionedThroughput, BillingMode, UpdateStreamEnabled, GlobalSecondaryIndexUpdates, SSESpecification, ReplicaUpdates, MultiAccountReplicaReady, ReplicaTransitRoleArn, MultiRegionConsistency, DeletionProtectionEnabled, OnDemandThroughput, WarmThroughput or TableClass is required

Step 5: Compare with the fidelity scores

Release v1.0.322 comes with the score data scores.json.gz (commit 7753983, aggregated at 2026-11-11 00:09 UTC). It contains the result (pass/fail/skipped) of each fidelity test and the list of services. It is not a table compiled by AWS, so in this article I recounted the results for each service.

• Overall: 24,243 of 42,857 tests (excluding skipped) passed (56.6%)
• How I counted: for tests that target only one service, I counted pass/total per service (tests that span multiple services are not included)
• Note: scores can only be compared between the same versions of the tests (as stated in the official documentation). My aggregation is not an official score table

Even where the score is low, the simple stacks in this run worked. I think the 16% for CloudFormation is because many of its tests target complex configurations (spanning services, or involving rollbacks and updates), but I have not checked the breakdown. A low ratio does not necessarily mean your configuration will not work, so the reliable approach is to try the range of APIs you actually use.

Step 6: Compare with known issues in the official repository

In the issues/ directory of aws/aws-emulator, each known difference is a separate file. They are divided into two folders: things-that-do-not-work/ (unresolved) and things-that-now-work/ (resolved). I checked whether the differences I found in this verification were already recorded.

This is how I searched.

• I sparse-checked-out only issues/ (HEAD is commit 7753983, the same as release v1.0.322 that I used)
• There are 6,544 unresolved and 12,708 resolved files
• I ran a full-text search over all files with keywords related to the differences I found, and read the matching files

These are the results.

What I can read from this:

• Three of the differences I found were already recorded in the official repository. For two of them (on_demand_throughput and statementId), the issues describe the AWS-side behavior ("CloudFormation keeps the ID within 100 characters" and "OnDemandThroughput is omitted"). I have not confirmed this on real AWS; this is what the issues state.
• For the remaining three (inline code, Function URL, and duplicate stage names), the full-text search found no match. They may be unreported. AWS accepts reports of differences through GitHub Issues.

Notes:

• The issue files are records of differences raised from test runs, and they were written against a commit at a certain point in time (each file contains a note showing that commit). The same problem does not necessarily occur in the current release.
• In fact, there was an example that showed how outdated they can be. The file 20261106T052537Z-apigatewayv2-lambda-logs-the-nodejs22-x-lambda-runtime.md in the unresolved folder says that "the nodejs22.x runtime does not bundle the AWS SDK v3", but in this release I could load @aws-sdk/client-dynamodb from Lambda and it worked. Even if an issue is in the unresolved folder, it may already be fixed.
• A full-text search depends on keywords. Issues written with wording that does not match my search terms may have been missed.

How to use it in practice

Conclusion

Even right after its release, AWS Emulator could run a wider range than I had expected, from CDK deployments to processing that spans API Gateway, Lambda, and DynamoDB. On the other hand, even when the CloudFormation status was successful, there were resources that were not actually usable, like the alarm. Instead of judging by the success of the deployment alone, checking the behavior of the created resources is a prerequisite for operating it. It is well suited to integration tests in CI and to environments where AI agents can safely experiment, while permission checks such as IAM still need to be done on real AWS. The emulator is updated several times a day, so the differences I confirmed in this article may change in the future. If you try it with your own configuration and find a difference that is not in the official records, reporting it through GitHub Issues leads to improvements. Note that all the verification was done on the emulator, and I did not compare it with real AWS.

References

• AWS Emulator is now available for building and testing AWS applications locally (2026-11-11) https://aws.amazon.com/about-aws/whats-new/2026/11/aws-emulator-now-available/
• AWS Emulator documentation https://docs.aws.amazon.com/emulator
• Fidelity in AWS Emulator https://docs.aws.amazon.com/emulator/latest/userguide/fidelity.html
• Pointing your AWS SDK at AWS Emulator https://docs.aws.amazon.com/emulator/latest/userguide/point-sdk-to-emulator.html
• Security in AWS Emulator https://docs.aws.amazon.com/emulator/latest/userguide/security.html
• Getting started with Docker https://docs.aws.amazon.com/emulator/latest/userguide/getting-started-docker.html
• aws/aws-emulator (GitHub) https://github.com/aws/aws-emulator
• aws/aws-emulator release v1.0.322 (with the fidelity data scores.json.gz attached) https://github.com/aws/aws-emulator/releases/tag/v1.0.322
• Test your applications against AWS locally with AWS Emulator (AWS News Blog, 2026-11-11) https://aws.amazon.com/blogs/aws/test-your-applications-against-aws-locally-with-aws-emulator/
• AWS Emulator and the engineer's job when agents write the code (All Things Distributed, 2026-11-11) https://www.allthingsdistributed.com/2026/11/aws-emulator-and-the-engineers-job-when-agents-write-the-code.html
• How emulators might catch what you might miss (DEV.to, AWS organization, 2026-11-11) https://dev.to/aws/how-emulators-might-catch-what-you-might-miss-34hd
• General purpose bucket naming rules (Amazon S3) https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucketnamingrules.html