AWS Emulator 연동 가이드 — 타 세션 접근법
이 문서는 다른 세션(다른 AI 에이전트 세션, 다른 터미널, 다른 프로젝트, CI 스크립트)이
이 머신에 이미 구성된 AWS Emulator 환경에 접속하는 방법을 정리합니다.
(사람용 기본 사용법은 08_README.md 참고)
- 구성일: 2026-11-13 / 최종 갱신: 2026-11-18 (AWS Emulator 1.0.507 · Windows AWS CLI 2.41.0 · uv 0.13.9) / WSL2 Ubuntu (ARM64)
- 최종 확인: 2026-11-18 헬스체크
ok(Windows·WSL), STSAccount 000000000000양쪽 PASS
1. 한 줄 요약
WSL2 Ubuntu에 설치된 공식 AWS Emulator가 https://127.0.0.1:9297 (HTTPS, 자체 서명 인증서)을 서비스합니다.
Windows에서도 localhost 포워딩으로 같은 주소를 그대로 씁니다. 접속에는 (1) 헬스체크 → (2) 필요 시 기동 → (3) 환경변수 설정 → (4) aws sts get-caller-identity 검증 순서를 따르면 됩니다.
2. 핵심 경로
| 항목 | WSL 경로 | Windows 경로 |
|---|---|---|
| 자격증명 | /root/.aws/emulator/9297/emulator_credentials | \\wsl.localhost\Ubuntu\root\.aws\emulator\9297\emulator_credentials |
| SDK 설정 | /root/.aws/emulator/9297/config | \\wsl.localhost\Ubuntu\root\.aws\emulator\9297\config |
| CA 인증서 | /root/.aws/emulator/9297/ca.pem | \\wsl.localhost\Ubuntu\root\.aws\emulator\9297\ca.pem |
| 스크립트 모음 | /mnt/c/work/서치독_프로젝트/aws-emulator/scripts/ | C:\work\서치독_프로젝트\aws-emulator\scripts\ |
WSL 배포판 이름: Ubuntu (기본 사용자 root). AWS CLI v2: WSL 2.40.2 · Windows 2.41.0(ARM64 네이티브) 모두 설치됨(2026-11-18 기준).
3. 1단계 — 실행 여부 확인
Windows 어디서든(PowerShell/Git Bash):
curl.exe -sf --cacert "\\wsl.localhost\Ubuntu\root\.aws\emulator\9297\ca.pem" https://127.0.0.1:9297/__admin/health
- 응답
ok→ 실행 중. 4단계로. - 실패 → 4단계 전에 기동 필요.
WSL 터미널에서는: pgrep -x aws-emulator
주의: 재부팅이나 wsl --shutdown 이후에는 에뮬레이터가 내려가 있고, 이전 자격증명 파일은 무효입니다(재기동 시 새로 생성됨). 헬스체크 실패 시 확인할 것 없이 재기동이 정답입니다.
4. 2단계 — 기동 (실행 중이 아니면)
powershell -NoProfile -ExecutionPolicy Bypass -File "C:\work\서치독_프로젝트\aws-emulator\scripts\start-emulator.ps1"
WSL 터미널에서 직접:
bash /mnt/c/work/서치독_프로젝트/aws-emulator/scripts/start-emulator.wsl.sh
WSL 안에서 백그라운드(nohup)로 띄우며 30초 이내 헬스체크로 완료를 확인합니다. 로그: WSL의 /tmp/aws-emulator.log. 이미 실행 중이면 "이미 실행 중"을 출력하고 종료합니다(idempotent).
5. 3단계 — 세션에 환경변수 연결
방법 A: 스크립트 재사용 (권장, 절대경로로 어디서든)
# WSL / Git Bash (bash) source /mnt/c/work/서치독_프로젝트/aws-emulator/scripts/env-wsl.sh
# Windows PowerShell (dot-source) . "C:\work\서치독_프로젝트\aws-emulator\scripts\env-windows.ps1"
방법 B: 스크립트 없이 직접 설정 (CI·임베디드 세션용)
WSL/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
Windows PowerShell:
$emu = "\\wsl.localhost\Ubuntu\root\.aws\emulator\9297" $env:AWS_ENDPOINT_URL = "https://127.0.0.1:9297" $env:AWS_SHARED_CREDENTIALS_FILE = "$emu\emulator_credentials" $env:AWS_CONFIG_FILE = "$emu\config" $env:AWS_CA_BUNDLE = "$emu\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
6. 4단계 — 연결 검증 (반드시 수행)
aws sts get-caller-identity
Windows 세션이면 scripts/verify-windows.ps1 실행으로 env 적용+검증이 한 번에 됩니다(2026-11-18 추가).
"Account": "000000000000","Arn": "arn:aws:iam::000000000000:user/emulator"→ 성공- 실제 계정 ID가 보이면 → 실제 AWS를 호출 중.
AWS_ENDPOINT_URL누락 여부 확인. - 자격증명 거부 오류 → 이전 기동의 파일 참조 중. 스크립트를 다시 source하거나 에뮬레이터 재기동.
7. SDK별 인증서 추가 설정
AWS_CA_BUNDLE을 읽는 클라이언트: AWS CLI v2, Boto3, Go v2 — 추가 설정 불필요.
| SDK | 추가 설정 |
|---|---|
| Node.js v3 | NODE_EXTRA_CA_CERTS = ca.pem 경로 |
| Java 2.x | JAVA_TOOL_OPTIONS=-Djavax.net.ssl.trustStore=<truststore.p12 경로> -Djavax.net.ssl.trustStoreType=PKCS12 |
| Rust | SSL_CERT_FILE = ca.pem 경로 |
| .NET | SSL_CERT_FILE = ca.pem 경로 |
Windows 경로에서 ca.pem이 UNC(\\wsl.localhost\...)으로 안 열리는 구형 도구는, 기동 확인 직후 세션 임시 폴더로 복사해 사용하고 재기동 시 다시 받으세요(캐시 금지).
8. 세션이 지켜야 할 규칙
- 자격증명·인증서를 복사·캐시하지 않기 — 매 기동마다 재생성됩니다. 항상 고정 경로(위 표)를 참조하세요.
- 리소스는 메모리에만 존재 — 중지하면 모두 사라집니다. 테스트 격리 목적에는 장점.
- Region 1개 가정(권장
us-east-1) — 병렬 세션 격리가 필요하면 포트를 달리 기동:aws-emulator -p 9300→ 파일은~/.aws/emulator/9300/에 생깁니다(환경변수 경로의9297도 포트에 맞게 변경). AWS_ENDPOINT_URL이 없는 셸은 실제 AWS를 호출 — 세션 끝날 때unset AWS_ENDPOINT_URL후 종료하면 안전합니다.localhost가 아니라127.0.0.1유지 — S3가 호스트명에 버킷을 붙이는 문제 회피. S3 Control(계정ID 호스트명)은 미지원.
9. 문제 해결
| 증상 | 조치 |
|---|---|
| 헬스체크 실패 | start-emulator 재실행 → 여전히 실패 시 WSL에서 tail /tmp/aws-emulator.log |
| 자격증명 거부 | 재기동 직후라면 스크립트 재 source; 아니면 재기동 |
| 포트 충돌(9297 사용 중) | aws-emulator -p <다른포트> 로 기동하고 환경변수 포트 변경 |
| Windows→WSL 포워딩 안 됨 | wsl.exe --shutdown 후 start-emulator (WSL 재시작으로 대부분 해결) |
10. 참조
- 사용자용 기본 가이드: 08_README.md
- 공식 문서(SDK 연결): https://docs.aws.amazon.com/emulator/latest/userguide/point-sdk-to-emulator.html
- 다른 ZCode 세션은 프로젝트 메모리(
aws-emulator-wsl-setup)로 이 구성을 자동 인지합니다.