AWS EmulatorにTerraformでS3とSQSを作る方法
AWS Emulator を手元で動かすと、Terraform の terraform apply で、AWS のアカウントなしに S3 のバケットと SQS のキューを作れます。インフラのコード(IaC)を本物の AWS に反映する前に、ローカル環境や CI で plan と apply を通して確かめたいときの手順です。ただし、検証した時点で最新だった AWS プロバイダー 6.73.0 では、S3 バケットの作成がエラーで止まりました。この記事では、その理由と、プロバイダーのバージョンを指定して回避する方法を、検証環境で実行したコマンドと出力をもとに説明します。
検証環境は Ubuntu 24.04(x86_64)、AWS Emulator 1.0.487(2026年11月17日リリース)、Terraform 1.17.2、AWS プロバイダー 6.22.1 と 6.73.0、AWS CLI 2.40.4 です。AWS のアカウントと認証情報は使っていません。本物の AWS に同じ設定を apply したときの動き(料金、IAM の権限の判定、作成にかかる時間)は確かめていません。検証環境からは Terraform Registry に接続できなかったため、AWS プロバイダーは releases.hashicorp.com からダウンロードし、SHA256 のチェックサムを確かめてから、Terraform のローカルのディレクトリからプロバイダーを入れる設定(filesystem_mirror)で入れました。Terraform は HTTPS のプロキシを使わない設定で実行しています。エミュレーターのアカウントIDは12桁の0で、出力の中では <12桁のアカウントID> に置き換えています(あとで出てくるホスト名の先頭の、0が12個並んだ部分も同じ値です)。
エミュレーターを起動して、Terraform を向ける
AWS Emulator は、AWS の API を手元で受け付けるエミュレーターです。公式ドキュメントによると、AWS のアカウントは要らず、リクエストは AWS に送られません。
入れ方は別の記事「AWS EmulatorをUbuntuに入れて使い始める方法」で詳しく扱っています。ここでは、Linux 向けの手順にある Debian パッケージを、gpg で署名を確かめてから入れました。私は root で作業したので sudo を付けていませんが、下のコマンドでは一般のユーザー向けに付けています。起動の -t off は、既定で AWS に送られる利用状況のデータ(テレメトリー)を止める指定です。
curl -fsSLO https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/latest/aws-emulator_amd64.deb
sudo apt-get install -y ./aws-emulator_amd64.deb
aws-emulator -t off
エミュレーターはその端末で動き続けるので、Terraform は別の端末で実行します。その端末で、公式ドキュメントにある環境変数を設定します。
export AWS_ENDPOINT_URL=https://127.0.0.1:9297
export AWS_SHARED_CREDENTIALS_FILE=~/.aws/emulator/9297/emulator_credentials
export AWS_CONFIG_FILE=~/.aws/emulator/9297/config
export AWS_CA_BUNDLE=~/.aws/emulator/9297/ca.pem
export AWS_EC2_METADATA_DISABLED=true
export AWS_DISABLE_HOST_PREFIX_INJECTION=true
export AWS_REGION=us-east-1
export AWS_DEFAULT_REGION=us-east-1
unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN AWS_PROFILE
Terraform の AWS プロバイダーも、この環境変数を読みます。プロバイダーのドキュメントには、リージョンを AWS_REGION、設定ファイルと認証情報のファイルを AWS_CONFIG_FILE と AWS_SHARED_CREDENTIALS_FILE、証明書を AWS_CA_BUNDLE から読むと書かれています。送り先も、エンドポイントを変える方法のガイドのとおり、AWS_ENDPOINT_URL でまとめて変えられます。そのため、provider "aws" {} の中には何も書かずに済みました。
公式ドキュメントでは、AWS_ENDPOINT_URL が設定されていないシェルでコマンドを実行すると、見つかった認証情報で本物の AWS に送られると注意しています。本物の認証情報があるマシンでは、上の環境変数をすべて設定した端末で terraform apply を実行してください。
エミュレーターに届いているかは、AWS CLI で確かめられます。ARN の最後が user/emulator なら、エミュレーターが答えています。起動した直後は、バケットもキューもありません。
$ aws sts get-caller-identity --query Arn --output text
arn:aws:iam::<12桁のアカウントID>:user/emulator
$ aws s3api list-buckets --query 'Buckets[].Name'
[]
$ aws sqs list-queues
新しい AWS プロバイダーでは、S3 バケットの作成が止まる
まず、検証した時点で最新だった AWS プロバイダー 6.73.0 で、バケットを1つだけ作りました。
terraform {
required_providers {
aws = {
source = "hashicorp/aws"
version = "6.73.0"
}
}
}
provider "aws" {}
resource "aws_s3_bucket" "uploads" {
bucket = "example-uploads"
}
terraform apply は、4秒ほどでエラーになりました(出力の最後の部分です)。
$ terraform apply -auto-approve
(略)
Plan: 1 to add, 0 to change, 0 to destroy.
aws_s3_bucket.uploads: Creating...
Error: listing tags for S3 (Simple Storage) Bucket (example-uploads): operation error S3 Control: ListTagsForResource, https response error StatusCode: 0, RequestID: , HostID: , request send failed, Get "https://000000000000.127.0.0.1:9297/v20180820/tags/arn%3Aaws%3As3%3A%3A%3Aexample-uploads": dial tcp: lookup 000000000000.127.0.0.1: no such host
with aws_s3_bucket.uploads,
on main.tf line 12, in resource "aws_s3_bucket" "uploads":
12: resource "aws_s3_bucket" "uploads" {
バケットそのものは、エミュレーターにできていました。Terraform の state にも記録されていました。
$ aws s3api list-buckets --query 'Buckets[].Name'
[
"example-uploads"
]
$ terraform state list
aws_s3_bucket.uploads
エラーになったのは、作ったバケットのタグを読むところです。送り先が 127.0.0.1 ではなく、先頭にアカウントIDの付いた 000000000000.127.0.0.1 になっていて、このホスト名を名前解決できずに失敗しています。

AWS プロバイダーの CHANGELOG の 6.23.0 によると、このバージョンから aws_s3_bucket は、タグの読み書きに S3 Control の API(ListTagsForResource など)を使います。CHANGELOG では、s3:ListTagsForResource などの権限がないときは、それまでと同じ S3 の GetBucketTagging などに切り替えると説明しています。一方、AWS Emulator の公式ドキュメントのSDK が送り先のホスト名を変える場合の説明には、S3 Control のリクエストは SDK が必ずアカウントIDをホスト名に入れるため、エミュレーターに届かないと書かれています。AWS_DISABLE_HOST_PREFIX_INJECTION を設定していても、この付け足しは止まりませんでした。
Terraform のデバッグログ(TF_LOG=DEBUG)で、タグを読むリクエストを比べると、違いがはっきり出ました。6.22.1 は GetBucketTagging を 127.0.0.1 に、6.73.0 は S3 Control/ListTagsForResource を 000000000000.127.0.0.1 に送っていました。
同じ現象は、AWS Emulator の GitHub に issue #56 として報告されています。この記事を書いた時点では open のままで、回避策としてプロバイダーを 6.23.0 より前に固定する方法が挙がっています。
プロバイダーを 6.23.0 より前にして、バケットとキューを作る
version を "< 6.23.0" にすると、Terraform は条件に合うもののうち、いちばん新しいもの(ここでは 6.22.1)を選びます(Terraform のバージョンの条件の書き方)。この設定で、S3 のバケットと SQS のキューを作りました。
terraform {
required_providers {
aws = {
source = "hashicorp/aws"
version = "< 6.23.0"
}
}
}
provider "aws" {}
resource "aws_s3_bucket" "uploads" {
bucket = "example-uploads"
force_destroy = true
tags = {
Env = "local"
}
}
resource "aws_sqs_queue" "jobs" {
name = "example-jobs"
visibility_timeout_seconds = 60
message_retention_seconds = 86400
tags = {
Env = "local"
}
}
output "bucket_name" {
value = aws_s3_bucket.uploads.bucket
}
output "queue_url" {
value = aws_sqs_queue.jobs.url
}
force_destroy = true は、中にオブジェクトが残っていても terraform destroy でバケットを消せるようにする指定です。あとでファイルを1つ置いてから消すので付けました。
terraform init で 6.22.1 が入りました。Terraform の出力は長いので、ここからは必要な行だけを抜き出して載せます。(unauthenticated) は、Terraform のソースコードによると、署名などによる確認の結果がないときの表示です。ここでは、ローカルのディレクトリに置く前に、SHA256 のチェックサムを確かめています。
$ terraform init
- Installing hashicorp/aws v6.22.1...
- Installed hashicorp/aws v6.22.1 (unauthenticated)
Terraform has been successfully initialized!
terraform plan で2つが作られる予定であることを確かめてから、terraform apply を実行しました。
$ terraform apply -auto-approve
(略)
Plan: 2 to add, 0 to change, 0 to destroy.
(略)
aws_sqs_queue.jobs: Creating...
aws_s3_bucket.uploads: Creating...
aws_s3_bucket.uploads: Creation complete after 0s [id=example-uploads]
aws_sqs_queue.jobs: Still creating... [00m10s elapsed]
aws_sqs_queue.jobs: Still creating... [00m20s elapsed]
aws_sqs_queue.jobs: Creation complete after 25s [id=https://sqs.us-east-1.amazonaws.com/<12桁のアカウントID>/example-jobs]
Apply complete! Resources: 2 added, 0 changed, 0 destroyed.
Outputs:
bucket_name = "example-uploads"
queue_url = "https://sqs.us-east-1.amazonaws.com/<12桁のアカウントID>/example-jobs"
バケットはすぐにできましたが、キューは25秒かかりました。これはエミュレーターが遅いのではなく、プロバイダーの待ち方によるものです。プロバイダーのソースコードでは、キューを作ったり設定を変えたりしたあと、キューの属性が設定どおりになっているかを5秒以上の間をあけて読み、6回続けて一致するまで待ちます。デバッグログでも、GetQueueAttributes がおよそ5秒ごとに呼ばれていました。
AWS CLI で、できたものを確かめる
できたバケットとキューを、AWS CLI で読みました。バケットのタグも、キューの属性とタグも、設定ファイルのとおりでした。
$ aws s3api get-bucket-tagging --bucket example-uploads
{
"TagSet": [
{
"Key": "Env",
"Value": "local"
}
]
}
$ aws sqs get-queue-attributes --queue-url $(terraform output -raw queue_url) --attribute-names VisibilityTimeout MessageRetentionPeriod
{
"Attributes": {
"VisibilityTimeout": "60",
"MessageRetentionPeriod": "86400"
}
}
$ aws sqs list-queue-tags --queue-url $(terraform output -raw queue_url)
{
"Tags": {
"Env": "local"
}
}
出力の queue_url は、本物の SQS と同じ sqs.us-east-1.amazonaws.com の形です。AWS CLI の送り先は AWS_ENDPOINT_URL で決まるので、この URL を --queue-url に渡しても、リクエストはエミュレーターに届きました。バケットにファイルを置き、キューでメッセージを送って受け取るところまで、そのまま使えました。
$ echo hello > hello.txt && aws s3 cp --no-progress hello.txt s3://$(terraform output -raw bucket_name)/hello.txt
upload: ./hello.txt to s3://example-uploads/hello.txt
$ aws sqs send-message --queue-url $(terraform output -raw queue_url) --message-body hello --query MessageId --output text | wc -c
37
$ aws sqs receive-message --queue-url $(terraform output -raw queue_url) --query 'Messages[].Body' --output text
hello
plan で差分が出ないか、設定の変更が反映されるかを見る
apply のあとで、もう一度 terraform plan を実行し、エミュレーターが返す値と設定ファイルの間に差分が出ないかを見ました。差分はありませんでした。
$ terraform plan
(略)
No changes. Your infrastructure matches the configuration.
次に、visibility_timeout_seconds を 60 から 120 に変えて apply しました。キューは作り直されずに、その場で更新されました。ここでも、作るときと同じ待ち方で25秒かかりました。
$ terraform apply -auto-approve
# aws_sqs_queue.jobs will be updated in-place
~ visibility_timeout_seconds = 60 -> 120
Plan: 0 to add, 1 to change, 0 to destroy.
aws_sqs_queue.jobs: Modifications complete after 25s [id=https://sqs.us-east-1.amazonaws.com/<12桁のアカウントID>/example-jobs]
Apply complete! Resources: 0 added, 1 changed, 0 destroyed.
$ aws sqs get-queue-attributes --queue-url $(terraform output -raw queue_url) --attribute-names VisibilityTimeout
{
"Attributes": {
"VisibilityTimeout": "120"
}
}
terraform destroy で、2つとも消えました。バケットにはファイルが残っていましたが、force_destroy = true を付けていたので、エラーにはなりませんでした。
$ terraform destroy -auto-approve
Plan: 0 to add, 0 to change, 2 to destroy.
aws_sqs_queue.jobs: Destroying... [id=https://sqs.us-east-1.amazonaws.com/<12桁のアカウントID>/example-jobs]
aws_s3_bucket.uploads: Destroying... [id=example-uploads]
aws_s3_bucket.uploads: Destruction complete after 0s
aws_sqs_queue.jobs: Destruction complete after 1s
Destroy complete! Resources: 2 destroyed.
$ aws s3api list-buckets --query 'Buckets[].Name'
[]
$ aws sqs list-queues
エミュレーターを起動し直すと、state だけが残る
AWS Emulator は、公式ドキュメントの制限の説明のとおり、リソースをメモリー上にだけ保持し、止めるとすべて消します。一方、Terraform の state はファイル(terraform.tfstate)なので残ります。
apply してからエミュレーターを止めて起動し直すと、バケットは消えていましたが、state には2つとも残っていました。この状態で plan を実行すると、Terraform はリソースがないことに気づき、2つとも作り直す計画を出しました。そのまま apply すると、作り直せました。
$ aws s3api list-buckets --query 'Buckets[].Name'
[]
$ terraform state list
aws_s3_bucket.uploads
aws_sqs_queue.jobs
$ terraform plan
# aws_sqs_queue.jobs has been deleted
# aws_s3_bucket.uploads will be created
# aws_sqs_queue.jobs will be created
Plan: 2 to add, 0 to change, 0 to destroy.
エミュレーターの中身は起動のたびに空になりますが、terraform.tfstate は前回の内容のまま残ります。CI などでエミュレーターを起動するたびに apply するなら、terraform.tfstate がない状態から毎回始めると、エミュレーターと state の中身がそろいます。





