如何在 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 Command Line Interface (AWS CLI) 命令時收到錯誤，請參閱AWS CLI 錯誤疑難排解。此外，請確定您使用的是最新的 AWS CLI 版本。

找出 API 呼叫錯誤

當 Amazon ECS 中發生活動時，AWS CloudTrail 會將您的 API 請求記錄為事件歷史記錄中的事件。

若要檢視您的 AWS CloudTrail 事件歷史記錄並找出 API 錯誤，請完成以下步驟：

開啟 CloudTrail console (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 console (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 叢集，請執行 list-clusters AWS CLI 命令：

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 管理主控台頁面的網址，以及會傳回錯誤的動作。

ServiceNotActiveException

如果您更新非作用中的 Amazon ECS 服務，則會收到「ServiceNotActiveException」錯誤。請確認您要更新的 ECS 服務位於您的 ECS 叢集中，且處於作用中狀態。

若要列出叢集中的所有服務，請執行 list-clusters AWS CLI 命令：

aws ecs list-services --cluster example_cluster

**注意：**將 example_cluster 替換為您的叢集名稱。

確認命令輸出包含您要更新的服務。然後，執行 describe-services 命令，確認服務處於作用中狀態：

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

**注意：**將 example_service_name 和 example_cluster 替換為您的值。

以下輸出範例表示 example-service 處於作用中狀態：

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

如果您的服務未處於作用中狀態，請確認您的 Amazon ECS 服務 Number of tasks (任務數量) 值大於零。您也可以執行 update-service AWS CLI 命令，將您的 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 Console 中，確認您的 task definition state (任務定義狀態) 為作用中。您也可以執行 describe-task-definition 命令：

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

**注意：**將 example_taskdefinition 替換為您的任務定義。

檢查您在 Amazon CloudWatch Logs 中的 CloudWatch 日誌，找出與您的 ServiceNotActiveException 錯誤對應的服務失敗或網路檢閱。

PlatformTaskDefinitionIncompatibilityException

如果您在不符合任務定義所需能力的平台上啟動任務，則會收到「PlatformTaskDefinitionIncompatibilityException」錯誤。在以下錯誤範例中，平台版本 1.3.0 不支援 create-service AWS CLI 命令的需求：

「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」錯誤。請確認您命令或程式碼中的服務名稱正確，然後確認該服務位於叢集中。若要檢視叢集中的所有服務，請執行 list-clusters AWS CLI 命令：

aws ecs list-services --cluster example_cluster

**注意：**將 example_cluster 替換為您的叢集。

UnsupportedFeatureException

當您在 AWS Fargate 不支援您容器的 AWS 區域中啟動 Fargate 任務時，就會發生「UnsupportedFeatureException」錯誤。如需更多資訊，請參閱 AWS Fargate 上 Amazon ECS 的支援區域。

對應用程式中的 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 失敗原因

主題: Containers
標籤: Amazon Elastic Container Service
語言: 中文 (繁體)