如何排查 Amazon ECS 中 API 调用的常见错误？

4 分钟阅读

我想排查 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 中发生活动时，该活动将与 Event history（事件历史记录）中的其他 AWS 服务事件一同记录在 CloudTrail 事件。您可以查看、搜索和下载 AWS 账户中的近期事件。

要查看 CloudTrail 事件历史记录并查找 API 错误，请执行以下操作：

打开 AWS CloudTrail 控制台。
在导航窗格中，选择 Event history（事件历史记录）。
选择齿轮图标。
在 Select visible columns（选择可见列）下，选择 Error code（错误代码）。
选择 Confirm（确认）。
在 Event history（事件历史记录）页面中，为 Lookup attributes（查找属性）选择 Event name（事件名称）。
为 Enter an event name（输入事件名称）输入失败的操作。
**注意：**如果您不知道事件名称，请执行以下操作：
为 Lookup attributes（查找属性）选择 Event source（事件源）。
为 Enter an event source（输入事件源）选择 ecs.amazonaws.com，以过滤与您的 ECS 服务相关的所有事件。
从结果列表中，选择包含所选错误代码的事件，查看事件详细信息。

AccessDeniedException

如果 AWS Identity and Access Management（IAM）用户或角色在没有执行请求的操作所需权限的情况下进行 API 调用，则系统会记录此错误。

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 策略模拟器。

要解决此错误，请执行以下操作：

打开 IAM 控制台。
在导航窗格中，根据用户身份选择 Roles（角色）或 Users（用户）。
使用搜索筛选器筛选角色或用户。
选择角色或用户。
选择 Permissions（权限）选项卡。
展开权限策略，查看与用户关联的权限。
确保策略在 Actions（操作）列表中包含 ecs:your-event-name，并且 Effect（生效）中包含 Allow（允许）参数。如果策略不包含这些参数，请更新策略以包含这些更改。或者，创建允许上述操作的新策略，并将该策略附加到 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，而不是版本 1.3.0：

$ 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 - Internal Server Error（500 – 内部服务器错误）：当应用程序遇到意外情况时，您会收到此错误。出现此错误的原因可能是应用程序配置错误或应用程序出现故障。

503 - Service Unavailable（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"
                    }
                }
...