AWS Emulator 설명 및 사용방법, A to Z

AWS Emulator 공식 출시와 실전 사용 가이드

업무 중 참고할 수 있도록 정리한 로컬 AWS 테스트 가이드 : Windows Docker 설치 · AWS CLI · S3/DynamoDB · .NET · Fidelity

개발 업무를 하다 보면 AWS와 연동하는 기능을 테스트할 때마다 실제 클라우드 환경을 준비해야 하는지 고민하게 됩니다. 마침 AWS가 2026년 11월 11일 AWS Emulator를 공식 공개했다는 소식을 접해, 나중에 업무에 활용할 수 있을지 확인하고자 공식 문서와 GitHub 자료를 찾아봤습니다. 그 과정에서 확인한 Windows Docker 설치, AWS CLI 연결, S3·DynamoDB 테스트, .NET 연동 방법과 주의사항을 필요할 때 다시 꺼내 볼 수 있도록 한 글에 정리했습니다.

이 글의 목차

1. 서론 : 업무에 활용할 로컬 테스트 환경을 찾으며
2. AWS Emulator의 개념과 구조
3. 기능·지원 범위·최신 릴리스
4. Windows Docker 설치
5. AWS CLI 연결과 정상 확인
6. S3 파일 업로드 테스트
7. DynamoDB 데이터 테스트
8. Linux 설치 방법
9. .NET / ASP.NET Core 연동
10. Fidelity와 API 호환성
11. 보안·텔레메트리·제약사항
12. LocalStack 비교 및 실무 도입
13. 자주 묻는 질문
14. 마무리
15. 공식 참고 자료

INTRODUCTION

01. 업무에 활용할 로컬 AWS 테스트 환경을 찾으며

개발 업무에서 AWS 연동 기능을 테스트해야 할 때를 생각하면, 매번 실제 클라우드 리소스를 준비하지 않고 로컬에서 검증할 방법이 있는지 궁금했습니다. AWS Emulator가 공개됐다는 소식을 접한 뒤에는 필요할 때 바로 업무에 적용할 수 있을지 알아보기 위해 설치 과정과 지원 범위를 하나씩 확인해 봤습니다.

 

S3 업로드, DynamoDB 저장, SQS 메시지 전송처럼 AWS SDK에 의존하는 코드를 검증하려면 보통 실제 AWS 개발 계정 또는 Mock이 필요합니다. 실제 클라우드 테스트는 서비스의 진짜 동작을 검증할 수 있지만 배포 시간, IAM·네트워크 설정, 비용을 관리해야 합니다. 반대로 Mock은 빠르고 격리하기 쉽지만 API 검증 오류나 서비스 간 상태 변화를 충분히 재현하지 못할 수 있습니다.

 

AWS Emulator는 이 둘 사이에 로컬 AWS API 통합 테스트 계층을 추가합니다. 에뮬레이터 자체는 그래픽 화면이 없는 로컬 서버이며, 애플리케이션의 AWS SDK/CLI 요청을 로컬로 보냅니다. 실제 클라우드 리소스는 생성되지 않습니다.

애플리케이션 (.NET / Node.js / Python 등) │ ▼ AWS SDK / AWS CLI │ HTTPS + SigV4 ▼ https://127.0.0.1:9297 │ ▼ AWS Emulator ┌──────┼─────────┐ ▼ ▼ ▼ S3 DynamoDB 기타 API │ ▼ 인스턴스 내 메모리 상태

중요한 것은 동작을 구현한 API에 한해 실제 AWS와 유사한 결과를 반환하도록 설계되었다는 점입니다. “AWS 서비스 목록에 표시된다”와 “모든 API가 실제 AWS와 동일하게 작동한다”는 서로 다릅니다.

ARCHITECTURE

02. AWS Emulator의 정의와 기술 구조

항목	공식적으로 확인되는 내용
공개일	2026년 11월 11일
개발·배포	Amazon Web Services(AWS)
구현	Rust / Smithy 기반 AWS API 모델 활용
접속	서버 모드 기본 HTTPS 127.0.0.1:9297
클라이언트	AWS CLI, AWS SDK, AI 코딩 에이전트
플랫폼	Linux 네이티브 RPM/DEB, Windows·macOS는 Docker
데이터	에뮬레이터 실행 인스턴스의 메모리에 보관
인증	기본적으로 자체 생성 SigV4 인증 정보 사용
계정·리전	에뮬레이터 인스턴스당 하나의 계정 및 리전 관점으로 테스트
라이선스	주요 소스 CC0-1.0; vendor/ 하위 코드는 Apache-2.0
과금	에뮬레이터 추가 서비스 요금 없음. 실제 AWS 사용료와 별개

핵심 동작 원리

AWS Emulator가 시작되면 포트별 디렉터리에 로컬 전용 인증 정보, SDK 설정 파일, HTTPS 인증서를 작성합니다. AWS CLI나 SDK는 해당 설정을 이용해 요청을 서명하고 에뮬레이터로 전송합니다. 응답 형식과 오류를 실제 AWS에 가깝게 처리하는 것이 목표이지만 미구현 작업도 존재합니다.

 

Rust 기반 소스는 서비스별 모듈로 구성되며 GitHub 저장소에서는 services/, core/router/, core/embedded/ 등으로 구조를 확인할 수 있습니다. Rust 테스트에서는 에뮬레이터의 HTTP 클라이언트를 프로세스 내부에 연결하는 Embedded mode도 제공하지만, 일반적인 Windows 사용자에게는 Docker 서버 모드가 출발점입니다.

AI가 작성했다는 사실의 의미

AWS는 자율 AI 에이전트들이 AWS Emulator 코드를 작성하고 테스트·수정했다고 공개했습니다. 다만 AI 기반 구현이라는 점만으로 품질을 판단할 수는 없습니다. 실제 사용 가능성은 API별 Fidelity 테스트와 본인 애플리케이션의 통합 테스트 결과로 확인해야 합니다.

FEATURES & RELEASES

03. 주요 기능과 2026년 11월 15일 릴리스 확인

기존 SDK 재사용

코드 구조를 크게 바꾸지 않고 호출 대상 엔드포인트를 로컬로 지정합니다.

격리된 테스트 인스턴스

포트·인증 정보·메모리 상태를 분리해 CI와 병렬 테스트에 활용할 수 있습니다.

공개 Fidelity 검증

서비스별 검증 테스트와 릴리스별 결과가 GitHub에 공개됩니다.

공식 GitHub 릴리스 목록을 2026년 11월 15일 확인했을 때 최상단 버전은 v1.0.385였으며, GitHub에는 11월 14일 릴리스로 표시되어 있습니다. 출시 직후 여러 차례 패치가 공개되는 중이므로 이 숫자를 항상 최신 버전으로 간주해서는 안 됩니다. 실제 설치 버전은 aws-emulator -v, 공개 현황은 공식 Releases에서 확인해야 합니다.

 

AWS API 모델을 바탕으로 서비스 엔드포인트를 구성하지만 일부 API는 HTTP 501 / NotImplemented를 반환합니다. S3, DynamoDB 등 이 글의 실습은 AWS가 공식 발표에서 예로 든 경로를 따릅니다. SQS·Lambda·CloudFormation 등 특정 프로젝트의 지원 범위는 각 API 수준에서 확인해야 합니다.

테스트 방식 비교

방식	강점	놓치기 쉬운 부분
단위 테스트 Mock	빠르고 외부 의존성이 작음	실제 API 규약·서비스별 오류 재현 부족
AWS Emulator	로컬 AWS API 연동 테스트에 적합	구현 갭·IAM·리전·성능 재현 한계
실제 AWS 테스트 계정	클라우드의 진짜 동작·정책·서비스 연동 검증	리소스 비용·정리·권한·배포 시간 관리 필요

AI 코딩 에이전트 스킬 설치

AWS는 Kiro·Cursor·Claude Code 등 AI 코딩 에이전트가 AWS Emulator를 설정하고 프로젝트의 API 호환성을 확인하는 aws-emulator 스킬을 제공합니다. 공식적으로 AWS CLI 2.35.0 이상을 요구합니다. 실제 지원 동작은 에이전트 및 실행 환경에 따라 확인해야 합니다.

AWS 공식 AI 에이전트 스킬 설치Bash / PowerShell

aws --version
aws agent-toolkit add-skill --skill-name aws-emulator --region us-east-1

스킬을 설치한 뒤 에이전트에게 “이 저장소에서 쓰는 AWS API를 찾아 Fidelity 테스트가 있는 항목과 없는 항목을 나눠 줘”처럼 요청할 수 있습니다. 에이전트의 결과 역시 실제 SDK 호출과 Fidelity 자료를 통해 재검증해야 합니다.

WINDOWS / DOCKER

04. Windows에서 Docker로 설치하는 방법

AWS 공식 문서 기준 Windows와 macOS에서는 사전 빌드된 AWS 공식 Docker 이미지를 제공하지 않습니다. 대신 Amazon Linux 패키지를 설치하는 Docker 이미지를 직접 빌드합니다. Windows에서는 Docker Desktop이 Linux 컨테이너 모드로 실행되는지 먼저 확인합니다.

1단계. 사전 준비 및 폴더 생성

Docker / AWS CLI 확인PowerShell

docker --version
docker info
aws --version

New-Item -ItemType Directory -Force C:\aws-emulator
Set-Location C:\aws-emulator

AWS CLI v2를 설치하지 않았다면 AWS CLI 공식 설치 문서를 참고합니다. Docker 정보 조회가 실패한다면 Docker Desktop이 실행 중인지 확인합니다.

2단계. Dockerfile 생성

C:\aws-emulator\Dockerfile 파일을 만들고 다음 내용을 저장합니다. x86_64(일반적인 Intel/AMD PC) 기준 AWS 공식 Dockerfile입니다.

AWS 공식 Dockerfile · x86_64Dockerfile

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

ARM 프로세서라면 RPM 파일을 aws-emulator-aarch64.rpm으로 바꿉니다. -b 0.0.0.0은 컨테이너 내부에서 연결을 받도록 하는 설정이며, 외부 노출 범위는 아래의 Docker 포트 매핑에서 제한합니다.

3단계. 이미지 빌드

이미지 생성PowerShell

docker build -t aws-emulator .
docker images

4단계. 설정 파일을 공유할 호스트 디렉터리 생성

인증서/설정용 폴더PowerShell

New-Item -ItemType Directory -Force "$env:USERPROFILE\.aws\emulator"

5단계. 컨테이너 실행

다음 명령어는 공식 실행 옵션을 유지하면서 로컬호스트로만 포트를 공개하고, 텔레메트리는 선택적으로 비활성화하도록 구성한 예시입니다.

컨테이너 실행 · 로컬 전용PowerShell

$port = 9297

docker run --rm --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

컨테이너는 터미널을 점유한 상태로 실행되므로 다음 단계는 새 PowerShell 창에서 진행합니다. --memory=2g --memory-swap=2g는 AWS 공식 예제의 2 GiB 한도이며 권장 최소 사양을 의미하지는 않습니다. 메모리 제한을 넘으면 컨테이너가 종료될 수 있습니다.

포트 매핑은 반드시 구분

-p 127.0.0.1:9297:9297은 호스트 PC에서만 접근할 수 있도록 제한합니다. 반대로 -p 9297:9297처럼 호스트 주소를 생략하면 환경에 따라 다른 컴퓨터에서도 접근할 수 있으므로 개발용 에뮬레이터에는 권장하지 않습니다.

CONNECT & VERIFY

05. AWS CLI를 로컬 에뮬레이터에 연결하기

실제 AWS에 요청을 잘못 전송하지 않도록 에뮬레이터용 전용 PowerShell 세션에서 환경 변수를 설정합니다. 아래 변수는 공식 SDK 연결 가이드에 따라 작성했습니다.

필수 환경 변수 + 실 AWS 키 분리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_EC2_METADATA_DISABLED = "true"
$env:AWS_DISABLE_HOST_PREFIX_INJECTION = "true"
$env:AWS_REGION = "us-east-1"
$env:AWS_DEFAULT_REGION = "us-east-1"

Remove-Item Env:AWS_ACCESS_KEY_ID, Env:AWS_SECRET_ACCESS_KEY, Env:AWS_SESSION_TOKEN, Env:AWS_PROFILE -ErrorAction SilentlyContinue

AWS_SHARED_CREDENTIALS_FILE은 에뮬레이터가 시작할 때 생성한 인증 키를 읽도록 하며, AWS_CA_BUNDLE은 AWS CLI가 로컬 HTTPS 인증서를 검증하도록 합니다. 실제 계정용 AWS_PROFILE 등이 남아 있다면 요청이 거부되거나 다른 엔드포인트를 호출할 수 있습니다.

Health 엔드포인트 확인

정상 상태 확인PowerShell

curl.exe --cacert "$env:USERPROFILE\.aws\emulator\9297\ca.pem" https://127.0.0.1:9297/__admin/health

정상이면 HTTP 200과 본문 ok가 반환됩니다. 헬스체크는 AWS API 호출과 별도로 서버 준비 상태를 확인하기 위한 용도입니다.

실제 AWS가 아닌지 교차 확인

호출 계정 확인PowerShell

aws sts get-caller-identity

공식 문서의 예상 응답 중 주요 필드 · UserId 생략JSON

{
  "UserId" : "...",
  "Account" : "000000000000",
  "Arn" : "arn:aws:iam::000000000000:user/emulator"
}

Account 값이 000000000000이고 ARN이 위 형태이면 로컬 에뮬레이터에 연결되었다는 의미입니다. 실제 AWS 계정 번호가 반환되면 즉시 테스트를 중단하고 환경 변수를 재확인합니다.

HTTPS 연결 문제

AWS Emulator는 시작할 때 인증서를 새로 만듭니다. 따라서 이전 실행의 인증서를 별도 복사해 둔 경우 재실행 후 TLS 오류가 생길 수 있습니다. ca.pem의 현재 경로를 확인하고 인증서 검증을 무작정 끄지 않는 것이 좋습니다.

AMAZON S3

06. S3 버킷 생성·업로드·다운로드 실습

이 절의 명령은 앞 단계에서 AWS CLI가 로컬 엔드포인트로 연결된 상태를 전제로 합니다. AWS 공식 발표에서도 S3 버킷 생성 및 객체 업로드 예제를 제공합니다.

버킷 생성과 목록 조회

S3 버킷 생성 / 목록PowerShell

aws s3 mb s3://local-getting-started
aws s3 ls

파일 생성 및 S3 업로드

S3 객체 업로드PowerShell

"hello from AWS Emulator" | Set-Content -Path hello.txt -Encoding utf8
aws s3 cp hello.txt s3://local-getting-started/
aws s3 ls s3://local-getting-started/

다운로드 및 내용 확인

S3 객체 다운로드PowerShell

aws s3 cp s3://local-getting-started/hello.txt downloaded.txt
Get-Content downloaded.txt

이 흐름은 파일 업로드 API의 성공 경로를 검증하는 최소 사례입니다. 실제 서비스에서 객체 버전 관리, 복제, KMS, 버킷 정책, 이벤트 알림 등을 사용한다면 해당 API의 Fidelity 테스트가 필요합니다. 이 예제로 모든 S3 기능을 검증한 것은 아닙니다.

AMAZON DYNAMODB

07. DynamoDB 테이블·데이터 저장 실습

DynamoDB는 테이블 생성(컨트롤 플레인)과 항목 저장·조회(데이터 플레인)를 함께 시험할 수 있는 예시입니다. JSON 인수를 PowerShell에 직접 중첩해 넣으면 따옴표 처리에 따라 결과가 달라질 수 있으므로 다음 예제는 JSON 파일을 UTF-8 BOM 없이 생성해 전달합니다.

테이블 생성

DynamoDB 테이블 생성PowerShell

aws dynamodb create-table `
  --table-name awsemu-demo `
  --attribute-definitions AttributeName=id,AttributeType=S `
  --key-schema AttributeName=id,KeyType=HASH `
  --billing-mode PAY_PER_REQUEST

aws dynamodb list-tables

위 테이블의 파티션 키는 String 형식의 id입니다. PAY_PER_REQUEST는 실제 DynamoDB의 온디맨드 용량 모드이지만, 이 로컬 호출 때문에 실제 DynamoDB 사용료가 발생하지는 않습니다.

항목 저장

UTF-8 JSON 파일로 PutItemPowerShell

$awsemu_utf8 = New-Object System.Text.UTF8Encoding($false)
$awsemu_item = '{"id":{"S":"item-1"},"message":{"S":"hello"}}'
[System.IO.File]::WriteAllText((Join-Path (Get-Location) "awsemu-item.json"), $awsemu_item, $awsemu_utf8)

aws dynamodb put-item `
  --table-name awsemu-demo `
  --item file://awsemu-item.json

기본 키로 항목 조회

GetItemPowerShell

$awsemu_key = '{"id":{"S":"item-1"}}'
[System.IO.File]::WriteAllText((Join-Path (Get-Location) "awsemu-key.json"), $awsemu_key, $awsemu_utf8)

aws dynamodb get-item `
  --table-name awsemu-demo `
  --key file://awsemu-key.json

예상 응답 형태 · 실행 결과 캡처 아님JSON

{
  "Item" : {
    "id" : {"S" : "item-1"},
    "message" : {"S" : "hello"}
  }
}

오류 응답까지 검증하기

정상 호출만 보는 것보다 잘못된 입력에 대한 응답을 검증하는 편이 실제 API 호환성을 파악하는 데 도움이 됩니다. AWS 문서는 DynamoDB 테이블 이름이 너무 짧으면 ValidationException이 발생하는 예시를 제시합니다.

의도적으로 잘못된 테이블 이름PowerShell

aws dynamodb create-table `
  --table-name ab `
  --attribute-definitions AttributeName=id,AttributeType=S `
  --key-schema AttributeName=id,KeyType=HASH `
  --billing-mode PAY_PER_REQUEST

정상적인 AWS 동작을 재현한다면 길이 제한 오류가 나야 합니다. 만약 NotImplemented나 예상과 다른 메시지가 나온다면 에뮬레이터의 현재 구현 범위와 관련 Fidelity 테스트를 확인해야 합니다.

LINUX / RPM / DEB

08. Linux에서는 패키지로 바로 설치

Linux는 네이티브 설치가 지원됩니다. AWS 공식 문서는 x86_64·aarch64의 RPM/DEB 패키지와 glibc 2.17 이상을 사전 조건으로 안내합니다.

Amazon Linux 2023 등 RPM 배포판 (x86_64)

RPM 패키지 설치 및 실행Bash

sudo dnf install -y https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/latest/aws-emulator-x86_64.rpm
aws-emulator -v
aws-emulator

Ubuntu/Debian (amd64)

DEB 패키지 설치 및 실행Bash

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
aws-emulator

새 터미널에서 AWS_ENDPOINT_URL, 인증 정보 파일, 인증서 등의 변수를 설정합니다. Windows와 기능은 같고 셸 문법만 다릅니다.

Linux 터미널에서 CLI 연결Bash

export AWS_ENDPOINT_URL=https://127.0.0.1:9297
export AWS_SHARED_CREDENTIALS_FILE="$HOME/.aws/emulator/9297/emulator_credentials"
export AWS_CONFIG_FILE="$HOME/.aws/emulator/9297/config"
export AWS_CA_BUNDLE="$HOME/.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
aws sts get-caller-identity

프로덕션 CI에서는 고정된 테스트 재현성이 중요합니다. LTS/latest를 매번 설치하면 릴리스 업데이트에 따라 테스트 결과가 바뀔 수 있습니다. 버전 고정 시에는 공식 버전 관리 문서에 명시된 버전별 패키지 경로를 사용하고 보안 업데이트도 정기적으로 확인해야 합니다.

AWS SDK FOR .NET

09. .NET / ASP.NET Core에서 사용하는 방법

C# 프로젝트는 기존 AWS SDK for. NET을 그대로 사용할 수 있습니다. 다만 인증 파일·엔드포인트·TLS 신뢰를 올바르게 구성하는 것이 관건입니다. 다음 예제는 SDK 구성 방식의 설명용 코드로, 특정 환경에서 실제 실행을 완료한 벤치마크나 검증 결과가 아닙니다.

콘솔 프로젝트와 패키지 설치

프로젝트 및 AWSSDK.S3 설치PowerShell

dotnet new console -n AwsEmulatorDemo
cd AwsEmulatorDemo
dotnet add package AWSSDK.S3

S3 버킷 조회 예제

로컬 전용 S3 클라이언트 구성 예시C#

using Amazon.S3;

var config = new AmazonS3Config
{
    ServiceURL = "https://127.0.0.1:9297",
    AuthenticationRegion = "us-east-1",
    ForcePathStyle = true
};

using var client = new AmazonS3Client(config);
var result = await client.ListBucketsAsync();

foreach (var bucket in result.Buckets)
{
    Console.WriteLine(bucket.BucketName);
}

이 코드의 ServiceURL은 요청 대상을 명시적으로 고정하고, ForcePathStyle은 S3 버킷 이름을 호스트 이름에 붙이지 않고 경로로 전달하기 위한 선택입니다. 실제 ASP.NET Core 애플리케이션에서는 개발 환경용 설정으로 분리하고, 운영 설정에 로컬 URL이 유입되지 않도록 관리해야 합니다.

SDK 인증서 신뢰 설정

AWS .NET SDK 문서의 인증서 변수PowerShell

$env:SSL_CERT_FILE = "$env:USERPROFILE\.aws\emulator\9297\ca.pem"
dotnet run

AWS 공식 SDK 연결 문서는 .NET용 추가 환경 변수로 SSL_CERT_FILE을 명시합니다. 다만 Windows에서 SDK·런타임 환경에 따라 인증서를 Windows 신뢰 저장소로 가져와야 할 수 있다고 별도로 안내합니다. 즉, 위 한 줄만으로 모든 Windows .NET 환경에서 TLS가 통과한다고 보장하지 않습니다.

.NET 보안 체크

ServerCertificateCustomValidationCallback = ... => true와 같은 인증서 검증 무력화 코드는 예제로 넣지 않았습니다. 로컬 개발용이라도 정상적인 TLS 검증을 유지하는 편이 좋으며, 실제 AWS와 같은 프로세스에서 함께 호출한다면 CA 번들 구성도 별도로 검토해야 합니다.

또한 AWS_SHARED_CREDENTIALS_FILE에 에뮬레이터 전용 키가 기록되어 있어야 합니다. 실제 운영용 프로파일과 혼용하지 않도록 앱 실행 프로세스의 환경 변수를 확인합니다.

COMPATIBILITY

10. Fidelity : 실제 AWS와 어느 정도 동일한가?

AWS는 에뮬레이터가 실제 AWS와 일치하는 정도를 Fidelity(동작 충실도)라고 부릅니다. 공개된 테스트는 단순한 HTTP 상태 코드뿐 아니라 요청 결과, 리소스 상태 변화, 잘못된 요청에 대한 오류 코드를 확인합니다.

개념	실무에서 확인할 내용
지원 API 목록	AWS API 모델에 포함된다고 실제 동작이 완성되었다는 뜻은 아님
미구현 작업	HTTP 501 + NotImplemented가 발생할 수 있음
Fidelity 점수	통과한 Fidelity 테스트 수 / 해당 서비스 전체 테스트 수
컨트롤 플레인	리소스 생성·조회·갱신·삭제 같은 관리 API에서 상대적으로 정확도가 높다고 AWS가 명시
데이터 플레인	실제 데이터 읽기·쓰기 및 서비스 연동은 기능별 차이 존재
IaC	CloudFormation, Terraform, CDK 등의 호환성은 서비스별로 확인

프로젝트 호환성을 확인하는 4단계

1. 프로젝트에서 사용 중인 AWS SDK 호출 목록을 정리합니다. 예 : CreateBucket, PutObject, GetItem.
2. Evaluation Suite 저장소의 manifest.jsonl과 테스트 코드를 확인합니다.
3. 해당 릴리스에 게시된 서비스별 Fidelity 점수를 확인합니다. 테스트 모음 버전이 다르면 점수만 단순 비교하지 않습니다.
4. 중요한 워크플로는 AWS Emulator와 실제 AWS 개발 환경 양쪽에서 실행하여 응답·오류·상태를 비교합니다.

AWS는 주로 us-west-2에서 테스트를 검증하고, 글로벌 서비스는 us-east-1을 사용한다고 설명합니다. 그러므로 다른 리전의 실제 서비스 가용성·차이까지 보장하는 것은 아닙니다.

버전 고정과 테스트 안정성

AWS Emulator는 MAJOR.MINOR.PATCH 형식으로 버전을 관리합니다. PATCH 업데이트라도 Fidelity 개선으로 기존 테스트의 기대 결과가 달라질 수 있습니다. CI에서는 버전을 고정해 재현성을 유지한 다음 의도적으로 업데이트하는 편이 관리하기 쉽습니다. 단, 공식 안내에 따르면 보안 수정은 최신 릴리스에만 적용되므로 오래된 버전을 무기한 유지해서는 안 됩니다.

SECURITY & PRIVACY

11. 보안·데이터 저장·텔레메트리의 실제 한계

IAM·버킷 정책 검증에는 사용할 수 없다

AWS 공식 보안 문서는 에뮬레이터 테스트가 통과해도 IAM 권한, Permissions Boundary, S3 버킷 정책, KMS 키 정책 등의 안전성이 검증된 것은 아니라고 명확히 경고합니다. 실제 AWS에서 거부할 요청이 에뮬레이터에서는 성공할 수 있습니다.

단일 계정·리전 테스트로 봐야 한다

계정 식별자는 000000000000입니다. 에뮬레이터는 요청에 계정이나 리전 정보가 있더라도 실제 AWS처럼 여러 계정·리전 간 리소스를 완전히 격리하지 않습니다. 서로 다른 리전을 시험하려면 인스턴스를 별도로 실행하는 것이 좋습니다.

인메모리·짧은 테스트 수명

리소스 데이터는 실행 중 메모리에 유지됩니다. 종료 시 리소스가 삭제되며, 앞서 마운트한 Docker 볼륨은 인증서·설정 파일 공유를 위한 것일 뿐 S3/DynamoDB 데이터를 영구 저장하는 용도가 아닙니다. 장시간 운영이나 부하 테스트의 검증된 대체재도 아닙니다.

텔레메트리는 기본 켜짐, 비활성화 가능

공식 문서에 따르면 AWS Emulator는 기본적으로 익명화된 사용량·오류 범주·성능 통계 등의 텔레메트리를 AWS로 보냅니다. AWS는 API 요청·응답의 실제 내용, 코드, 인증 정보, 개인 데이터는 수집하지 않는다고 설명합니다. 앞의 Docker 명령에서 -e EMULATOR_TELEMETRY=off를 설정한 이유가 여기에 있습니다.

Linux 텔레메트리 설정Bash

aws-emulator --telemetry off

# 또는 Linux 쉘에서
export EMULATOR_TELEMETRY=off

실무 적용 전 반드시 확인

운영용 비밀키·개인정보·실제 고객 데이터를 테스트용 에뮬레이터에 넣지 않는 것이 안전합니다. 로컬 포트 공개 여부, SDK 자격 증명 우선순위, CA 파일 관리, 운영 계정으로 향하는 요청 여부를 확인한 후 사용하세요.

ENGINEERING DECISION

12. LocalStack과의 차이, 도입 판단 기준

비슷한 영역의 대표적인 기존 도구는 LocalStack입니다. 2026년 11월 13일 LocalStack도 AWS Emulator 관련 공식 입장을 공개했습니다. 두 제품이 동일한 범위의 기능을 지원한다고 단정하기보다 테스트 대상 API와 개발 플랫폼의 편의 기능을 비교해야 합니다.

비교 항목	AWS Emulator	LocalStack
제공 주체	AWS 공식 프로젝트	LocalStack 제공
관점	AWS API 에뮬레이터·공개 Fidelity	로컬 클라우드 개발 플랫폼
로컬 실행	Linux 패키지, Docker, Rust Embedded	컨테이너 중심 및 플랫폼 연동
주요 부가 기능	AI 에이전트 스킬·서비스별 Fidelity 테스트	웹 리소스 브라우저, IaC/IDE 통합 등 제품 기능
사용 조건	AWS 계정 불필요·추가 에뮬레이터 이용료 없음	2026년 통합 제품 기준 계정과 플랜 조건 확인 필요
최종 선택	사용하는 API와 Fidelity 검증	사용하는 API·개발 도구·플랜 검증

LocalStack은 2026년 3월부터 AWS 에뮬레이터 제품 제공 체계를 단일 버전으로 전환하면서 실행을 위한 계정이 필요하다고 안내했습니다. 그러므로 과거 Community 무료 이미지 이용 경험을 현재 모든 기능의 무료 사용 조건과 동일하게 해석하면 안 됩니다.

개발 환경에 적용한다면

1. 단위 테스트: Mock 기반 테스트는 계속 유지합니다. 요청 파라미터 검증 등 빠른 피드백에 유리합니다.
2. 로컬 통합 테스트: 지원 수준을 확인한 API부터 AWS Emulator로 검증합니다. 예 : S3 업로드, DynamoDB 저장·조회.
3. 실제 AWS 검증: IAM·KMS·리전·네트워크·이벤트·운영 성능 등은 개발 또는 스테이징 AWS 계정에서 확인합니다.
4. CI/CD: 단일 에뮬레이터를 여러 테스트가 공유하기보다 필요 시 별도 인스턴스를 생성하고 종료해 상태 충돌을 줄입니다.

CI에 /__admin/health 준비 확인을 넣고, 테스트 종료 후 컨테이너를 제거하면 외부 클라우드 자원 없이 반복 가능한 테스트 환경을 만드는 데 도움이 됩니다. 다만 “AWS Emulator에서 성공 = 실제 AWS 배포 성공”이라는 등식은 성립하지 않습니다.

FAQ

13. AWS Emulator 자주 묻는 질문

Q. AWS 계정이나 신용카드를 등록해야 하나요?

아닙니다. AWS 공식 안내 기준 AWS Emulator를 다운로드하고 로컬에서 실행하는 데 AWS 계정이 필요하지 않습니다. 실제 AWS에 애플리케이션을 배포한다면 별도의 AWS 사용료가 발생할 수 있습니다.

Q. Windows에서 EXE 파일을 바로 설치할 수 있나요?

AWS 공식 지원 경로는 Windows 및 macOS에서 Docker 이미지 직접 빌드·실행입니다. Linux는 RPM/DEB 네이티브 패키지를 설치합니다. 공식 문서 기준 Windows용 단독 EXE 설치 절차는 안내되지 않습니다.

Q. S3, DynamoDB, Lambda 등 모든 서비스가 완전히 동작하나요?

그렇지 않습니다. AWS API 모델 기반 인터페이스가 있어도 구현 수준은 API별로 다릅니다. 미구현 작업은 HTTP 501과 NotImplemented를 반환할 수 있습니다. 필요한 동작이 Fidelity 테스트에 포함되는지 확인해야 합니다.

Q. AWS Emulator를 끄면 S3 버킷과 DynamoDB 데이터가 남나요?

기본적으로 남지 않습니다. 리소스 상태는 인메모리이며 종료 시 삭제됩니다. Docker 설정 파일 볼륨을 연결해도 이를 영속적인 S3/DynamoDB 저장소로 볼 수 없습니다.

Q. LocalStack보다 정확하거나 빠르다고 할 수 있나요?

제품 전체를 대상으로 한 검증된 비교 벤치마크가 없으므로 단정할 수 없습니다. 프로젝트에서 사용하는 API·오류 경로·IaC·IDE 통합·사용 조건 등을 직접 비교해야 합니다.

Q. .NET에서 SSL 오류가 발생하면 인증서 검증을 꺼도 되나요?

권장하지 않습니다. AWS 문서의 SSL_CERT_FILE과 필요한 경우 Windows 인증서 저장소에 현재 에뮬레이터 CA 인증서를 신뢰하도록 설정하고, 재시작 후 인증서 갱신 여부를 확인합니다.

CONCLUSION

14. 마무리

이번 글은 새로운 AWS 도구를 소개하는 데서 끝내기보다, 업무 중 AWS 연동 기능을 개발하거나 테스트할 일이 생겼을 때 바로 참고할 자료를 만들어 두자는 생각으로 정리했습니다. 공식 문서를 여러 곳 찾아보며 설치 순서와 명령어, .NET 연동 시 확인할 부분, 실제 AWS와 다른 제약사항까지 한 곳에 모았습니다.

 

정리해 보니 AWS Emulator는 모든 AWS 서비스를 대신하는 도구라기보다 반복적인 API 연동 테스트를 로컬에서 빠르게 수행할 수 있는 선택지에 가깝습니다. 나중에 업무에 적용한다면 먼저 실제 사용하는 AWS API 목록을 확인하고, Fidelity 테스트와 지원 범위를 살펴본 뒤 S3 업로드나 DynamoDB 데이터 처리처럼 범위가 작은 기능부터 검증해 볼 생각입니다. IAM 권한, 보안 정책, 리전별 동작과 운영 환경 특성은 실제 AWS에서 별도로 확인해야 합니다.

 

아직 이 글의 모든 예제를 직접 실행하거나 업무 시스템에 도입해 검증한 것은 아닙니다. 따라서 실제 적용 시에는 사용 중인 SDK 버전과 API 지원 상태를 다시 확인해야 합니다. 이번 정리가 저뿐 아니라 비슷한 개발 환경을 구성하려는 분들에게도 실무 참고 자료가 되었으면 합니다.

결론 한 줄

AWS Emulator는 실제 AWS를 대체하는 운영 환경이 아니라, 실제 AWS에 도달하기 전 오류를 더 빨리 발견하게 하는 개발·테스트용 로컬 API 계층 입니다.

오딘박스(OdinBOX)에서 함께 읽어볼 글

• 클라우드(Cloud)에 대해서 알아봅시다!AWS Emulator를 처음 접했다면 클라우드 개념부터 정리하기 좋은 기존 글
• AI 코딩 에이전트의 숨겨진 위험, 악성 README와 간접 프롬프트 인젝션AI 에이전트 스킬과 외부 프로젝트를 사용할 때의 보안 점검 관점

REFERENCES

15. 검증에 사용한 공식 자료

• AWS 공식 발표 · 2026.11.11공식 출시일, 제품 목적, 과금·기본 개념
• AWS News Blog · 2026.11.11AWS CLI, S3·DynamoDB 시나리오, Rust·보안
• GitHub / aws-emulator소스·README·알려진 문제·CC0 및 vendor 예외
• GitHub / Releases버전 및 릴리스별 패치·Fidelity 결과
• AWS Docker 시작 가이드Windows Dockerfile, 실행 명령, 호스트 포트 제한
• AWS SDK 연결 가이드환경 변수, STS 계정, SDK별 TLS
• AWS Linux 설치 가이드RPM·DEB 패키지, 버전·서명 검증
• Fidelity / Evaluation SuiteAPI 충실도 측정, 검증 범위
• 프로젝트 호환성 확인 가이드manifest.jsonl 기준 API별 검증
• 보안 및 텔레메트리IAM 한계 및 기본 로컬 네트워크 보호
• Telemetry 안내기본 수집 항목과 opt-out
• 버전·호환성 안내고정 버전·보안 업데이트 정책
• LocalStack 공식 비교 · 2026.11.13LocalStack 측 공식 입장
• LocalStack 2026 제품 정책2026년 통합 버전 및 계정 필요 정책