AWS Emulator入門!Windows・Dockerで構築しJava・GradleからS3を操作する方法
2026年11月11日、AWSが新しいローカル開発ツール「AWS Emulator」を正式に公開しました。
AWS Emulatorを利用すると、AWSアカウントを用意せずに、自分のPC上でAWS APIを呼び出すアプリケーションを開発・テストできます。
これまでAWSを利用したWebアプリケーションの開発では、実際のAWS環境を用意するか、LocalStackやMinIOなどのローカルツールを活用する方法がありました。
今回、AWS自身がAWS APIのエミュレータを公開したことで、新たな選択肢が増えました。
本記事では、WindowsとDocker DesktopでAWS Emulatorを起動し、Gradle・AWS SDK for Java v2を使ってAmazon S3のバケット作成と一覧取得を試す手順を紹介します。
なお、掲載する実装コードはAWSの公式仕様に基づいて構成したサンプルです。コンテナの起動・Javaからの統合動作確認は未実施のため、実行する環境やエミュレータのバージョンによって調整が必要な場合があります。
AWS Emulatorとは?
AWS Emulatorは、Amazon Web Servicesが2026年11月11日に公開した、AWS APIをローカル環境で再現するためのオープンソースソフトウェアです。
AWS公式ブログによると、次の特徴があります。
| 特徴 | 内容 |
|---|---|
| 提供元 | AWS |
| 公開日 | 2026年11月11日 |
| 利用料金 | Emulator自体に追加サービス料金なし |
| AWSアカウント | 不要 |
| 対応環境 | Linux、Dockerなど |
| APIアクセス | AWS SDK・AWS CLI |
| 通信 | ローカルHTTPS |
| 認証 | Emulator専用の認証情報 |
| データ保存 | メモリ上 |
| ソースコード | GitHubで公開 |
AWS APIと同じ形式のリクエストを利用できるため、既存のAWS SDKのコードを活用できます。
ただし、AWSのすべての操作が完全に再現されているわけではありません。
APIごとの実装状況によっては、HTTP 501(Not Implemented)が返されます。
そのため、AWS Emulatorは本番AWS環境を完全に置き換えるものではなく、開発やテストを効率化するためのツールと考えるのが適切です。
AWS Emulatorの何がすごい?
今回の発表には、もう一つ注目すべき特徴があります。
AWS公式によると、AWS Emulatorのコードは自律型AIエージェントによって生成されています。
AIエージェントが以下のような作業を担当する仕組みです。
- AWS APIの仕様からテストを作成する
- AWSとの動作の違いを検出する
- 問題のある処理を修正する
- テストやセキュリティチェックを通過した変更をリリースする
つまり、AIが単にソースコードを書くのではなく、テスト・検証・修正まで継続的に実施する仕組みで開発されています。
AIコーディングが話題になる中で、開発プロセスそのものにも注目したいプロジェクトです。
参考:AWS公式:How we built the agents that built AWS Emulator
今回の動作確認環境
今回のサンプルでは、以下の環境を想定します。
| 項目 | バージョン・設定 |
|---|---|
| OS | Windows 10 / 11 |
| コンテナ環境 | Docker Desktop(Linuxコンテナ) |
| Java | Java 21 |
| ビルドツール | Gradle 8.14以降 |
| AWS SDK | AWS SDK for Java v2(2.57.13) |
| AWS Emulator | 公式LTSパッケージ |
| 対象サービス | Amazon S3 |
| 接続先 | https://127.0.0.1:9297 |
AWS EmulatorはWindows向けのネイティブ実行ファイルではなく、Dockerを使用して起動します。
なお、公式のDocker用サンプルではx86_64向けのRPMを使用します。Arm環境の場合はaarch64向けのパッケージへ変更してください。
AWS Emulatorの構成
今回の処理の流れは次のとおりです。
Windows PC
│
├─ Javaアプリケーション
│ └─ AWS SDK for Java v2
│ │
│ │ HTTPS
│ │ https://127.0.0.1:9297
│ ▼
├─ Docker Desktop
│ └─ AWS Emulator
│ └─ Amazon S3 APIを再現
│ ├─ CreateBucket
│ └─ ListBuckets
│
└─ .aws/emulator/9297/
├─ emulator_credentials
├─ config
├─ ca.pem
└─ truststore.p12
今回のポイントは、Java側で実際のAWSではなく、Dockerコンテナ上のAWS Emulatorへ接続することです。
また、EmulatorはHTTPSを使用するため、Java側で証明書を信頼する設定も必要になります。
手順1:Docker Desktopを準備する
まず、WindowsにDocker Desktopをインストールしてください。
インストール後、Docker Desktopを起動します。
PowerShellで次のコマンドを実行してください。
docker --version
docker info
Dockerのバージョンや実行環境の情報が表示されれば、Dockerを利用できる状態です。
エラーになる場合は、Docker Desktopが起動しているか、Linuxコンテナモードになっているか確認してください。
手順2:AWS EmulatorのDockerfileを作成する
作業用ディレクトリを作成します。
mkdir aws-emulator-demo
cd aws-emulator-demo
続いて、Dockerfileという名前のファイルを作成します。
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"]
これはAWS公式ドキュメントに掲載されたDockerfileの構成です。
重要な部分を確認しましょう。
FROMではAmazon Linux 2023をベースイメージとして使用します。
ADDではAWS EmulatorのRPMパッケージを取得しています。
EXPOSE 9297はEmulatorが利用するポートです。
最後のENTRYPOINTでAWS Emulatorを起動します。
-b 0.0.0.0はDockerコンテナ内部で全インターフェースの接続を受け付けるための設定です。
このままホスト側にも無制限に公開するのではなく、次の手順で接続元をローカルPCに制限します。
Dockerイメージをビルド
作成したDockerfileがあるディレクトリで、以下を実行します。
docker build -t aws-emulator .
ビルドに成功すると、aws-emulatorという名前のDockerイメージが作成されます。
確認するには以下を実行します。
docker images aws-emulator
手順3:AWS Emulatorを起動する
まず、認証情報や証明書の保存先となるディレクトリを作成します。
New-Item -ItemType Directory -Force "$env:USERPROFILE\.aws\emulator"
次に、Dockerコンテナを起動します。
$port = 9297
docker run --rm --name aws-emulator `
--memory=2g --memory-swap=2g `
-e EMULATOR_TELEMETRY=off `
-p "127.0.0.1:${port}:${port}" `
-v "$env:USERPROFILE\.aws\emulator:/home/emulator/.aws/emulator" `
aws-emulator -p $port
このコマンドのポイントは3つあります。
① ポートをローカルに限定する
127.0.0.1:9297:9297
この指定によって、他のPCから直接アクセスできる状態を避けます。
② 認証情報をホストと共有する
-vオプションで、Windowsとコンテナ間で以下のディレクトリを共有しています。
%USERPROFILE%\.aws\emulator
ここにAWS Emulator専用の認証情報や証明書が生成されます。
③ テレメトリを無効にする
EMULATOR_TELEMETRY=off
AWS Emulatorでは、標準で匿名の利用状況・エラー統計情報が収集されます。
今回のサンプルでは、ローカル検証で不要な外部送信を抑えるために無効化しています。
Docker起動後、このPowerShellは閉じずに、別のPowerShellを開いて次の設定を行います。
手順4:環境変数を設定する
AWS Emulatorでは、起動時に専用の認証情報や証明書が自動生成されます。
通常のAWS SDKでは、AWSの認証情報を使ってクラウドへアクセスします。
一方、今回はEmulator専用の認証情報を利用します。
新しいPowerShellで、以下を実行してください。
$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_EMULATOR_TRUSTSTORE = "$env:USERPROFILE\.aws\emulator\9297\truststore.p12"
$env:AWS_REGION = "us-east-1"
$env:AWS_DEFAULT_REGION = "us-east-1"
$env:AWS_EC2_METADATA_DISABLED = "true"
$env:AWS_DISABLE_HOST_PREFIX_INJECTION = "true"
さらに、実AWSの認証情報が環境変数に残っている場合は解除します。
Remove-Item Env:AWS_ACCESS_KEY_ID, Env:AWS_SECRET_ACCESS_KEY, Env:AWS_SESSION_TOKEN, Env:AWS_PROFILE -ErrorAction SilentlyContinue
この操作は、現在のPowerShellプロセスの環境変数を対象としています。
実AWSへ意図せずアクセスしないようにするためにも重要です。
設定ファイルを確認する
続いて、AWS Emulatorが必要なファイルを生成したか確認します。
Get-ChildItem "$env:USERPROFILE\.aws\emulator\9297"
以下のファイルが存在することを確認してください。
emulator_credentials
config
ca.pem
truststore.p12
それぞれの用途は以下のとおりです。
| ファイル | 役割 |
|---|---|
| emulator_credentials | Emulator専用のアクセスキー |
| config | SDKやCLI用の設定 |
| ca.pem | HTTPS通信用の証明書 |
| truststore.p12 | Java用の証明書ストア |
認証情報は起動ごとに生成されます。
実際のAWS認証情報とは異なるため、サンプルコードへアクセスキーを直接記述する必要はありません。
手順5:AWS Emulatorの動作を確認する
まず、AWS Emulatorが起動しているか確認しましょう。
PowerShellで以下のコマンドを実行します。
curl.exe --cacert "$env:USERPROFILE\.aws\emulator\9297\ca.pem" https://127.0.0.1:9297/__admin/health
正常であれば、次のレスポンスが返されます。
ok
続いて、AWS CLIをインストール済みであれば、接続先を確認できます。
aws sts get-caller-identity
AWS Emulatorに接続できている場合、次のような結果が返ります。
{
"UserId": "...",
"Account": "000000000000",
"Arn": "arn:aws:iam::000000000000:user/emulator"
}
※UserIdは省略した表示例です。
重要なのは、Accountが000000000000となっていることです。
もし実際のAWSアカウントIDが表示された場合は、Emulatorではなく実AWSへアクセスしている可能性があります。
その場合はJavaコードの実行を進めず、環境変数や認証情報を確認してください。
手順6:Java・Gradleのプロジェクトを作成する
ここからは、AWS SDK for Java v2を使用してS3バケットを操作します。
まず、次の構成でGradleプロジェクトを用意してください。
aws-emulator-java-demo/
├── Dockerfile
├── settings.gradle
├── build.gradle
└── src/
└── main/
└── java/
└── com/
└── example/
└── AwsEmulatorS3App.java
settings.gradle
rootProject.name = 'aws-emulator-java-demo'
build.gradle
plugins {
id 'java'
id 'application'
}
java {
toolchain {
languageVersion = JavaLanguageVersion.of(21)
}
}
repositories {
mavenCentral()
}
dependencies {
implementation platform(
'software.amazon.awssdk:bom:2.57.13'
)
implementation 'software.amazon.awssdk:s3'
implementation 'software.amazon.awssdk:apache-client'
}
application {
mainClass = 'com.example.AwsEmulatorS3App'
}
tasks.named('run', JavaExec) {
doFirst {
def trustStore =
System.getenv('AWS_EMULATOR_TRUSTSTORE')
if (trustStore == null || !file(trustStore).isFile()) {
throw new GradleException(
'Set AWS_EMULATOR_TRUSTSTORE to truststore.p12'
)
}
systemProperty 'javax.net.ssl.trustStore', trustStore
systemProperty 'javax.net.ssl.trustStoreType', 'PKCS12'
}
}
ここではAWS SDKのBOMを使用して、関連するライブラリのバージョンを統一しています。
software.amazon.awssdk:s3はAmazon S3を操作するためのSDKです。
apache-clientはHTTP通信に利用するクライアントです。
なぜJavaの証明書設定が必要?
AWS EmulatorはHTTPS通信で独自の証明書を使用します。
そのため、通常のJavaアプリケーションからアクセスすると、証明書を信頼できず、次のような例外が発生する場合があります。
javax.net.ssl.SSLHandshakeException
PKIX path building failed
AWS公式ドキュメントでは、Javaのtruststore.p12を利用する方法が案内されています。
今回のGradle設定では、runタスクで実行されるJavaプロセスにのみ証明書設定を適用しています。
Java全体へ設定すると、GradleがMaven Centralへアクセスする際にもEmulator専用証明書が使われ、依存ライブラリの取得に失敗する可能性があるためです。
手順7:AWS SDK for Java v2でS3を操作する
続いて、Javaクラスを作成します。
今回は以下の処理を実装します。
- AWS Emulatorへ接続する
- S3バケットを作成する
- S3バケットの一覧を取得する
- 作成したバケットが存在することを確認する
AwsEmulatorS3App.java
package com.example;
import java.net.URI;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.List;
import java.util.UUID;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.S3Configuration;
import software.amazon.awssdk.services.s3.model.Bucket;
public class AwsEmulatorS3App {
public static void main(String[] args) {
String endpoint = System.getenv("AWS_ENDPOINT_URL");
if (!"https://127.0.0.1:9297".equals(endpoint)) {
throw new IllegalStateException(
"Only the local AWS Emulator is allowed."
);
}
String credentials =
System.getenv("AWS_SHARED_CREDENTIALS_FILE");
if (credentials == null ||
!Files.isRegularFile(Path.of(credentials))) {
throw new IllegalStateException(
"Emulator credentials were not found."
);
}
for (String name : List.of(
"AWS_ACCESS_KEY_ID",
"AWS_SECRET_ACCESS_KEY",
"AWS_SESSION_TOKEN",
"AWS_PROFILE")) {
String value = System.getenv(name);
if (value != null && !value.isBlank()) {
throw new IllegalStateException(
"Unset " + name + " before running."
);
}
}
String bucketName = "aws-emulator-demo-"
+ UUID.randomUUID()
.toString()
.replace("-", "")
.substring(0, 12);
try (S3Client s3 = S3Client.builder()
.endpointOverride(URI.create(endpoint))
.region(Region.US_EAST_1)
.serviceConfiguration(
S3Configuration.builder()
.pathStyleAccessEnabled(true)
.build()
)
.build()) {
s3.createBucket(request ->
request.bucket(bucketName)
);
List<String> bucketNames = s3.listBuckets()
.buckets()
.stream()
.map(Bucket::name)
.toList();
if (!bucketNames.contains(bucketName)) {
throw new IllegalStateException(
"Bucket was not found: " + bucketName
);
}
System.out.println(
"Created S3 bucket: " + bucketName
);
System.out.println(
"Listed S3 buckets: " + bucketNames
);
System.out.println(
"AWS Emulator S3 test passed."
);
}
}
}
このコードで重要なのが、次の設定です。
.endpointOverride(URI.create(endpoint))
通常、AWS SDKはリージョンに応じたAWSのエンドポイントへ接続します。
今回は接続先を明示的にAWS Emulatorへ変更しています。
また、安全のために以下のチェックを実装しています。
if (!"https://127.0.0.1:9297".equals(endpoint)) {
throw new IllegalStateException(
"Only the local AWS Emulator is allowed."
);
}
環境変数の設定ミスによって実AWSへ接続しないよう、サンプルではエンドポイントをローカルに固定しました。
pathStyleAccessEnabled(true)とは?
今回の実装では、以下の設定も指定しています。
S3Configuration.builder()
.pathStyleAccessEnabled(true)
.build()
これは、S3バケット名をホスト名ではなくURLのパスに含める設定です。
例えば、以下のような形式です。
https://127.0.0.1:9297/bucket-name
AWS公式ドキュメントでも、Java SDKでlocalhostを利用するとバケット名がホスト名に追加される場合があるため、127.0.0.1を利用することが案内されています。
今回はさらにパススタイルアクセスを明示しています。
手順8:Gradleから実行する
PowerShellで、AWS Emulatorの環境変数を設定した状態のまま、Gradleを実行します。
gradle run
Gradle Wrapperを生成済みの場合は、以下でも実行できます。
.\gradlew.bat run
なお、同梱のサンプルにはGradle Wrapperを含めていないため、初回はGradle本体をインストールするか、gradle wrapperで生成してください。
実行に成功した場合、次のような出力になります。
Created S3 bucket: aws-emulator-demo-xxxxxxxxxxxx
Listed S3 buckets:
[aws-emulator-demo-xxxxxxxxxxxx]
AWS Emulator S3 test passed.
※上記は想定される出力例です。実際の実行結果ではありません。
これにより、JavaからAWS Emulatorへ接続し、S3のCreateBucketとListBucketsを実行できたことを確認できます。
今回はAWSアカウントを使用せず、ローカル環境だけでS3 APIを呼び出す構成です。
AWS Emulatorでよくあるエラーと対処方法
① Connection refused
Connection refused: 127.0.0.1:9297
この場合、まずDockerコンテナが起動しているか確認します。
docker ps
起動していなければコンテナを再起動してください。
また、ポート番号が9297になっているか確認しましょう。
② SSLHandshakeExceptionが発生する
PKIX path building failed
このエラーはJavaがAWS Emulatorの証明書を信頼できないときに発生する場合があります。
まず、以下のファイルが存在するか確認します。
%USERPROFILE%\.aws\emulator\9297\truststore.p12
続いて、環境変数を確認します。
echo $env:AWS_EMULATOR_TRUSTSTORE
実際のファイルパスが設定されていることを確認してください。
③ 認証エラーが発生する
AWS Emulatorでは、起動するたびに専用の認証情報が生成されます。
以前の起動時の認証情報をそのまま使用すると、認証エラーになる可能性があります。
以下のファイルが存在するか確認してください。
%USERPROFILE%\.aws\emulator\9297\emulator_credentials
また、実AWS用のアクセスキーが環境変数に残っていないか確認してください。
④ HTTP 501 Not Implementedが返る
HTTP 501 Not Implemented
これは、実行したAWS APIがEmulator側でまだ実装されていない場合に発生します。
AWS EmulatorはAWSのAPIモデルをもとに開発されていますが、サービスや操作によって実装の完成度が異なります。
公式のFidelityレポートで、対応状況を確認しましょう。
AWS EmulatorとLocalStack・MinIOの違い
これまでローカルでAWSの機能を確認するには、LocalStackやMinIOなどを利用する方法が一般的でした。
今回登場したAWS Emulatorは、AWS自身が提供するエミュレータという点が特徴です。
| 項目 | AWS Emulator | LocalStack | MinIO |
|---|---|---|---|
| 主な用途 | AWS APIのローカル検証 | AWSサービスのローカル検証 | S3互換ストレージ |
| 提供元 | AWS | LocalStack | MinIO |
| 主な対象 | 幅広いAWS API | 複数のAWSサービス | S3 API |
| AWSアカウントなしでのローカル利用 | 可能 | 利用形態による | 可能 |
| API互換性 | 操作ごとに異なる | 操作・エディションによる | S3の機能ごとに異なる |
どれが最適かは、目的によって変わります。
例えば、S3互換ストレージでファイルアップロードやダウンロードを検証したい場合は、MinIOが選択肢になります。
一方で、AWSの複数のサービスを組み合わせたアプリケーションや、AWS APIそのものの挙動を検証したい場合、AWS EmulatorやLocalStackが候補になります。
AWS Emulatorは新しいツールのため、既存の検証環境をすぐに置き換えるより、必要なAPIがサポートされているか確認しながら導入するのがよいでしょう。
AWS Emulatorを実務で利用するときの注意点
IAMの認可テストには利用できない
重要なのが、AWS EmulatorではAWS IAMのポリシーやリソースベースポリシーの評価が実AWSと同じように再現されていない点です。
例えば、実際のAWSではアクセスが拒否される操作でも、Emulatorでは成功する可能性があります。
したがって、認証・認可の安全性を確認するテストには利用できません。
データはメモリ上に保存される
AWS Emulatorは、作成したリソースの状態をメモリ上で管理します。
コンテナを停止すると、作成したリソースの状態は失われます。
今回のサンプルで作成したS3バケットも同様です。
そのため、長期保存が必要なデータベースとして利用するのではなく、起動・検証・停止を繰り返すテスト用途に向いています。
本番環境での検証も必要
AWS Emulatorは、開発時のフィードバックを早くするためのツールです。
しかし、以下のような確認は実AWS環境でも行う必要があります。
- IAMポリシーの認可動作
- AWS独自の制限やクォータ
- ネットワーク・セキュリティ設定
- 実際のサービス間連携
- 本番相当の性能や負荷
本番環境へリリースする前には、実AWSの検証環境で統合テストを実施しましょう。
AWS Emulatorは無料で使える?
AWS Emulator自体には追加サービス料金が発生しません。
AWSアカウントも不要です。
ただし、ローカルPCやDockerを動かすための計算資源は必要です。
また、AWS Emulatorを利用したテストとは別に、実際のAWSへアプリケーションをデプロイした場合には、利用したAWSサービスに応じた料金が発生します。
まとめ
2026年11月にAWSが公開したAWS Emulatorは、AWSアプリケーションの開発・テストをローカル環境で実施するための新しい選択肢です。
今回のポイントは以下のとおりです。
- WindowsではDockerを利用して起動できる
- AWSアカウントがなくてもAWS APIを試せる
- AWS SDK for Java v2から利用できる
- Emulator専用の認証情報とHTTPS証明書を使用する
- APIの対応状況には差があるため、実AWSでのテストも必要
Java・Spring BootでAWSを使用したWeb APIを開発する場合、AWS Emulatorを活用することで、毎回AWS上へデプロイせずに処理の一部を確認できる可能性があります。
特に、S3やDynamoDBなどを利用したアプリケーションの開発では、対象APIの対応状況を確認しながら試してみる価値があるでしょう。
AWS Emulatorは公開されたばかりのため、今後のAPI互換性の改善にも注目したいところです。
関連記事
参考資料
- AWS公式発表:Test your applications against AWS locally with AWS Emulator
- AWS Emulator公式ドキュメント
- AWS Emulator:Getting started with Docker
- AWS Emulator:AWS SDKとの接続設定
- AWS Emulator公式GitHub
- AWS Emulator:Fidelity(互換性評価)
※最終更新:2026年11月12日
是非フォローしてください
最新の情報をお伝えします
