AWS re:Post을(를) 사용하면 다음에 동의하게 됩니다. AWS re:Post 이용 약관
AWS re:Postre:Post

Amazon ECS에서 API 호출과 관련된 일반적인 오류를 해결하려면 어떻게 해야 합니까?

7분 분량
0

Amazon Elastic Container Service(Amazon ECS)에서 API 호출과 관련된 일반적인 오류를 해결하고 싶습니다.

간략한 설명

Amazon ECS API가 다음 오류 중 하나로 인해 실패할 수 있습니다.

  • AccessDeniedException
  • ClientException
  • ClusterNotFoundException
  • InvalidParameterException
  • ServerException
  • ServiceNotActiveException
  • PlatformTaskDefinitionIncompatibilityException
  • PlatformUnknownException
  • ServiceNotFoundException
  • UnsupportedFeatureException

Amazon ECS 태스크 내에서 실행 중인 애플리케이션에 API 문제가 발생할 수도 있습니다.

해결 방법

API 요청은 AWS CloudTrail에 이벤트로 기록됩니다. Amazon ECS에서 활동이 발생하면 해당 활동은 이벤트 기록의 다른 AWS 서비스 이벤트와 함께 CloudTrail 이벤트에 기록됩니다. AWS 계정에서 최근 이벤트를 보고, 검색하고, 다운로드할 수 있습니다.

CloudTrail 이벤트 기록을 보고 API 오류를 찾으려면 다음을 수행합니다.

  1. AWS CloudTrail 콘솔을 엽니다.
  2. 탐색 창에서 [이벤트 기록]을 선택합니다.
  3. 톱니바퀴 아이콘을 선택합니다.
  4. 표시되는 열 선택에서 [오류 코드]를 선택합니다.
  5. [확인]을 선택합니다.
  6. 이벤트 기록 페이지의 [속성 조회]에서 [이벤트 이름]을 선택합니다.
  7. 이벤트 이름 입력에 실패한 작업을 입력합니다.
    참고: 이벤트 이름을 모르는 경우 다음을 수행합니다.
    속성 조회에서 [이벤트 소스]를 선택합니다.
    이벤트 소스 입력에서 ecs.amazonaws.com을 선택하여 ECS 서비스와 관련된 모든 이벤트를 필터링합니다.
  8. 결과 목록에서 선택한 오류 코드의 이벤트를 선택하여 이벤트 세부 정보를 확인합니다.

AccessDeniedException

이 오류는 API 호출을 수행하는 AWS Identity and Access Management(IAM) 사용자 또는 역할에 요청된 작업을 수행하는 데 필요한 권한이 없을 때 기록됩니다.

AccessDeniedException 오류는 다음과 유사합니다.

An error occurred (AccessDeniedException) when calling the CreateCluster operation: User: arn:aws:sts::123456789012:assumed-role/test-role/test-session is not authorized to perform: ecs:CreateCluster on resource: * because no identity-based policy allows the ecs:CreateCluster action

관련 CloudTrail 이벤트 레코드에서 다음 세부 정보를 볼 수 있습니다.

  • 사용자 정보:
"type": "AssumedRole",
"principalId": "AROAZEPPWYLQU45ZDJY6V:test-session",
"arn": "arn:aws:sts::123456789012:assumed-role/test-role/test-session"
  • 이벤트 이름:
"eventName": "CreateCluster"
  • 오류 메시지:
"errorMessage": "User: arn:aws:sts::123456789012:assumed-role/test-role/test-session is not authorized to perform: ecs:CreateCluster on resource: * because no identity-based policy allows the ecs:CreateCluster action"

사용자, 사용자 그룹 또는 역할에 연결되지 않은 정책을 테스트하려면 IAM 정책 시뮬레이터를 사용합니다.

이 오류를 해결하려면 다음을 수행합니다.

  1. IAM 콘솔을 엽니다.
  2. 탐색 창에서 사용자 자격 증명에 따라 역할 또는 사용자를 선택합니다.
  3. 검색 필터를 사용하여 역할이나 사용자를 필터링합니다.
  4. 역할 또는 사용자를 선택합니다.
  5. [권한] 탭을 선택합니다.
  6. 권한 정책을 확장하여 사용자와 연결된 권한을 봅니다.
  7. 정책에 작업 목록과 효과에 대한 허용에 ecs:your-event-name이 포함되어 있는지 확인합니다. 정책에 이러한 파라미터가 포함되어 있지 않으면 이러한 변경 사항을 포함하도록 정책을 업데이트합니다. 또는 언급된 작업을 허용하는 새 정책을 생성하고 IAM 역할 또는 사용자에게 정책을 연결합니다. 자세한 내용은 고객 관리형 정책 편집(콘솔)을 참조하세요.

ClientException

이 오류는 ECS 클라이언트가 유효하지 않거나 존재하지 않는 식별자 또는 리소스를 지정할 때 기록됩니다. 예를 들어 RunTask 또는 StartTask API를 사용하여 태스크를 시작하고 잘못된 태스크 정의를 참조하려고 하면 다음 오류가 발생합니다.

$ aws ecs run-task --cluster example-cluster --task-definition centos --region ap-southeast-2
An error occurred (ClientException) when calling the RunTask operation: TaskDefinition not found.
$ aws ecs start-task --cluster example-cluster --task-definition centos --container-instances 765936fadbdd46b5991a4bd70c2a43d4 --region ap-southeast-2
An error occurred (ClientException) when calling the StartTask operation: TaskDefinition not found.

이 오류를 방지하려면 명령, 코드 또는 API 호출에서 참조된 리소스가 존재하고 유효한지 확인합니다.

ClusterNotFoundException

이 오류는 지정된 클러스터를 찾을 수 없을 때 기록됩니다.

예:

$ aws ecs run-task --task-definition CentOS --cluster example-cluster --region ap-southeast-2
An error occurred (ClusterNotFoundException) when calling the StartTask operation: Cluster not found.

이 오류를 방지하려면 명령, 코드 또는 API 호출에서 전달하는 클러스터 이름이 올바른지 확인합니다. 다음 명령을 실행하여 기존 ECS 클러스터를 나열할 수 있습니다. 반환된 목록을 사용하여 API 호출에 언급된 클러스터가 존재하는지 확인할 수 있습니다.

$ aws ecs list-clusters --region example-region
{
    "clusterArns": [
        "arn:aws:ecs:ap-southeast-2:123456789012:cluster/my-cluster",
        "arn:aws:ecs:ap-southeast-2:123456789012:cluster/my-private-cluster"
    ]
}

InvalidParameterException

이 오류는 명령에 전달된 파라미터가 유효하지 않을 때 기록됩니다. 존재하지 않는 태스크 정의 버전을 언급했다고 가정해 보겠습니다.

$ aws ecs run-task --task-definition CentOS:3 --cluster example-cluster --region ap-southeast-2

그러면 다음과 비슷한 오류가 나타납니다.

An error occurred (InvalidParameterException) when calling the RunTask operation: TaskDefinition not found.

이 오류를 방지하려면 명령에 전달된 파라미터가 올바른지 확인합니다.

ServerException

이 오류는 API 호출과 관련된 서버 오류가 있을 때 기록됩니다. ServerException은 일반적으로 HTTP 오류 코드 500으로 인해 발생합니다. 이 예외는 AWS 리전의 ECS 서비스에 문제가 있는 경우 발생합니다. 이 오류는 일반적으로 일시적이며 이후에 API를 실행하려는 시도가 성공해야 합니다. 하지만 문제가 오랫동안 지속되면 AWS Support에 문의하세요.

ServiceNotActiveException

이 오류는 업데이트 중인 ECS 서비스가 활성 상태가 아닐 때 발생합니다. 업데이트 중인 ECS 서비스가 ECS 클러스터에 있고 활성 상태인지 확인합니다.

다음 AWS Command Line Interface(AWS CLI) 명령을 실행하여 클러스터의 모든 서비스를 나열합니다.

$ aws ecs list-services --cluster example-cluster

출력에서 업데이트 중인 서비스가 표시되는지 확인합니다.

참고: AWS CLI 명령을 실행할 때 오류가 발생하는 경우, 최신 버전의 AWS CLI를 사용하고 있는지 확인합니다.

그런 다음, 다음 명령을 실행하여 서비스가 활성 상태인지 확인합니다.

$ aws ecs describe-services --services example-service-name --cluster example-cluster

출력은 다음과 유사합니다.

{
    "services": [{
        "serviceArn": "arn:aws:ecs:ap-southeast-2:111122223333:service/my-cluster/example-service",
        "serviceName": "example-service",
        "clusterArn": "arn:aws:ecs:ap-southeast-2:111122223333:cluster/example-cluster",
        "loadBalancers": [],
        "serviceRegistries": [],
        "status": "ACTIVE",
        ......
    }]
}

PlatformTaskDefinitionIncompatibilityException

이 오류는 태스크 정의에 필요한 기능을 충족하지 않는 플랫폼에서 태스크가 시작될 때 발생합니다. 플랫폼 버전 1.3.0에 연결된 Amazon EFS 볼륨으로 서비스를 생성하려고 한다고 가정해 보겠습니다.

$ aws ecs create-service \
    --cluster example-cluster \
    --task-definition Test-fargate-EFS \
    --launch-type FARGATE \
    --service-name example-service \
    --desired-count 1 \
    --network-configuration="awsvpcConfiguration={subnets=["subnet-ed7d31b5","subnet-833ef1cb"],securityGroups=["sg-eeb28aa1"]}" \
    --platform-version 1.3.0

그러면 다음 오류가 발생합니다.

An error occurred (PlatformTaskDefinitionIncompatibilityException) when calling the CreateService operation: One or more of the requested capabilities are not supported.

이 문제를 해결하려면 태스크 정의에서 기능 요구 사항을 지원하는 플랫폼 버전을 사용해야 합니다. 다양한 플랫폼 버전에서 지원되는 기능에 대한 자세한 내용은 AWS Fargate 플랫폼 버전을 참조하세요.

PlatformUnknownException

태스크를 시작할 때 알 수 없거나 잘못된 플랫폼 버전을 지정한 경우 이 오류가 발생합니다. 버전 1.3.0 대신 잘못된 플랫폼 버전 1.3을 제공했다고 가정해 보겠습니다.

$ aws ecs create-service \
    --cluster example-cluster\
    --task-definition example-task \
    --launch-type FARGATE\
    --enable-execute-command \
    --service-name example-service\
    --desired-count 1 \
    --network-configuration="awsvpcConfiguration={subnets=["subnet-ed7d31b5","subnet-833ef1cb"],securityGroups=["sg-eeb28aa1"]}"\
    --platform-version 1.3

그러면 다음 오류가 발생합니다.

An error occurred (PlatformUnknownException) when calling the CreateService operation: The specified platform does not exist.

자세한 내용은 Linux 플랫폼 버전 및 Windows 플랫폼 버전을 참조하세요.

ServiceNotFoundException

이 오류는 명령이나 코드에 지정된 ECS 서비스가 없을 때 발생합니다. 명령이나 코드의 서비스 이름이 올바르고 서비스가 클러스터에 있는지 확인합니다.

클러스터의 모든 서비스를 보려면 다음 명령을 실행합니다.

$ aws ecs list-services --cluster example-cluster

UnsupportedFeatureException

이 오류는 특정 리전에서 ECS 기능을 사용할 수 없는 경우에 발생합니다. 예를 들어 새로 시작된 리전에서는 AWS Fargate 기능을 즉시 사용하지 못할 수 있습니다. 이 리전에서 Fargate 태스크가 시작되면 UnsupportedFeatureException 오류가 발생합니다.

애플리케이션 API 문제

다음은 ECS 태스크 내에서 호스팅되는 애플리케이션에 액세스할 때 발생할 수 있는 가장 일반적인 HTTP 5xx 오류 중 일부입니다.

500 - 내부 서버 오류: 애플리케이션에 예기치 않은 상태가 발생하면 이 오류가 발생합니다. 이 오류는 애플리케이션 구성 오류 또는 애플리케이션 오류로 인해 발생할 수 있습니다.

503 - 서비스를 사용할 수 없음: 이 오류는 다음 조건에서 발생합니다.

  • ECS 태스크의 워크로드가 너무 많아 요청을 처리할 수 없습니다.
  • 태스크 내에서 실행 중인 애플리케이션이 유지 관리를 위해 중단됩니다.

이러한 오류를 해결하려면 다음을 수행합니다.

Amazon CloudWatch Logs에서 ECS 태스크에 대한 애플리케이션 로그를 분석합니다. 태스크 정의에서 로그 그룹에 대한 정보를 찾을 수 있습니다. 각 태스크는 태스크의 애플리케이션 로그를 포함하는 개별 로그 스트림과 연결됩니다.

태스크에 대한 로그 그룹 및 로그 스트림을 보려면 다음 명령을 실행합니다.

$ aws ecs describe-task-definition —task-definition example-taskdefinition

출력은 다음과 유사합니다.

...
                "logConfiguration": {
                    "logDriver": "awslogs",
                    "options": {
                        "awslogs-group": "/ecs/example-task",
                        "awslogs-region": "ap-southeast-2",
                        "awslogs-stream-prefix": "ecs"
                    }
                }
...

관련 정보

API 실패 사유

주제
컨테이너
태그
Amazon Elastic Container Service
언어
한국어
AWS 공식
AWS 공식업데이트됨 2년 전
댓글 없음

관련 콘텐츠