AWS Emulator 연동 가이드 — 타 세션 접근법

이 문서는 다른 세션(다른 AI 에이전트 세션, 다른 터미널, 다른 프로젝트, CI 스크립트)이
이 머신에 이미 구성된 AWS Emulator 환경에 접속하는 방법을 정리합니다.
(사람용 기본 사용법은 08_README.md 참고)


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

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 추가).

7. SDK별 인증서 추가 설정

AWS_CA_BUNDLE을 읽는 클라이언트: AWS CLI v2, Boto3, Go v2 — 추가 설정 불필요.

SDK추가 설정
Node.js v3NODE_EXTRA_CA_CERTS = ca.pem 경로
Java 2.xJAVA_TOOL_OPTIONS=-Djavax.net.ssl.trustStore=<truststore.p12 경로> -Djavax.net.ssl.trustStoreType=PKCS12
RustSSL_CERT_FILE = ca.pem 경로
.NETSSL_CERT_FILE = ca.pem 경로

Windows 경로에서 ca.pem이 UNC(\\wsl.localhost\...)으로 안 열리는 구형 도구는, 기동 확인 직후 세션 임시 폴더로 복사해 사용하고 재기동 시 다시 받으세요(캐시 금지).

8. 세션이 지켜야 할 규칙

  1. 자격증명·인증서를 복사·캐시하지 않기 — 매 기동마다 재생성됩니다. 항상 고정 경로(위 표)를 참조하세요.
  2. 리소스는 메모리에만 존재 — 중지하면 모두 사라집니다. 테스트 격리 목적에는 장점.
  3. Region 1개 가정(권장 us-east-1) — 병렬 세션 격리가 필요하면 포트를 달리 기동: aws-emulator -p 9300 → 파일은 ~/.aws/emulator/9300/에 생깁니다(환경변수 경로의 9297도 포트에 맞게 변경).
  4. AWS_ENDPOINT_URL이 없는 셸은 실제 AWS를 호출 — 세션 끝날 때 unset AWS_ENDPOINT_URL 후 종료하면 안전합니다.
  5. 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. 참조