Fargate タスクで ECS Exec を使用するときに発生するエラーをトラブルシューティングする方法を教えてください。

所要時間3分

AWS Fargate タスクで Amazon Elastic Container Service (Amazon ECS) Exec を実行するときに発生するエラーをトラブルシューティングしたいです。

簡単な説明

Fargate タスクで ECS Exec を使用すると、次のいずれかのエラーメッセージが表示されることがあります。

ExecuteCommand 操作の呼び出し時にエラーが発生しました (InvalidParameterException): タスクの実行時に実行コマンドが有効になっていなかったか、コマンド実行エージェントが実行されていないため、実行コマンドに失敗しました。しばらく待ってからやり直すか、実行コマンドが有効な新しいタスクを実行してからやり直してください。
ExecuteCommand 操作の呼び出し時にエラーが発生しました (TargetNotConnectedException)。内部エラーが原因で、実行コマンドが失敗しました。後でもう一度試してください。

解決策

注: AWS コマンドラインインターフェイス (AWS CLI) コマンドの実行中にエラーが発生した場合は、「AWS CLI で発生したエラーのトラブルシューティング」を参照してください。また、AWS CLI の最新バージョンを使用していることを確認してください。

Fargate タスクで ECS Exec を使用すると発生する一般的なエラーを解決するには、AWS CloudShell を使用することがベストプラクティスです。CloudShell には、AWS Systems Manager Session Manager Agent (SSM Agent) と AWS CLI がプリインストールされています。

InvalidParameterException エラー

Fargate タスクで ExecuteCommand オプションが無効になっている場合、InvalidParameterException エラーが発生します。

この問題を解決するには、次の手順を実行します。

describe-tasks コマンドを実行し、enableExecuteCommand パラメータが true に設定されているか false に設定されているかを確認します。

aws ecs describe-tasks --cluster example-cluster-name --tasks example-task-id| grep enableExecuteCommand

注: example-cluster-name を実際のクラスターに、example-task-id を実際のタスク ID に置き換えます。

enableExecuteCommand パラメータが false の場合は、次の update-service コマンドを実行してパラメータを true に更新します。
```
aws ecs update-service --cluster example-cluster-name --service example-service --region example-region --enable-execute-command --force-new-deployment
```
注: お使いのものでそれぞれ、example-cluster-name をクラスターに、example-service をサービスに、example-region を AWS リージョンに置き換えます。force-new-deployment オプションを指定した場合、サービスのデプロイ設定に基づいて新しいタスクを開始し、古いタスクを停止する新しいデプロイが作成されます。サービスが AWS CodeDeploy によるブルー/グリーンデプロイを使用している場合は、force-new-deployment ではなく、CODE_DEPLOY のデプロイを開始します。この方法ではローリングアップデートが開始されるため、ブルー/グリーンデプロイには force-new-deployment を使用できません。

次の describe-tasks コマンドを実行し、ExecuteCommandAgent のステータスを確認します。

aws ecs describe-tasks --cluster example-cluster-name --tasks example-task-id | grep -A 6 managedAgents

注: example-cluster-name を実際のクラスターに、example-task-id を実際のタスク ID に置き換えます。

コマンドの出力を参考に、ExecuteCommand エージェントの状態を確認します。ExecuteCommandAgent の lastStatus が RUNNING 以外の場合は、ExecuteCommandAgent のエージェントログを確認して根本原因を特定します。「ECS Exec のログを生成し、問題を特定する」のトラブルシューティング手順に進み、ExecuteCommandAgent のログを生成します。
コンテナでプロキシを設定したことが原因で ExecuteCommandAgent が認証情報を取得できない場合は、次の NO_PROXY オプションをコンテナインスタンスの設定ファイルに追加します。
```
env no_proxy=169.254.169.254,169.254.170.2
```

TargetNotConnectedException エラー

TargetNotConnectionException エラーを解決するには、次の手順を実行します。

必要なアクセス許可を追加し、ネットワーク設定が正しいことを確認する

次の手順を実行します。

Amazon ECS タスクの AWS Identity and Access Management (IAM) ロールに必要なアクセス許可を追加します。タスクの IAM ロールに必要なアクセス許可が既にある場合は、タスクによる SSM エージェントへの接続をブロックするサービスコントロールポリシー (SCP) がないかどうかを確認します。
Amazon ECS で Amazon Virtual Private Cloud (Amazon VPC) インターフェイスエンドポイントを使用する場合は、次のエンドポイントを作成します。
ec2messages.region.amazonaws.com
ssm.region.amazonaws.com
ssmmessages.region.amazonaws.com
注: region は、お使いのリージョンに置き換えます。

AWS CLI 環境および、ECS クラスターまたはタスクが Amazon ECS Exec に対応できる状態になっていることを確認するには、check-ecs-exec.sh スクリプトを実行します。前提条件と使用方法については、GitHub のウェブサイトで「Amazon ECS Exec Checker」を参照してください。
check-ecs-exec.sh スクリプトの出力は、ECS Exec を使用する前に解決する必要がある事項を示しています。出力例:

Prerequisites for check-ecs-exec.sh v0.7-------------------------------------------------------------  jq      | OK (/usr/bin/jq)
  AWS CLI | OK (/usr/local/bin/aws)

-------------------------------------------------------------
Prerequisites for the AWS CLI to use ECS Exec
-------------------------------------------------------------
  AWS CLI Version        | OK (aws-cli/2.11.0 Python/3.11.2 Linux/4.14.255-291-231.527.amzn2.x86_64 exec-env/CloudShell exe/x86_64.amzn.2 prompt/off)
  Session Manager Plugin | OK (1.2.398.0)

-------------------------------------------------------------
Checks on ECS task and other resources
-------------------------------------------------------------
Region : us-east-1
Cluster: Fargate-Testing
Task   : ca27e41ea3f54fd1804ca00feffa178d
-------------------------------------------------------------
  Cluster Configuration  | Audit Logging Not Configured
  Can I ExecuteCommand?  | arn:aws:iam::12345678:role/Admin
     ecs:ExecuteCommand: allowed
     ssm:StartSession denied?: allowed
  Task Status            | RUNNING
  Launch Type            | Fargate
  Platform Version       | 1.4.0
  Exec Enabled for Task  | NO
  Container-Level Checks |
    ----------
      Managed Agent Status - SKIPPED
    ----------
    ----------
      Init Process Enabled (Exec-check:2)
    ----------
         1. Disabled - "nginx"
    ----------
      Read-Only Root Filesystem (Exec-check:2)
    ----------
         1. Disabled - "nginx"
  Task Role Permissions  | arn:aws:iam::12345678:role/L3-session
     ssmmessages:CreateControlChannel: implicitDeny
     ssmmessages:CreateDataChannel: implicitDeny
     ssmmessages:OpenControlChannel: implicitDeny
     ssmmessages:OpenDataChannel: implicitDeny
  VPC Endpoints          | SKIPPED (vpc-abcd - No additional VPC endpoints required)
  Environment Variables  | (Exec-check:2)
       1. container "nginx"
       - AWS_ACCESS_KEY: not defined
       - AWS_ACCESS_KEY_ID: not defined
       - AWS_SECRET_ACCESS_KEY: not defined

上記の出力は、タスクで ECS Exec が無効であり、タスクロールには必要な Systems Manager アクセス許可がないことを示しています。注: ECS Exec を実行するには、タスク定義の ReadOnlyRootFileSystem パラメータを false に設定する必要があります。ReadOnlyRootFileSystem が true の場合、SSM エージェントは必要なディレクトリを作成できません。

コンテナレベルで、アクセスキーやシークレットアクセスキーなどの IAM ユーザー認証情報を設定したかどうかを確認します。SSM エージェントは、認証を確認する際に AWS SDK for Java を使用します。コンテナインスタンスのアクセスキーまたはシークレットアクセスキーを環境変数として設定すると、タスクレベルのアクセス許可は上書きされます。ECS Exec を使用するには、コンテナレベルの IAM 認証情報により SSM エージェントのアクセス許可を付与する必要があります。

ECS Exec を使用して正しいシェルでコンテナにアクセスする

ベースイメージに応じて、含まれるシェルが異なる場合があります。間違ったシェルを使用すると、エラーが発生します。アプリケーションイメージに応じて、正しいシェルを使用していることを確認してください。

ECS Exec を使用してコンテナにアクセスするには、execute-command コマンドを実行します。

aws ecs execute-command --region example-region --cluster example-cluster --container example-container --task example-task --command "example_shell" --interactive

注: お使いのものでそれぞれ、example-region をリージョンに、example-cluster をクラスター名に、example-container をコンテナインスタンス名に、example-task をタスク名に置き換えます。

ECS Exec のログを生成し、問題を特定する

ECS Exec が機能しない理由を特定するには、コンテナ定義の環境セクションで次のコマンドを実行して SSM Agent ログを生成します。

コンソール:

bin/bash,-c,sleep 2m && cat /var/log/amazon/ssm/amazon-ssm-agent.log

JSON:

"/bin/bash","-c","sleep 2m && cat /var/log/amazon/ssm/amazon-ssm-agent.log"

注: アプリケーションによって、シェルとエディタは異なります。アプリケーションの要件に合わせて、上記のコマンドパラメータを変更します。

awslogs ログドライバーを使用している場合、上記のコマンドは SSM エージェントログを生成し、Amazon CloudWatch ロググループに転送します。他のログドライバーやログ記録エンドポイントを使用している場合、SSM Agent ログはそれに対応する場所に転送されます。

JSON の例:

"entryPoint": [],      "portMappings": [],      "command": [
        "bin/bash",
        "-c",
        "sleep 2m && cat /var/log/amazon/ssm/amazon-ssm-agent.log"
      ],

Fargate タスクで ECS Exec を使用するときに発生するエラーをトラブルシューティングする方法を教えてください。

簡単な説明

解決策

InvalidParameterException エラー

TargetNotConnectedException エラー

関連情報

関連するコンテンツ