如何对 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 任务中运行的应用程序也可能会导致 Amazon ECS API 调用失败。

解决方法

**注意：**如果在运行 AWS 命令行界面 (AWS CLI) 命令时收到错误，请参阅 AWS CLI 错误故障排除。此外，请确保您使用的是最新版本的 AWS CLI。

找到 API 调用错误

当 Amazon ECS 中发生活动时，AWS CloudTrail 会将您的 API 请求作为事件记录在 Event history（事件历史记录）中。

要查看您的 AWS CloudTrail 事件历史记录并找到 API 错误，请完成以下步骤：

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

**注意：**您还可以使用 Amazon Athena 通过 errorcode 查询 CloudTrail 日志中的事件。

解决 API 调用错误

根据您收到的错误代码执行以下操作。

AccessDeniedException

如果您的 AWS Identity and Access Management (IAM) 用户或角色没有所需的权限，那么您会收到 "AccessDeniedException" 错误。以下错误示例表明用户 arn:aws:sts::123456789012:assumed-role/test-role/test-session 没有执行 CreateCluster 操作所需的权限：

"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: CreateCluster on resource: * because no identity-based policy allows the ecs:CreateCluster action"

要向 IAM 身份的权限策略添加相应的权限，请完成以下步骤：

打开 IAM 控制台。
在导航窗格中，根据 IAM 身份选择 Roles（角色）、User groups（用户组）或 Users（用户）。
使用搜索筛选条件来筛选角色或用户选项。然后，选择要查看的 IAM 身份。
选择 Permissions（权限）选项卡。
要查看与 IAM 身份关联的权限，请展开权限策略。
在权限策略中，将 ecs:your-event-name 添加到 Actions（操作）列表中。然后，为 Effect（效果）选择 Allow（允许）。或者，创建允许 ecs:your-event-name 的新策略，并将该策略附加到 IAM 角色或用户。有关更多信息，请参阅编辑客户管理型策略（控制台）。

您可以使用 IAM 策略模拟器来测试未附加到 IAM 用户、用户组或角色的策略。

ClientException

如果您的 ECS 客户端指定的标识符或资源无效或不存在，那么您会收到 "ClientException" 错误。以下错误示例表明 RunTask 命令引用的 TaskDefinition 无效：

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

验证您是否在命令、API 调用和代码中引用了正确的资源。

ClusterNotFoundException

如果 Amazon ECS 找不到您为某项操作指定的集群，那么您会收到 "ClusterNotFoundException" 错误。以下错误示例表明 Amazon ECS 找不到您为 StartTask 操作指定的集群：

"An error occurred (ClusterNotFoundException) when calling the StartTask operation: Cluster not found."

验证您是否在命令、API 调用和代码中引用了正确的集群名称。

要列出您当前所有的 ECS 集群，请运行 AWS CLI 命令 list-clusters：

aws ecs list-clusters --region example_region

注意：请将 example_region 替换为您的 AWS 区域。

然后，验证您在 API 调用中引用的集群是否存在。

InvalidParameterException

如果您在命令中输入的参数无效，并且任务定义的版本不存在，那么您会收到以下错误：

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

以下 RunTask 命令示例表明 CentOS:3 任务定义不存在：

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

注意：在上述示例中，将 example_cluster 替换为您的集群名称。

以下错误示例与上述 RunTask 命令相对应：

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

验证命令中的参数是否有效。

ServerException

如果您在进行 API 调用时服务器宕机，那么您会收到 "ServerException" 错误。如果您在所有 API 调用中都收到此错误，则表示 AWS 服务不可用。

ServerException 错误通常是暂时的。请稍后，然后再次进行 API 调用。如果问题仍然存在，请联系 AWS Support 并提供以下信息：

提供与错误相对应的时间戳。
如果您使用命令行，请提供返回错误的命令。
如果您使用编程语言或使用 AWS SDK 的基础设施即代码工具，请提供返回错误的代码块。
如果您使用 AWS 管理控制台，请提供 AWS 管理控制台页面的 URL 以及返回错误的操作。

ServiceNotActiveException

如果您更新处于非活动状态的 Amazon ECS 服务，那么您会收到 "ServiceNotActiveException" 错误。验证要更新的 ECS 服务是否在您的 ECS 集群中且处于 ACTIVE 状态。

要列出集群中的所有服务，请运行 AWS CLI 命令 list-clusters：

aws ecs list-services --cluster example_cluster

**注意：**请将 example_cluster 替换为您的集群名称。

验证命令的输出是否包含要更新的服务。然后，运行 describe-services 命令来验证该服务是否处于 ACTIVE 状态：

aws ecs describe-services --services example_service_name --cluster example_cluster

**注意：**请将 example_service_name 和 example_cluster 替换为您的值。

以下输出示例表明 example-service 处于 ACTIVE 状态：

{    "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",  
        ......  
    }]  
}

如果您的服务未处于 ACTIVE 状态，请验证您的 Amazon ECS 服务的 Number of tasks（任务数）值是否大于零。您还可以运行 AWS CLI 命令 update-service 将 Number of tasks（任务数）值更新为 1：

aws ecs update-service --cluster example_cluster_name --service example_service_name --desired-count 1

**注意：**请将 example_cluster_name 和 example_service_name 替换为您的值。您可以将所需的计数值设置为大于零的数字。

然后，在 ECS 控制台中，验证您的 task definition state（任务定义状态）是否为 ACTIVE。您也可以运行 describe-task-definition 命令：

aws ecs describe-task-definition --task-definition example_taskdefinition

**注意：**请将 example_taskdefinition 替换为您的任务定义。

检查您的 CloudWatch 日志，查看是否存在与您的 ServiceNotActiveException 错误相对应的服务故障或网络审查。

PlatformTaskDefinitionIncompatibilityException

如果您在不满足任务定义所需功能的平台上启动任务，那么您会收到 "PlatformTaskDefinitionIncompatibilityException" 错误。在以下错误示例中，平台版本 1.3.0 不支持 AWS CLI 命令 create-service 的要求：

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

以下 create-service 命令示例使用平台版本 1.3.0 上附加的 Amazon Elastic File System (Amazon EFS) 卷创建服务：

aws ecs create-service \  
    --cluster example_cluster \  
    --task-definition  example_taskdefinition  \  
    --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

验证您的 AWS Fargate 平台版本是否支持您的任务定义所需的功能。

PlatformUnknownException

如果您在启动任务时指定的平台版本未知或不正确，那么您会收到 "PlatformUnknownException" 错误。以下错误示例表明您在创建服务操作中指定的平台版本不正确：

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

以下 create-service 命令示例包含不正确的平台版本 1.3，并非正确的版本 1.3.0：

aws ecs create-service \    --cluster example_cluster\  
    --task-definition example_taskdefinition \  
    --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

验证您在启动任务时指定的平台版本是否正确。有关更多信息，请参阅适用于 Amazon ECS 的 Fargate Linux 平台版本和适用于 Amazon ECS 的 Fargate Windows 平台版本。

ServiceNotFoundException

当您的命令或代码中指定的 ECS 服务不存在时，就会出现 "ServiceNotFoundException" 错误。验证您的命令或代码中的服务名称是否正确，然后确认该服务存在于集群中。要查看集群中的所有服务，请运行 AWS CLI 命令 list-clusters：

aws ecs list-services --cluster example_cluster

**注意：**请将 example_cluster 替换为您的集群。

UnsupportedFeatureException

当您在 Fargate 不支持您的容器的 AWS 区域中启动 Fargate 任务时，就会出现 "UnsupportedFeatureException" 错误。有关更多信息，请参阅 Amazon ECS 在 AWS Fargate 上的支持区域。

对应用程序中的 API 问题进行故障排除

当您访问托管在 ECS 任务中的应用程序时，您可能会收到以下常见的 HTTP 5## 状态代码响应：

如果应用程序遇到意外情况（例如错误），则会出现 "HTTP 500 - Internal server" 错误。或者，如果您错误配置了应用程序，则会收到此错误。
如果 ECS 任务的工作负载繁重，则会出现 "HTTP 503 - Service unavailable" 错误。或者，如果任务中的应用程序因维护而关闭，则会收到此错误。

在 Amazon CloudWatch Logs 中查看 ECS 任务的应用程序日志。每个任务定义都对应一个日志流，其中包含来自该任务的应用程序日志。要查看有关任务定义的日志组和日志流的信息，请运行 describe-task-definition 命令：

aws ecs describe-task-definition --task-definition example_taskdefinition

**注意：**请将 example_task_definition 替换为您的任务定义。

如何对 Amazon ECS 中 API 调用的常见错误进行故障排除？

简短描述

解决方法

找到 API 调用错误

解决 API 调用错误

对应用程序中的 API 问题进行故障排除

相关信息

相关视频

相关内容