Huny's Dev Blog
huny.dev

AWS Emulator(aws/aws-emulator) 아키텍처 해부: Rust·Smithy 기반 439개 서비스 로컬 에뮬레이션과 자율 AI 에이전트 Fidelity 검증 경계 점검하기

2026년 11월 11일 공개된 AWS 공식 로컬 에뮬레이터 aws/aws-emulator의 Rust·Smithy API 모델 아키텍처와 AI 에이전트 자율 개발 루프를 분석한다. 439개 서비스 크레이트 모노레포 구조, #[tokio::main] 대신 64 MiB 라우터 스택을 수동 할당하는 이유, ~/.aws/emulator/9297/ 인증서·임시 자격 증명 격리, v1.0.519 기준 46,026건 Fidelity 테스트(73.06% 통과) 및 CC0-1.0 vs vendor/ Apache-2.0 이중 라이선스, IAM·인메모리·소스 빌드 100GB 디스크 경계와 로컬 Python 6대 검증 스크립트를 정리한다.

Hun Jang
Hun Jang Nov 19, 2026

AWS Emulator의 439개 서비스 크레이트가 단일 로컬 라우터(127.0.0.1:9297)로 수렴하는 개념 추상 아트워크

2026년 11월 11일 AWS가 공식 오픈소스 로컬 AWS API 에뮬레이터 AWS Emulator(github.com/aws/aws-emulator)를 공개했다. 그동안 로컬 AWS 테스트 생태계는 서드파티 도구인 LocalStack에 의존해 왔으나, AWS가 직접 자사의 공식 Smithy API 모델을 기반으로 Rust 기반 경량 로컬 에뮬레이터를 무료·무계정·오프라인 형태로 배포하면서 CI/CD 파이프라인과 AI 코딩 에이전트 개발 루프의 지형이 크게 달라졌다. 특히 이번 프로젝트는 전체 서비스 코드와 테스트가 자율 AI 에이전트에 의해 100% 작성·검증되었고, 소스 코드 역시 저작권 분쟁 소지를 없애기 위해 퍼블릭 도메인 선언인 CC0 1.0 Universal(vendor/ 프레임워크 크레이트는 Apache-2.0)로 공개되었다는 점에서 엔지니어링 관점의 시사점이 크다.

핵심 아키텍처와 실무 도입 기준을 먼저 요약하면, AWS Emulator는 400개 이상의 공식 Smithy API 모델을 바탕으로 200개 이상의 AWS 서비스를 포괄하는 439개 Rust 서비스 크레이트(services/service-<name>/)를 단일 aws-emulator-router 바이너리로 묶어 로컬 https://127.0.0.1:9297 엔드포인트로 제공한다. 각 실행 인스턴스는 자체 서명 인증서(ca.pem)와 임시 SigV4 자격 증명(~/.aws/emulator/9297/)을 생성하고 모든 리소스를 인메모리(In-Memory)로만 유지하므로, AWS 계정이나 과금 없이 테스트 간 깔끔한 초기화가 가능하다. 다만 2026년 11월 19일 공개된 v1.0.519 릴리스의 scores.json.gz 기준 전체 46,026개 Fidelity 테스트 중 33,627건(73.06%)이 통과하고 12,312건(26.75%)이 실패 상태이며, 미구현 연산은 501 NotImplemented를 반환한다. 또한 IAM 정책 평가, 크로스 계정·리전 시뮬레이션, 쓰로틀링 검증은 지원하지 않으므로 프로덕션이나 보안 검증 용도로는 절대 사용할 수 없다. 이 글은 2026년 11월 19일 기준 aws/aws-emulator 저장소 및 README, v1.0.519 릴리스의 scores.json.gz, core/router/src/main.rs 소스 코드, All Things Distributed 공식 아키텍처 글(2026-11-11), AWS Emulator User Guide를 교차 검증해 정리했으며, 실제 로컬 aws-emulator 데몬 기동 벤치마크 대신 공개 아티팩트·소스 코드 분석과 로컬 Python 6대 검증 스크립트를 기준으로 동작 경계를 설명한다.

1. 왜 AWS가 직접 aws-emulator를 공개했는가

1.1 Smithy API 모델과 439개 서비스 크레이트 모노레포

기존 모킹(Mocking) 도구들은 AWS 서비스가 신설되거나 파라미터·에러 스키마가 바뀔 때마다 커뮤니티가 수동으로 응답 포맷을 역공학해 따라가야 했다. 반면 aws-emulator는 AWS SDK가 사용하는 것과 동일한 공개 Smithy API 모델을 출발점으로 삼는다.

저장소(v1.0.519 기준 services/ 하위 439개 디렉터리)를 들여다보면 서비스마다 독립된 Rust 크레이트 구조를 갖는다:

  • services/service-<name>/smithy-model/<name>.json: 해당 AWS 서비스의 와이어 프로토콜, 연산 스키마, 에러 형식을 정의한 Smithy 모델
  • services/service-<name>/build.rs: 컴파일 타임에 Smithy 모델로부터 서비스 선언과 타입을 자동 생성
  • services/service-<name>/src/service.rs & ops/: 요청 라우팅, 거부(Refusal) 오버라이드, 연산별 핸들러 구현
  • services/service-<name>/src/state.rs: 해당 서비스의 인메모리 상태(In-Memory State) 저장소

이 구조 덕분에 유효한 API 요청에는 실제 AWS와 동일한 응답 형식을 돌려주고, 잘못된 입력에는 실제 AWS와 같은 에러 코드를 반환하며, 아직 구현되지 않은 연산은 모호한 500 에러 대신 명확히 501 NotImplemented로 응답한다.

1.2 자율 AI 에이전트 코드 생성 루프와 v1.0.519 Fidelity 실측

Swami Sivasubramanian과 Matt Goldberg의 공식 발표에 따르면, aws-emulator는 초기 SQS 프로토타입을 시작으로 전체 코드베이스가 자율 AI 에이전트 팀에 의해 작성·테스트·유지보수된다. 저장소는 외부인의 Pull Request를 받지 않으며(CONTRIBUTING.md), 아래 3단계 에이전트 파이프라인이 실제 AWS와의 간극(Fidelity Gap)을 매일 메워 나간다:

  1. Test Writers: 공개 Smithy API 모델에서 E2E 고객 시나리오(예: SQS 메시지 수신 후 VisibilityTimeout 동안 다른 소비자에게 숨겨지는지 등)를 도출하고, 실제 AWS 클라우드에 실행해 통과할 때까지 테스트를 보정해 기준선(Baseline)으로 확정한다.
  1. Issue Finders: 동일한 기준선 테스트를 로컬 aws-emulator에 재실행해 상태 코드나 응답 본문 불일치를 탐지하고, 근본 원인별로 묶어 issues/things-that-do-not-work/ 아래에 등록한다.
  1. Fixers & 다중 보안 Merge Gate: 패치를 작성한 뒤 일반 코드 리뷰어 에이전트와 다수의 적대적 보안 리뷰 에이전트, 그리고 허용되지 않은 프레임워크 영역 수정을 막는 결정적 검사(Merge Gate)를 모두 통과해야만 병합된다. 해결된 이슈는 issues/things-that-now-work/로 이동하며 릴리스마다 scores.json.gz가 함께 배포된다.

2026년 11월 19일 배포된 v1.0.519 릴리스의 scores.json.gz(scoredAt: 2026-11-19T04:31:38Z)를 직접 파싱해 집계한 결과는 다음과 같다:

  • 전체 검증 유닛(units): 46,026건
  • 통과(pass): 33,627건 (73.06%)
  • 실패(fail): 12,312건 (26.75%)
  • 스킵(skipped): 87건 (0.19%)

실패 유닛은 expected: 400 ValidationException 대비 actual: 200 같은 상태 코드 불일치, 501 NotImplemented 미구현 연산, 또는 응답 본문(mismatch: "body") 차이로 정량 추적된다. 하루에도 수십~수백 건 단위로 릴리스 버전이 올라갈 만큼(출시 8일 만에 v1.0.519 도달) 에이전트의 패치 속도가 빠르다는 점이 특징이다.

1.3 #[tokio::main]을 쓰지 않고 64 MiB 스택을 수동 할당한 이유

core/router/src/main.rs를 확인해 보면 흥미로운 Rust 시스템 엔지니어링 디테일이 드러난다. 이 파일은 #![forbid(unsafe_code)]를 선언하면서 동시에 주석으로 절대 #[tokio::main]으로 교체하지 말 것을 경고한다.

439개에 달하는 서비스 크레이트를 하나의 라우터로 조립할 때 가장 큰 mount_chunk_NN과 단일 서비스의 ops::register_all 호출이 엄청난 스택 프레임을 소비하기 때문에, OS 기본 스레드 스택으로는 리스너가 :9297 포트를 바인딩하기도 전에 스택 오버플로로 프로세스가 조용히 종료될 수 있다. 이를 막기 위해 aws-emulator-router는 세 가지 장치를 조합한다:

  • 라우터 전용 스레드 64 MiB 스택: EMULATOR_STACK_SIZE = 64 * 1024 * 1024(EMULATOR_STACK_BYTES 환경변수로 오버라이드 가능, 권장 하한 MINIMUM_STACK_SIZE = 32 MiB)로 스레드를 수동 생성해 라우터를 조립한다.
  • Tokio 워커 스레드 16 MiB 스택: 실제 요청 역직렬화가 실행되는 Tokio 워커 스레드에도 수동 빌더로 WORKER_STACK_SIZE = 16 * 1024 * 1024를 부여한다.
  • #[inline(never)] 청크 분할: router/src/lib.rs에서 서비스 마운트 함수를 mount_chunk_NN 헬퍼로 쪼개 단일 스택 프레임에 전체 워크스페이스가 합쳐지지 않게 차단한다.

2. 혼동하기 쉬운 5가지 운영 경계와 비교 표

aws-emulator를 로컬 개발이나 CI에 도입할 때 엔지니어가 가장 자주 오해하는 다섯 가지 경계를 먼저 짚어야 한다.

  • "200개 이상의 AWS 서비스를 지원하니 내 CloudFormation·Terraform·CDK 스택이 바로 다 돌아갈까?" — 그렇지 않다: v1.0.519 기준 Fidelity 통과율은 73.06%이며, 서비스별·연산별 성숙도 편차가 크다. 특히 여러 서비스가 얽히는 복합 IaC 템플릿이나 세부 edge 동작은 501 NotImplemented나 스키마 불일치를 만날 수 있으므로, 릴리스의 scores.json.gz와 issues/things-that-do-not-work/를 먼저 확인해야 한다.
  • "로컬에서 IAM 권한이나 보안 정책도 함께 검증할 수 있을까?" — 공식적으로 금지한다: 공식 보안 문서와 README는 aws-emulator가 오직 빌드·테스트 전용임을 못 박는다. IAM 정책 평가, 크로스 계정·크로스 리전 권한 경계, 실제 AWS API 스로틀링이나 장애 시뮬레이션은 수행하지 않는다.
  • "컨테이너를 재시작해도 S3 버킷이나 DynamoDB 데이터가 유지될까?" — 인메모리 전용이라 전부 초기화된다: 모든 서비스의 state.rs는 프로세스 메모리에만 존재한다. 프로세스를 끄거나 재시작하면 상태가 깨끗이 사라지므로 영속적 로컬 개발 DB 대용보다는 테스트 실행 단위 격리에 적합하다.
  • "macOS나 Windows에서도 소스 빌드나 Rust Embedded 모드를 바로 쓸 수 있을까?" — Linux 전용이며 100 GB+ 디스크가 필요하다: 프리빌트 패키지는 Linux(x86_64/aarch64 RPM·DEB)용으로 제공되며, Windows와 macOS에서는 Docker 컨테이너 실행이 공식 경로다. 특히 소스 빌드나 Rust aws-emulator-embedded 모드는 439개 서비스 크레이트를 전부 컴파일해야 하므로 target/ 디렉터리에 최소 100 GB 이상의 여유 디스크가 필요하다.
  • "완전 오프라인이라면 외부 네트워크 호출이 전혀 없을까?" — Telemetry가 기본 ON이다: aws-emulator는 기본적으로 사용량 텔레메트리(https://aws-emulator-telemetry.us-west-2.api.aws/v1/config)를 수집하도록 켜져 있다. 요청·응답 본문이나 자격 증명·코드는 전송하지 않지만, 폐쇄망이나 사내 보안 정책상 외부 송신을 차단해야 한다면 반드시 --telemetry off, EMULATOR_TELEMETRY=off, 또는 config.toml로 꺼야 한다.
비교 항목
AWS Emulator (aws/aws-emulator)
LocalStack (서드파티 로컬 클라우드)
실제 AWS 샌드박스 계정
라이선스 및 계정 요건
CC0-1.0 (vendor/ Apache-2.0) · AWS 계정·인증 토큰 불필요
2026년 3월 이후 상용·CI 워크플로 계정/인증 토큰 요건 확대
실제 AWS 계정·IAM 자격 증명 및 결제 수단 필수
구현 방식 및 모델 기반
Rust + 공식 Smithy API 모델 (439개 서비스 크레이트, AI 에이전트 유지보수)
Python/커뮤니티·상용 혼합 구현체 + 서드파티 에뮬레이션 엔진
실제 프로덕션 AWS 컨트롤·데이터 플레인
상태 유지 방식
인메모리(In-Memory) 전용 (종료 시 초기화, 포트·테스트별 완벽 격리)
인메모리 + 영속성 스냅샷(State Persistence) 기능 지원
영구 저장 (테스트 후 별도 정리/리소스 삭제 필요)
보안 · IAM · 리전 시뮬레이션
미지원 (빌드·기능 테스트 전용, 보안·IAM·쓰로틀링 검증 불가)
일부 IAM·엔터프라이즈 시뮬레이션 유료/상위 티어 지원
100% 실제 동작 (IAM·KMS·SCP·스로틀링·네트워크 지연 포함)
실행 환경 및 빌드 비용
Linux RPM/DEB, macOS/Windows Docker · 소스/Embedded 빌드 시 target/ 100 GB+
Docker 컨테이너 이미지 중심 배포
원격 API 호출 지연 및 실사용 과금 발생

3. 아키텍처 흐름과 로컬 CLI·SDK 격리 연결 및 Embedded 모드

AWS Emulator 아키텍처(클라이언트·코어 라우터 스택 가드·439개 Smithy 서비스 크레이트) 및 자율 AI 에이전트 Fidelity 검증 파이프라인

3.1 ~/.aws/emulator/9297/ 격리와 실계정 유출 방지 환경변수

aws-emulator를 로컬 프로세스나 컨테이너로 띄우면 기본 포트인 127.0.0.1:9297에서 자체 서명 TLS 기반 HTTPS 서버가 열리고, 홈 디렉터리 아래 ~/.aws/emulator/9297/ 경로에 세션 전용 설정 파일이 자동 생성된다:

  • emulator_credentials: 해당 인스턴스 전용 임시 SigV4 Access/Secret Key
  • config: 로컬 에뮬레이터 대상 AWS CLI/SDK 프로파일 설정
  • ca.pem: 로컬 HTTPS 엔드포인트의 자체 서명 CA 인증서 번들
  • truststore.p12: Java 기반 AWS SDK 클라이언트용 트러스트스토어

실제 AWS 계정에 실수로 리소스를 생성하는 사고를 막으려면, 로컬 리다이렉션 환경변수를 설정하는 동시에 기존 AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN, AWS_PROFILE을 반드시 unset해야 한다.

3.2 헬스체크·AI 에이전트 연동·Embedded 모드 및 Telemetry 차단

환경변수 적용 후에는 아래 두 명령으로 요청이 실제 AWS가 아닌 로컬 에뮬레이터로 향하는지 즉시 검증할 수 있다(sts get-caller-identity는 계정 ID 000000000000을 반환한다):

AI 코딩 에이전트(Kiro, Claude Code, Cursor 등)가 로컬 에뮬레이터를 자동 설치·구동하게 하려면 AWS CLI 2.35.0 이상 환경에서 공식 에이전트 툴킷 스킬을 추가한다:

한편 Rust 프로젝트에서는 포트나 TLS 인증서, 환경변수 없이 테스트 프로세스 내부에 격리된 인스턴스를 직접 띄우는 Embedded 모드(aws-emulator-embedded)도 제공한다. Telemetry를 끈 상태로 Embedded 인스턴스를 생성하는 예시는 다음과 같다:

CLI나 Docker 실행 시 Telemetry를 끄려면 aws-emulator --telemetry off, 환경변수 EMULATOR_TELEMETRY=off(인식되지 않는 임의 문자열 입력 시에도 경고와 함께 비활성화됨), 또는 ~/.aws/emulator/config.toml(Windows는 %USERPROFILE%\.aws\emulator\config.toml)에 [telemetry] enabled = false를 기록한다.

4. 로컬 Python 6대 아키텍처·보안 격리 검증 스크립트

아래 verify_aws_emulator_architecture.py 스크립트는 외부 의존성 없이 Python 표준 라이브러리만으로 ① v1.0.519 릴리스 scores.json.gz의 Fidelity 수치(33,627 / 46,026 = 73.06%) 및 501/상태/본문 불일치 분류, ② core/router/src/main.rs의 EMULATOR_STACK_BYTES(기본 64 MiB·권장 하한 32 MiB) 부팅 스택 가드, ③ ~/.aws/emulator/9297/ 필수 환경변수 및 AWS_PROFILE·AWS_ACCESS_KEY_ID 실계정 유출 탐지, ④ IAM·영속 상태·macOS/Windows Docker·소스 빌드 100 GB 디스크 경계 라우팅, ⑤ Telemetry CLI·환경변수·config.toml 우선순위 판정, ⑥ CC0-1.0 vs vendor/ Apache-2.0 이중 라이선스 및 사람 PR 미수락 정책을 검증한다.

로컬 실행 결과:

5. 실무 도입 및 CI/CD 운영 체크리스트

테스트 대상 서비스의 Fidelity 점수 및 미구현 이슈 사전 확인: 도입 전 최신 릴리스의 scores.json.gz와 저장소 issues/things-that-do-not-work/에서 프로젝트가 의존하는 AWS API 연산이 501 NotImplemented에 걸리지 않는지 확인한다.

실계정 자격 증명 unset 및 AWS_EC2_METADATA_DISABLED=true 강제: CI 러너나 개발 셸에서 AWS_PROFILE·AWS_ACCESS_KEY_ID·AWS_SECRET_ACCESS_KEY를 비우고, AWS_ENDPOINT_URL·AWS_CA_BUNDLE·AWS_DISABLE_HOST_PREFIX_INJECTION=true를 적용한 뒤 aws sts get-caller-identity가 000000000000을 반환하는지 게이트로 확인한다.

보안·IAM·크로스 리전 테스트는 실제 AWS 샌드박스 계정으로 분리: IAM 권한 검증, KMS 키 정책, 크로스 계정 AssumeRole, 쓰로틀링 내성 테스트는 aws-emulator 범위 밖이므로 별도의 격리된 AWS 테스트 계정 파이프라인에서 실행한다.

운영체제·디스크 예산에 맞는 실행 모드 선택: Linux CI에서는 프리빌트 RPM/DEB 또는 Docker를 기본으로 쓰고, Rust Embedded 모드나 소스 빌드를 선택할 때는 target/용 100 GB 이상 여유 공간과 CARGO_TARGET_DIR/sccache 캐싱을 함께 구성한다.

폐쇄망·보안 정책 환경에서는 Telemetry 비활성화 설정 고정: 사내 정책상 외부 텔레메트리 송신이 불가하다면 --telemetry off, EMULATOR_TELEMETRY=off, 또는 config.toml의 enabled = false를 표준 CI 템플릿에 포함한다.

6. 참고 자료 및 공식 출처 (2026-11-19 확인)

확인 기준일: November 19, 2026

추천 글