Amazon ECS Express Mode 서비스 트러블슈팅

이 섹션은 Express Mode 서비스를 배포·관리할 때 흔히 겪는 문제를 식별하고 해결하는 데 도움을 줘요.

출처: 문서

본문

이 섹션은 Express Mode 서비스를 배포·관리할 때 흔한 문제를 식별하고 해결하는 데 도움을 줍니다.

배포 문제

서비스가 ACTIVE 또는 DRAINING 상태에 멈춤

증상: DescribeServiceRevisions가 리소스가 여전히 프로비저닝 또는 디프로비저닝 중임을 보여주고, DescribeServices가 배포가 안정화되지 않았다고 보여줍니다.
가능한 원인과 해결책:
- IAM 권한 부족 — 태스크 실행 역할(task execution role)과 인프라 역할(infrastructure role)이 각각의 관리형 정책에 표시된 필요한 권한을 갖고 있는지 확인하세요.
```
# Check if the role has the required managed policy
aws iam list-attached-role-policies --role-name ecsTaskExecutionRole
```
- 이미지 풀 실패 — 컨테이너 이미지가 존재하고 접근 가능한지 확인하세요.
```
# Test image pull manually
docker pull 123456789012.dkr.ecr.us-west-2.amazonaws.com/my-app:latest
```
- 네트워크 연결 문제 — 서브넷에 인터넷 접근이나 AWS 서비스용 Amazon VPC 엔드포인트가 있는지 확인하세요.
- 리소스 한도 — 계정에 충분한 Fargate 용량이 있고 서비스 할당량에 도달하지 않았는지 확인하세요.
진단 단계:
- DescribeExpressGatewayService로 현재 Service Revision을 가져온 뒤, DescribeServiceRevisions로 해당 ServiceRevision의 프로비저닝·디프로비저닝 상태를 확인합니다.
- 상세 오류 메시지를 위해 Amazon ECS 콘솔의 서비스 이벤트를 확인합니다.
- 컨테이너 포트가 올바르게 설정되었는지 확인합니다.
- Amazon ECS와 Fargate의 AWS 서비스 할당량을 확인합니다.

태스크 시작 실패

증상: 태스크가 시작에 실패하거나 시작 직후 중지됩니다.
흔한 원인:
- 애플리케이션 오류 — 컨테이너 애플리케이션이 구성 또는 런타임 오류로 종료됩니다.
- 헬스 체크 실패 — 애플리케이션이 예상된 포트나 경로의 헬스 체크에 응답하지 않습니다.
- 리소스 제약 — 애플리케이션에 CPU 또는 메모리 할당이 부족합니다.
- 누락된 환경 변수 또는 시크릿 — 필요한 구성이 애플리케이션에 제공되지 않습니다.
해결 단계:
- DescribeServiceRevisions에서 로그 그룹 이름을 얻어 CloudWatch Logs의 애플리케이션 로그를 확인합니다.
```
aws logs describe-log-streams --log-group-name /ecs/express-service-my-app
aws logs get-log-events --log-group-name /ecs/express-service-my-app --log-stream-name stream-name
```
- 헬스 체크 경로가 HTTP 200 상태를 반환하는지 확인합니다.
- 컨테이너 이미지를 로컬에서 테스트해 올바르게 시작되는지 확인합니다.
- 필요하면 CPU와 메모리 할당을 검토·조정합니다.

사용자 지정 태스크 정의 오류

taskDefinitionArn 파라미터를 사용할 때 InvalidParameterException으로 서비스 생성·업데이트가 실패합니다.

"taskDefinitionArn cannot be provided with primaryContainer, executionRoleArn, taskRoleArn, cpu, or memory." — taskDefinitionArn 파라미터는 같은 API 호출에서 primaryContainer, executionRoleArn, taskRoleArn, cpu, memory와 함께 지정할 수 없습니다. Express Mode는 제공된 태스크 정의에서 이 값들을 파생합니다.
"Task definition must contain a container named 'Main' with a single TCP port mapping." — 태스크 정의가 Express Mode 요구 사항을 충족하지 않습니다. 다음을 갖추어야 합니다:
- Main이라는 이름의 컨테이너
- Main 컨테이너가 컨테이너 포트와 포트 이름이 정의된 정확히 하나의 TCP 포트 매핑을 가질 것
- 태스크 정의의 compatibilities에 FARGATE가 있을 것

연결 문제

로드 밸런서로 애플리케이션에 접근 불가

증상: 애플리케이션 URL이 타임아웃이나 연결 오류를 반환합니다.
트러블슈팅 단계:
1. 리소스가 프로비저닝을 마쳤는지 검증합니다.
2. 태스크가 실행 중이고 healthy한지 확인합니다.
```
aws ecs describe-services --cluster my-cluster --services my-express-service
```
3. Application Load Balancer 대상 그룹 상태를 확인합니다.
```
aws elbv2 describe-target-health --target-group-arn arn:aws:elasticloadbalancing:region:account:targetgroup/name/id
```
4. 애플리케이션이 컨테이너 안에서 올바른 포트로 리슨 중인지 확인합니다.

성능 문제

느린 응답 시간

증상: 애플리케이션 응답이 예상보다 느립니다.

진단 방법:

CPU와 메모리 사용률을 모니터링합니다.

# Check CloudWatch metrics for the service
aws cloudwatch get-metric-statistics \
    --namespace AWS/ECS \
    --metric-name CPUUtilization \
    --dimensions Name=ServiceName,Value=my-express-service Name=ClusterName,Value=my-cluster \
    --start-time 2024-01-01T00:00:00Z \
    --end-time 2024-01-01T01:00:00Z \
    --period 300 \
    --statistics Average

오류나 성능 경고를 위해 애플리케이션 로그를 검토합니다.
자동 확장이 부하에 적절히 응답하는지 확인합니다.
요청 분산을 위해 로드 밸런서 메트릭을 분석합니다.

최적화 전략:
- 리소스가 제약되면 CPU 또는 메모리 할당을 늘립니다.
- 더 일찍 확장하도록 자동 확장 임계값을 조정합니다.
- 애플리케이션 코드와 데이터베이스 쿼리를 최적화합니다.

자동 확장이 예상대로 동작하지 않음

증상: 높은 부하에서 서비스가 확장되지 않거나, 낮은 부하에서 축소되지 않습니다.
트러블슈팅 단계:
1. 자동 확장 정책과 구성을 확인합니다.
```
aws application-autoscaling describe-scaling-policies \
    --service-namespace ecs \
    --resource-id service/my-cluster/my-express-service
```
2. 확장 트리거가 충족되고 있는지 CloudWatch 메트릭을 검토합니다.
3. 서비스에 확장 권한이 있는지 확인합니다(IAM 역할 확인).
4. 확장 활동과 그 결과를 확인합니다.

모니터링과 디버깅 도구

CloudWatch Container Insights 사용하기

포괄적인 모니터링을 위해 Container Insights를 활성화합니다.

aws ecs put-account-setting --name containerInsights --value enabled

Container Insights가 제공하는 것:

CPU, 메모리, 디스크, 네트워크 메트릭
성능 모니터링 대시보드
로그 상관관계와 분석
이상 탐지(anomaly detection)

더 알아보기 (Learn more)

Amazon ECS Express Mode 서비스에 대한 자세한 내용은 AWS 공식 문서를 참고해 주세요.