# 문제 해결
<a name="microvms-troubleshooting"></a>

이 섹션에서는 AWS Lambda MicroVM 작업 시 발생할 수 있는 일반적인 문제를 디버깅하고 해결하는 방법을 설명합니다.

## 쉘 액세스
<a name="microvms-troubleshooting-shell"></a>

쉘 액세스를 사용하여 디버깅 및 문제 해결을 위해 실행 중인 MicroVM에 직접 연결합니다.

다음 두 가지 방법으로 MicroVM 쉘에 연결할 수 있습니다.
+ **콘솔** - Lambda 콘솔에서 MicroVM을 선택하고 연결을 선택합니다.
+ **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`을 반환합니다.

기타 문제의 경우
+ `get-microvm` 응답의 `terminationMessage` 필드에서 종료된 MicroVM을 확인합니다.
+ CloudWatch 빌드 로그에서 이미지 생성 문제를 확인합니다.
+ `StateReason` 필드에서 `FAILED` 상태의 네트워크 커넥터를 확인합니다.

## 문제 해결
<a name="microvms-troubleshooting-troubleshooting"></a>

이 섹션에서는 Lambda MicroVM 작업 시 발생하는 일반적인 문제에 대한 해결 방법을 제공합니다.


| 증상 | 가능한 원인 및 해결 방법 | 
| --- | --- | 
| 이미지 빌드 실패(CREATION\_FAILED) | /aws/lambda/microvms/<image-name>에서 빌드 로그를 확인합니다. Dockerfile 구문, Amazon S3 권한 및 기본 이미지 가용성을 확인합니다. 로컬에서 docker build를 실행하여 재현합니다. | 
| MicroVM이 PENDING 상태에서 멈춤 | 기다렸다가 다시 시도하세요. 지속될 경우 서비스 상태를 확인합니다. 동시성 할당량이 소진되지 않았는지 확인합니다. | 
| 재개 후 애플리케이션이 응답하지 않음 | /resume 수명 주기 후크를 구현하여 연결을 재설정하고 상태를 검증합니다. 재개 후 앱이 포트 8080 또는 구성된 포트에 바인딩되는지 확인합니다. | 
| 엔드포인트에서 502 잘못된 게이트웨이 오류 발생 | 애플리케이션이 충돌했거나 수신하고 있지 않습니다. 런타임 로그를 확인합니다. Dockerfile에서 EXPOSE 및 CMD를 확인합니다. 자동 재개의 경우 MicroVM 재개에 실패했을 수 있습니다(get-microvm을 통해 상태 확인). | 
| 429 요청이 너무 많음 | 요청 속도가 초과되었습니다. 지수 백오프와 지터를 사용하여 재시도합니다. | 
| 연결 끊김 | 유휴 제한 시간이 트리거되었습니다. ping/pong 킵얼라이브를 구현합니다. 또는 유휴 정책에서 maxIdleDurationSeconds를 연장합니다. | 
| 엔드포인트의 긴 지연 시간 | 대역폭 포화 상태입니다. 트래픽이 MicroVM 크기의 대역폭 기능을 초과하는지 확인합니다. 더 큰 크기로 스케일 업합니다. | 
| 인증 토큰 만료(403) | 토큰에는 구성 가능한 만료가 있습니다. 이전 토큰이 만료되기 전에 새 토큰을 생성합니다. 클라이언트에서 토큰 새로 고침 로직을 구현합니다. | 
| VPC 송신 작동 안 함 | 네트워크 커넥터가 ACTIVE 상태인지 확인합니다. 보안 그룹 규칙이 아웃바운드 트래픽을 허용하는지 확인합니다. 서브넷에 대상 리소스에 대한 경로가 있는지 확인합니다. | 

## 일반적인 오류(이미지 생성)
<a name="microvms-troubleshooting-image-errors"></a>


| 오류 | 원인 | 솔루션 | 
| --- | --- | --- | 
| S3\_ACCESS\_DENIED | 빌드 역할에 Amazon S3 아티팩트를 검색할 수 있는 권한이 없습니다. | 아티팩트 버킷에 대한 s3:GetObject 권한을 추가합니다. | 
| S3\_NO\_SUCH\_KEY | 아티팩트 키가 버킷에 없습니다. | Amazon S3 경로가 올바른지 확인합니다. | 
| S3\_NO\_SUCH\_BUCKET | Amazon S3 버킷이 존재하지 않습니다. | 버킷 이름을 확인하고 생성되었는지 확인합니다. | 
| S3\_INVALID\_OBJECT | Glacier 또는 직접 액세스할 수 없는 스토리지 클래스에 있는 아티팩트입니다. | 아티팩트를 표준 스토리지 클래스로 이동합니다. | 
| 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 | 내부 오류가 발생했습니다. | 작업을 다시 시도합니다. 지속될 경우 지원팀에 문의합니다. | 

## 네트워크 커넥터 문제 해결
<a name="microvms-troubleshooting-connector-errors"></a>


| 오류 코드 | 원인 | 솔루션 | 
| --- | --- | --- | 
| DisallowedByVpcEncryptionControl | VPC에는 암호화되지 않은 네트워크 인터페이스 또는 트래픽을 방지하는 암호화 제어 정책이 있습니다. Lambda는 암호화 요구 사항을 충족하는 ENI를 생성할 수 없습니다. | VPC 암호화 제어 제외 목록에 Lambda를 추가합니다. 제외가 불가능한 경우 제한적인 암호화 제어가 적용되지 않은 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 이상)을 고려합니다. |