スキップしてコンテンツを表示
AWS re:Postを使用することにより、以下に同意したことになります AWS re:Post 利用規約
AWS re:Postre:Post
re:Postに関して

Amazon ECS の API コールに関する一般的なエラーをトラブルシューティングする方法を教えてください。

所要時間4分
0

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 リクエストをイベント履歴のイベントとして記録します。

AWS CloudTrail イベント履歴を表示して API エラーを見つけるには、次の手順を実行します。

  1. CloudTrail コンソールを開きます。
  2. ナビゲーションペインで [イベント履歴] を選択します。
  3. 歯車のアイコンを選択します。
  4. [表示される列の選択] で [エラーコード] を選択します。次に、[確認] を選択します。
  5. [イベント履歴] ページの [ルックアップ属性] で [イベント名] を選択します。
  6. [イベント名を入力] に、失敗したアクションを入力します。
    注: イベント名がわからない場合は、[イベント履歴] ページに移動してください。[ルックアップ属性] で、[イベントソース] を選択します。[イベントソースを入力] で ecs.amazonaws.com を選択し、ECS サービスに関連するすべてのイベントをフィルタリングします。
  7. 結果のリストから、詳細を知りたいエラーコードのイベントを選択します。

注: Amazon Athena を使用して、エラーコードごとに 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 ID のアクセス許可ポリシーに適切なアクセス許可を追加するには、次の手順を実行します。

  1. IAM コンソールを開きます。
  2. ナビゲーションペインで、IAM ID に基づいて [ロール] 、[ユーザーグループ]、または [ユーザー] を選択します。
  3. 検索フィルターを使用して、ロールまたはユーザーオプションをフィルタリングします。次に、表示したい IAM ID を選択します。
  4. [アクセス許可] タブを選択します。
  5. IAM ID に関連付けられているアクセス許可を表示するには、アクセス許可ポリシーを展開します。
  6. アクセス許可ポリシーで、ecs:your-event-name をアクションリストに追加します。次に、[効果] に対して [許可] を選択します。または、ecs:your-event-name を許可する新しいポリシーを作成し、そのポリシーを IAM ロールまたはユーザーにアタッチします。詳細については、「Editing customer managed policies (console)」(カスタマーマネージドポリシーを編集する (コンソール)) を参照してください。

IAM ポリシーシミュレータを使用して、IAM ユーザー、ユーザーグループ、またはロールにアタッチされていないポリシーをテストできます。

ClientException

ECS クライアントが、無効または存在しない識別子やリソースを指定した場合、"ClientException" エラーが表示されます。次のエラー例は、RunTask コマンドが無効な TaskDefinition を参照していることを示しています。

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

コマンド、API コール、およびコードで正しいリソースを参照していることを確認します。

ClusterNotFoundException

Amazon ECS がオペレーション用に指定したクラスターを見つけられない場合、"ClusterNotFoundException" エラーが表示されます。次のエラー例は、StartTask オペレーションで指定したクラスターを Amazon ECS が見つけられないことを示しています。

"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 サポートに連絡し、次の情報を提供してください。

  • エラーに対応するタイムスタンプを提供します。
  • コマンドラインを使用する場合は、エラーを返すコマンドを提供します。
  • AWS SDK を使用するプログラミング言語や Infrastructure as Code ツールを使用している場合は、エラーを返すコードブロックを提供します。
  • AWS マネジメントコンソールを使用する場合は、AWS マネジメントコンソールページの URL とエラーを返すアクションを提供します。

ServiceNotActiveException

非アクティブな Amazon ECS サービスを更新すると、"ServiceNotActiveException" エラーが表示されます。更新する ECS サービスが ECS クラスターにあり、ACTIVE 状態であることを確認します。

クラスター内のすべてのサービスを一覧表示するには、list-clusters AWS CLI コマンドを実行します。

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 サービスの [タスクの数] の値が 0 より大きいことを確認します。また、update-service AWS CLI コマンドを実行して、[タスクの数] の値を 1 に更新することもできます。

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

注: example_cluster_name と example_service_name をそれぞれ実際の値に置き換えてください。必要数の値は、0 より大きい数値に設定できます。

次に、ECS コンソールで、タスク定義の状態が ACTIVE であることを確認します。次の describe-task-definition コマンドを実行することもできます。

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

注: example_taskdefinition を実際のタスク定義に置き換えてください。

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.0 ではなく、正しくないプラットフォームバージョン 1.3 が含まれています。

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 プラットフォームバージョン」および「Fargate Windows platform versions for Amazon ECS」(Amazon ECS 向け Fargate Windows プラットフォームバージョン) を参照してください。

ServiceNotFoundException

"ServiceNotFoundException" エラーは、指定した ECS サービスがコマンドまたはコードに存在しない場合に発生します。コマンドまたはコード内のサービス名が正しいことを確認し、サービスがクラスター内にあることを確認します。クラスター内のすべてのサービスを表示するには、list-clusters AWS CLI コマンドを実行します。

aws ecs list-services --cluster example_cluster

注: example_cluster を実際のクラスターに置き換えてください。

UnsupportedFeatureException

"UnsupportedFeatureException" エラーは、Fargate がコンテナをサポートしていない AWS リージョンで Fargate タスクを起動したときに発生します。詳細については、「AWS Fargate で使用する Amazon ECS でサポートされているリージョン」を参照してください。

アプリケーションの API に関する問題のトラブルシューティング

ECS タスク内でホストされているアプリケーションにアクセスすると、次の一般的な HTTP 5## ステータスコードレスポンスを受け取ることがあります。

  • "HTTP 500 - Internal server" エラーは、アプリケーションがエラーなどの予期しない状態に遭遇した場合に発生します。または、アプリケーションの設定を誤った際にこのエラーが表示されます。
  • ECS タスクに大きな負荷がかかると、"HTTP 503 - Service unavailable" エラーが発生します。または、タスク内のアプリケーションがメンテナンスのためにダウンしている場合、このエラーが表示されます。

Amazon CloudWatch ログで ECS タスクのアプリケーションログを確認してください。各タスク定義は、タスクのアプリケーションログを含むログストリームに対応します。タスク定義のロググループとログストリームに関する情報を表示するには、describe-task-definition コマンドを実行します。

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

注: example_task_definition を実際のタスク定義に置き換えてください。

関連情報

Amazon ECS での API エラーの原因

コメントはありません

関連するコンテンツ