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 のサービスのイベントが [Event history] (イベント履歴) に記録されるとともに、CloudTrail イベントに記録されます。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] (ルックアップ属性) で、[Event source] (イベントソース) を選択します。
    [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:your-event-name が含まれており、[Effect] (効果) が [Allow] (許可) であることを確認します。ポリシーにこれらのパラメータが含まれていない場合は、ポリシーを更新してこれらの変更を含めます。または、前述のアクションを許可する新しいポリシーを作成し、そのポリシーを IAM ロールまたはユーザーにアタッチします。詳細については、「カスタマーマネージドポリシーの編集 (コンソール)」を参照してください。

ClientException

このエラーは、ECS クライアントが、無効または存在しない識別子またはリソースを指定した場合に記録されます。例えば、RunTask API または 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

このエラーは、タスク定義で要求される機能要件を満たさないプラットフォームでタスクが起動された場合に発生します。Amazon EFS ボリュームがプラットフォームバージョン 1.3.0 にアタッチされたサービスを作成しようとしているとします。

$ 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 - 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"
                    }
                }
...

この記事はお役に立ちましたか?


請求に関するサポートまたは技術サポートが必要ですか?