如何對 Amazon ECS 中 API 呼叫的常見錯誤進行疑難排解?

上次更新日期:2022 年 4 月 12 日

我想對 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 事件中,並可在 Event history (事件歷史記錄) 中找到。您可以檢視、搜尋和下載您 AWS 帳戶中最近發生的事件。

若要檢視 CloudTrail 事件歷史記錄並找到 API 錯誤,請執行以下操作:

  1. 開啟 AWS CloudTrail 主控台
  2. 在導覽窗格中,選擇 Event history (事件歷史記錄)。
  3. 選擇齒輪圖示。
  4. Select visible columns (選取可見欄) 下,選取 Error code (錯誤碼)。
  5. 選擇 Confirm (確認)。
  6. Event history (事件歷史記錄) 頁面中,針對 Lookup attributes (查詢屬性),選擇 Event name (事件名稱)。
  7. 對於 Enter an event name (輸入事件名稱),輸入失敗的動作。
    注意:如果您不知道事件名稱,請執行以下操作:
    對於 Lookup attributes (查詢屬性),選取 事件來源 (事件來源)。
    對於 Enter an event source (輸入事件來源),選取 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. 在導覽窗格中,根據使用者身分選擇 Roles (角色) 或 Users (使用者)。
  3. 使用搜尋篩選條件篩選角色或使用者。
  4. 選擇角色或使用者。
  5. 選擇 Permissions (許可) 標籤。
  6. 展開許可政策以檢視與使用者關聯的許可。
  7. 請確認該政策在 Actions (動作) 清單中包含 ecs:事件名稱,並且 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.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"
                    }
                }
...

此文章是否有幫助?


您是否需要帳單或技術支援?