使用 AWS 模拟器测试 Terraform
Testing Terraform with AWS Emulator

原始链接: https://notes.hatedabamboo.me/terraform-tests-with-aws-emulator/

文章解释 Terraform 计划可能遗漏真实 AWS API 约束,导致 apply 失败。AWS Emulator 通过提供短暂、真实的 AWS 风格 API 用于本地和 CI 测试来解决此问题。它可作为 Docker 容器或安装包运行,并配置 Terraform 将服务指向模拟器端点。计划后,可对模拟器运行 apply,在接触真实 AWS 前捕获 API 级别错误。该流程也适用于 CI:安装/启动模拟器,设置凭据/证书,然后 init、validate、plan 和 apply。一个故意演示显示无效的 DynamoDB 表名能通过 plan 但 apply 失败,证明模拟器的价值。限制包括无法有效检查 IAM 策略、服务覆盖不完整且部分返回 NotImplemented,以及遥测可禁用。总体而言,AWS Emulator 在 plan 和生产 apply 之间增加更安全的模拟 apply 步骤。

Hacker News 上一个讨论“使用 AWS Emulator 测试 Terraform”的帖子。评论者指出,emulator 仅复制 API,并非真实 AWS 服务的完整逻辑和行为,因此在其中测试与真实使用不同。一位评论者补充,emulator 也不模拟 IAM 权限,限制了 Terraform 的权限测试。
相关文章

原文

Terraform plan passes and shows all green and all the necessary resource changes. You trigger apply and... the job fails with some obscure error that a resource can't be changed. You open another pull request and try again. And perhaps you encounter an error again. Sounds familiar? I bet it does. I encountered issues like this so many times I'm afraid to count. But recently AWS released a new tool called Emulator that emulates actual AWS API endpoints. And it should be great for tasks just like that!

Title image

Defining the problem

The problem with the difference between plan and apply jobs is that plan can't possibly emulate every actual API call against a live infrastructure. It's a safe assumption based on the static declarations we put into it – the order of application, the necessary parameters, the proper configuration values. These mock calls can't know for a fact that you already have a resource in AWS called "my-bucket-asdasdasd" or that you're trying to upgrade a PostgreSQL RDS instance from version 14 to version 18 without an explicit "apply immediately" flag. One may argue that one can always try to apply changes locally, but this kinda undermines the whole automation workflow. So what is the answer?

There are multiple tools that can emulate AWS services either partially or in full, but what they lack is the actual knowledge of the service architecture. It may be similar, but it won't be authentic, and sometimes this small difference may cause a lot of problems. After all, what can be the closest to an AWS API, if not the same AWS API, but ephemeral?

AWS Emulator

The benefit of the AWS Emulator is that it's a self-contained binary (or Docker container) that can be utilized locally or in a CI workflow. This means the usual "Plan > Apply" terraform workflow changes to "Plan > Apply against mock AWS infrastructure to test the plan > Apply on actual AWS Infrastructure". This means slightly longer jobs, but if you're like me and apply jobs run on commits to the main branch after a PR, this saves you the hassle of creating a new branch just to fix the issue.

Running Terraform against local AWS Emulator

Let's start with a local setup and see how we can utilize AWS Emulator with the actual Terraform code. All code is available in my example GitHub repository.

First up, installation. You can either install aws-emulator via package manager, or build it with Docker. I'll use Docker to keep my system clear of yet another package:

bash$ docker build -t aws-emulator .
$ docker images
IMAGE                 ID             DISK USAGE   CONTENT SIZE   EXTRA
aws-emulator:latest   3c8fdb957b45       1.24GB             0B          
$ docker run --rm -d -p 9297:9297 aws-emulator -a off
dcc416f234aaa3ec2966c9e8dcde7870f8d03057ec8a465cb8960617af82e501
$ docker logs dcc416f234aaa3ec2966c9e8dcde7870f8d03057ec8a465cb8960617af82e501
{"timestamp":"2026-11-12T14:51:16.261883Z","level":"INFO","fields":{"message":"aws-emulator emulator starting"},"target":"aws_emulator"}
This emulator collects usage and error telemetry: enabled (on by default; opt out any time); disable with EMULATOR_TELEMETRY=off or [telemetry] enabled = false in /home/emulator/.aws/emulator/config.toml
{"timestamp":"2026-11-12T14:51:16.270635Z","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-12T14:51:16.270655Z","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"}
{"timestamp":"2026-11-12T14:51:16.270659Z","level":"WARN","fields":{"message":"request authentication is off: the emulator accepts any request, signed or not; start it with -a on to require signatures","bind_address":"0.0.0.0"},"target":"aws_emulator_server"}

And it's up and running! In the example above I set the container to live without limits (official AWS documentation proposes to set memory and swap limits: --memory=2g --memory-swap=2g, but for local that's fine). I also disabled authorization (flag -a off) to simplify things a bit.

To be sure aws-emulator is up and running, let's query the admin endpoint:

bash$ curl -sk https://127.0.0.1:9297/__admin/health
ok

Okay, fake AWS is live, let's deploy some infrastructure!

I created an example AWS stack for Terraform and will use it in this article. First, let's configure Terraform to act against aws-emulator and not real AWS APIs. providers.tf will look like this:

hclprovider "aws" {
  access_key = var.access_key
  secret_key = var.secret_key
  region     = var.region

  insecure = true 

  s3_use_path_style = true   

  
  skip_credentials_validation = true
  skip_metadata_api_check     = true
  skip_requesting_account_id  = true
  skip_region_validation      = true

  
  endpoints {
    ec2        = var.emulator_endpoint
    lambda     = var.emulator_endpoint
    iam        = var.emulator_endpoint
    sts        = var.emulator_endpoint
    cloudwatch = var.emulator_endpoint
    logs       = var.emulator_endpoint
    events     = var.emulator_endpoint
    sns        = var.emulator_endpoint
  }

  default_tags {
    tags = var.tags
  }
}

The difference between actual live infrastructure and a fake one is that we set up a bunch of flags to allow insecure connections (perhaps turning authentication off wasn't actually simpler?) and we set up an endpoint for each service we use in the setup to an emulator endpoint, which lives in the local Docker container:

hcl
variable "emulator_endpoint" {
  description = "Base URL of the AWS Emulator"
  type        = string
  default     = "https://127.0.0.1:9297"
}
...

The rest of the configuration is as usual: resources, variables, modules (if any). Just what your project has.

Let's proceed and test our setup. (I'll omit full terraform output otherwise this article would be 3 kilometers long)

bash$ cd terraform/
$ terraform init
Initializing the backend...
...
Terraform has been successfully initialized!
...
$ terraform plan
...
Plan: 15 to add, 0 to change, 0 to destroy.

Changes to Outputs:
  + alarm_name          = "ttwae-lambda-errors"
  + event_rule_arn      = (known after apply)
  + lambda_function_arn = (known after apply)
  + security_group_id   = (known after apply)
  + sns_topic_arn       = (known after apply)
  + subnet_id           = (known after apply)
  + vpc_id              = (known after apply)

Plan works! That's good to see, but not what we're here for. Still, a good sign. Now for the real test.

bash$ terraform apply --auto-approve
...
Apply complete! Resources: 15 added, 0 changed, 0 destroyed.

Outputs:

alarm_name = "ttwae-lambda-errors"
event_rule_arn = "arn:aws:events:us-east-1:000000000000:rule/ttwae-schedule"
lambda_function_arn = "arn:aws:lambda:us-east-1:000000000000:function:ttwae-worker"
security_group_id = "sg-00000000000000085"
sns_topic_arn = "arn:aws:sns:us-east-1:000000000000:ttwae-alarms"
subnet_id = "subnet-00000000000000089"
vpc_id = "vpc-00000000000000080"

And apply also works! Amazing!

Sadly, the running aws-emulator container doesn't show in its logs which API requests it receives and what's happening under the hood, but I guess the tool is good enough as it is.

When you're done, stop the container:

bash$ docker stop dcc416f234aaa3ec2966c9e8dcde7870f8d03057ec8a465cb8960617af82e501

A container started with --rm removes itself after stopping, so no additional cleanup is needed. And as for the emulator -- it stores its state in memory, so each container restart drops all record of previous actions and any stale state.

Running Terraform against AWS Emulator in CI pipeline

Now for the real test: can we wrap the desired logic inside a CI pipeline? Let's think.

For successful invocation in the pipeline we will need almost everything the same, but we will be limited by time (the faster -- the better, and overall reasonable timeouts) and resources.

The workflow with terraform apply against aws-emulator is shown down below. For it I decided to try out package manager installation (builders are ephemeral anyway) and proper authentication. Full workflow with actual successful runs can be found in the example GitHub repository.

yaml---
name: terraform-against-emulator
on:
  push:
    branches: [main]
permissions:
  contents: read
jobs:
  terraform:
    runs-on: ubuntu-latest
    env:
      EMULATOR_PORT: "9297"
      
      
      
      TF_VAR_access_key: ""
      TF_VAR_secret_key: ""
      TF_VAR_insecure: "false"

    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 
      - name: Install the 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 -v
      - name: Start the emulator with signature checks on
        run: |
          nohup aws-emulator > /tmp/aws-emulator.log 2>&1 &
          echo "Waiting for the emulator to answer..."
          CA="$HOME/.aws/emulator/${EMULATOR_PORT}/ca.pem"
          for i in $(seq 30); do
            if [ -f "$CA" ] && curl -sf --cacert "$CA" \
                "https://127.0.0.1:${EMULATOR_PORT}/__admin/health" >/dev/null; then
              echo "Emulator is ready."
              exit 0
            fi
            sleep 1
          done
          echo "Emulator did not become ready." >&2
          cat /tmp/aws-emulator.log >&2
          exit 1
      - name: Point Terraform at the emulator credentials and certificate
        run: |
          DIR="$HOME/.aws/emulator/${EMULATOR_PORT}"
          {
            echo "AWS_SHARED_CREDENTIALS_FILE=$DIR/emulator_credentials"
            echo "AWS_CONFIG_FILE=$DIR/config"
            echo "AWS_CA_BUNDLE=$DIR/ca.pem"
            echo "AWS_REGION=us-east-1"
            echo "AWS_DEFAULT_REGION=us-east-1"
            echo "AWS_EC2_METADATA_DISABLED=true"
            echo "AWS_DISABLE_HOST_PREFIX_INJECTION=true"
          } >> "$GITHUB_ENV"
      - uses: hashicorp/setup-terraform@dfe3c3f87815947d99a8997f908cb6525fc44e9e 
        with:
          terraform_wrapper: false
      - run: terraform -chdir=terraform init -input=false
      - run: terraform -chdir=terraform validate
      - run: terraform -chdir=terraform plan -input=false
      - run: terraform -chdir=terraform apply -auto-approve -input=false

This is a crude excerpt of the actual glorious workflow file that outlines the most important steps: emulator installation, terraform setup, plan and apply. On the example terraform architecture the whole pipeline took 1m25s, which is okay in my opinion, but there is room for improvement: sprinkle some caching on top, leave validation, format check for local hooks, etc.

Running a deliberately failing apply job

It's always nice when code someone wrote on the internet works from the start after you copy-paste it onto your machine. That's why I always run the described processes myself -- building, testing, fixing, retrying -- before publishing an article. But showing only the positive scenarios creates a false sense of trust in the tool.

Let's break something on purpose.

In the example codebase I added a variable that, when enabled, makes the stack try to deploy a resource with an erroneous declaration. It will pass the plan job, but fail on apply.

hclvariable "enable_failure_demo" {
  description = "Create a DynamoDB table with an invalid name."
  type        = bool
  default     = false
}

Setting this variable to true at runtime will break our stack. Let's see:

bash$ cd terraform/
$ terraform init
Initializing the backend...
...
$ terraform plan -var 'enable_failure_demo=true'
...
Plan: 16 to add, 0 to change, 0 to destroy.

Changes to Outputs:
...
  + failure_demo_table_arn = (known after apply)
...
$ terraform apply -auto-approve -var 'enable_failure_demo=true'
...
╷
│ Error: creating AWS DynamoDB Table (ab): operation error DynamoDB: CreateTable, https response error StatusCode: 400, RequestID: 4TLD3XUB94783KNA4C76L8BEZ26UU8LS4IBN2IEKZJLAK4NMVTQ4, api error ValidationException: 1 validation error detected: Value 'ab' at 'tableName' failed to satisfy constraint: Member must have length greater than or equal to 3
│
│   with aws_dynamodb_table.bad_name[0],
│   on dynamodb.tf line 10, in resource "aws_dynamodb_table" "bad_name":
│   10: resource "aws_dynamodb_table" "bad_name" {
│

And there we have it. The exact issue that arises only against actual API calls and not during a plan job.

For scenarios exactly like this, the emulator is priceless.

Limitations and considerations

AWS Emulator is AWESOME. I'm rarely that excited about new tools lately (mostly because almost all of them are near/about AI), but this one is just so good and scratches that exact itch I felt for so long.

Still, it's far from perfect.

For starters, it can't effectively emulate IAM policies and permission checks. This is a bummer, because permission validation is such a crucial step for production-ready security. Here's hoping that the tool will evolve further and it will be included in future updates.

Second, as a tool still a work-in-progress, its capabilities are quite limited. Even while writing the article I encountered several cases of 501 NotImplemented. It complicates things a bit if your infrastructure setup is huge and has a lot of quirks and weird configurations and super new services. Still, AWS releases new versions quite often, and they're quite open about Emulator limitations, which is nice.

And last, but not least, is telemetry. AWS is explicit that it gathers telemetry and what this telemetry includes. This is honest behaviour and I like that approach. They even allow you to disable the telemetry, which further increases my trust in this tool. I understand the rationale behind this functionality (the tool is actively developed, they need the data to understand usage patterns and what goes wrong), but in the age of constant surveillance from Big Tech at every corner it still raises a slight concern. But then again, for the ultra-paranoid folks the code is open source and can be rebuilt with telemetry torn out of it.


Reply to this post ✉️

联系我们 contact @ memedata.com