트러블슈팅

트러블슈팅 (Troubleshooting)

이 섹션은 AWS Lambda MicroVMs로 작업할 때 흔한 문제를 디버그하고 해결하는 방법을 설명해요.

셸 접근

셸 접근을 사용해 실행 중인 MicroVM에 직접 연결해서 디버그하고 트러블슈팅할 수 있어요.

MicroVM 셸에 두 가지 방식으로 연결할 수 있어요.

  • 콘솔 — Lambda 콘솔에서 MicroVM을 선택하고 Connect를 선택해요.
  • CLI — create-microvm-shell-auth-token으로 셸 토큰을 생성한 다음, 그 토큰으로 연결을 설정해요.

셸 토큰을 생성하고 연결해요.

aws lambda-microvms create-microvm-shell-auth-token \
  --microvm-identifier <id> --expiration-in-minutes 30
# In Console: select MicroVM -> Connect
# In shell: ctr task ls, then ctr task exec -t --exec-id shell <id> /bin/sh

MicroVM은 SHELL_INGRESS 네트워크 커넥터(arn:aws:lambda:us-east-1:aws:network-connector:aws-network-connector:SHELL_INGRESS)로 실행되어야 해요. 이 커넥터 없이 MicroVM을 시작했다면 create-microvm-shell-auth-token이 ValidationException을 반환해요.

그 외 문제는 다음을 확인해요.

  • 종료된 MicroVM의 경우 get-microvm 응답의 terminationMessage 필드를 확인해요.
  • 이미지 생성 문제는 CloudWatch 빌드 로그를 확인해요.
  • FAILED 상태의 네트워크 커넥터에 대한 StateReason 필드를 확인해요.

트러블슈팅

이 섹션은 Lambda MicroVMs로 작업할 때 흔한 문제에 대한 해결 방법을 제공해요.

증상 가능한 원인과 해결
이미지 빌드 실패(CREATION_FAILED) /aws/lambda-microvms/<image-name>에서 빌드 로그를 확인해요. Dockerfile 문법, Amazon S3 권한, 기본 이미지 가용성을 검증해요. 로컬에서 docker build를 실행해 재현해요.
MicroVM이 PENDING에서 멈춤 기다렸다가 재시도해요. 지속되면 서비스 상태를 확인해요. 동시성 할당량이 소진되지 않았는지 확인해요.
재개 후 애플리케이션이 응답하지 않음 /resume 수명주기 훅을 구현해 연결을 다시 수립하고 상태를 검증해요. 앱이 재개 후 포트 8080(또는 구성된 포트)에 바인딩하는지 확인해요.
엔드포인트에서 502 Bad Gateway 애플리케이션이 크래시했거나 수신 대기하지 않고 있어요. 런타임 로그를 확인해요. Dockerfile의 EXPOSE와 CMD를 검증해요. 자동 재개라면 MicroVM이 재개에 실패했을 수 있어요(get-microvm으로 상태 확인).
429 Too Many Requests 요청 속도를 초과했어요. 지수 백오프와 지터(jitter)로 재시도해요.
연결 끊김 유휴 타임아웃이 촉발됐어요. ping/pong keepalive를 구현하거나 유휴 정책의 maxIdleDurationSeconds를 늘려요.
엔드포인트의 높은 지연 시간 대역폭 포화예요. 트래픽이 MicroVM 크기의 대역폭 용량을 초과하는지 확인하고 더 큰 크기로 확장해요.
인증 토큰 만료(403) 토큰은 구성 가능한 만료 시간이 있어요. 이전 토큰이 만료되기 전에 새 토큰을 생성해요. 클라이언트에 토큰 갱신 로직을 구현해요.
VPC 이그레스가 동작하지 않음 네트워크 커넥터가 ACTIVE 상태인지 확인해요. 보안 그룹 규칙이 아웃바운드 트래픽을 허용하는지 확인해요. 서브넷이 대상 리소스로의 경로를 갖는지 확인해요.

일반적인 오류 (이미지 생성)

오류 원인 해결
S3_ACCESS_DENIED 빌드 역할에 Amazon S3 아티팩트를 검색할 권한이 없어요. 아티팩트 버킷에 s3:GetObject 권한을 추가해요.
S3_NO_SUCH_KEY 아티팩트 키가 버킷에 없어요. Amazon S3 경로가 올바른지 확인해요.
S3_NO_SUCH_BUCKET Amazon S3 버킷이 존재하지 않아요. 버킷 이름을 확인하고 생성되었는지 확인해요.
S3_INVALID_OBJECT 아티팩트가 Glacier 또는 직접 접근 불가능한 스토리지 클래스에 있어요. 아티팩트를 Standard 스토리지 클래스로 이동해요.
S3_CROSS_REGION_ACCESS_DENIED 아티팩트가 MicroVM 이미지와 다른 리전에 있어요. 아티팩트가 MicroVM 이미지와 같은 리전에 있는지 확인해요.
ARCHIVE_DOCKERFILE_NOT_FOUND zip 아카이브의 루트 디렉터리에 Dockerfile이 없어요. zip 아카이브의 루트에 Dockerfile을 추가해요.
ARCHIVE_INVALID 아카이브 파일이 유효한 ZIP이 아니거나 손상됐어요. zip 아카이브를 다시 만들고 재업로드해요.
CONTAINER_BUILD_FAILED 잘못된 Dockerfile 지시문, 누락된 파일, 또는 문법 오류가 있어요. docker build로 Dockerfile을 로컬에서 디버그해요.
DISK_STORAGE_FULL 빌드 중 MicroVM의 스토리지가 소진됐어요. 아티팩트 크기를 줄이거나 지원팀에 문의해요.
INTERNAL_PLATFORM_ERROR 내부 오류가 발생했어요. 작업을 재시도해요. 지속되면 지원팀에 문의해요.

네트워크 커넥터 트러블슈팅

오류 코드 원인 해결
DisallowedByVpcEncryptionControl VPC에 암호화되지 않은 네트워크 인터페이스나 트래픽을 막는 암호화 제어 정책이 있어요. Lambda가 암호화 요구 사항을 충족하는 ENI를 만들 수 없어요. Lambda를 VPC 암호화 제어 제외 목록에 추가해요. 제외가 불가능하면 제한적인 암호화 제어가 적용되지 않는 VPC나 서브넷을 사용해요.
Ec2RequestLimitExceeded Lambda가 연결을 설정하기 위해 EC2 API 호출(예: CreateNetworkInterface, DescribeSubnets)을 해요. 동시 EC2 API 호출이 너무 많으면 스로틀링이 발생해요. 잠시 후 작업을 재시도해요. 지속되면 동시 네트워크 커넥터 작업을 줄이거나 AWS Support로 EC2 API 스로틀링 한도 증가를 요청해요.
InsufficientRolePermissions 운영자 역할에 필요한 EC2 권한이 없어요. IAM 역할에 필요한 EC2 네트워킹 권한이 있는지 확인해요.
InternalError 네트워크 커넥터 요청을 처리하는 중 Lambda 서비스 내부에서 예기치 않은 오류가 발생했어요. 작업을 재시도해요. 여러 번 재시도해도 지속되면 네트워크 커넥터 ARN과 대략적 타임스탬프와 함께 AWS Support에 문의해요.
InvalidSecurityGroup 보안 그룹 ID가 존재하지 않거나, 삭제됐거나, 지정된 서브넷과 같은 VPC에 속하지 않아요. 모든 보안 그룹 ID가 존재하고 서브넷과 같은 VPC에 속하는지 확인해요. aws ec2 describe-security-groups --group-ids <sg-id>로 검증해요.
InvalidSubnet 서브넷 ID가 존재하지 않거나, 삭제됐거나, 예상과 다른 VPC에 속해요. 모든 서브넷 ID가 존재하고 올바른 VPC에 속하는지 확인해요. aws ec2 describe-subnets --subnet-ids <subnet-id>로 검증해요.
SubnetOutOfIPAddresses 서브넷의 CIDR 블록이 소진됐어요 — 모든 IP가 ENI, 인스턴스, 다른 리소스에 할당되어 Lambda가 네트워크 인터페이스를 만들 수 없어요. 사용하지 않는 ENI/인스턴스를 제거하거나 사용 가능한 용량이 있는 다른 서브넷을 사용해 IP 주소를 확보해요. 네트워크 커넥터에는 더 큰 서브넷(예: /24 이상)을 고려해요.

출처: AWS Lambda 개발자 안내서

더 알아보기 (Learn more)