Fargate タスクで Amazon ECS Exec を実行したときに表示されるエラーをトラブルシューティングする方法を教えてください。

簡単な説明

Fargate タスクで Amazon ECS Exec を使用すると、次のエラーステートメントが表示される場合があります。

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

これらのエラーを解決するには、[InvalidParameter] と [TargetNotConnectedException] をトラブルシューティングしてください。

解決方法

**注記:**AWS CloudShell を使用するのがベストプラクティスです。CloudShell には、AWS システムマネージャーセッションマネージャプラグインと AWS コマンドラインインターフェイス (AWS CLI) がプリインストールされています。AWS CLI コマンドの実行中にエラーが発生した場合は、最新バージョンの AWS CLI を実行していることを確認してください。

**重要:**AWS CLI コマンドのすべての [サンプル] 文字列を自分の値に置き換えます。たとえば、[example-cluster-name] をクラスターの名前に置き換えてください。

InvalidParameterException エラーのトラブルシューティング

Fargate タスクの [ExecuteCommand] オプションをオンにしないと、[InvalidParameterException] というエラーが表示されます。この問題を解決するには、次のステップを実行してください。

1.    [EnableExecuteCommand] パラメータが [true] に設定されているか [false] に設定されているかを確認してください。

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

2.    [EnableExecuteCommand] パラメータが [false] の場合は、パラメータを [true] として更新してください。

aws ecs update-service --cluster <example-cluster-name> --service <example-service> --region <example-region> --enable-execute-command --force-new-deployment

注記:[force-new-deploy] オプションでは、サービスのデプロイ設定に基づいて新しいタスクを開始し、古いタスクを停止する新しいデプロイを作成します。詳細については、アップデートのローリング を参照してください。

TargetNotConnectedException エラーのトラブルシューティング

[TargetNotConnectionException] エラーを解決するには、次のステップを実行してください。

• 必要な権限とネットワーク設定を確認してください。
• Amazon ECS Exec を使用して、正しいシェルでコンテナに入ります。
• Amazon ECS Exec が問題を特定するためのログを生成します。

必要な権限とネットワーク設定を確認してください

1.    Amazon ECS Exec には、コンテナにアクセス権限を付与するためのタスク IAM ロールが必要です。次のポリシーを使用して、タスク IAM ロールに必要な SSM アクセス権限を追加します。

{
   "Version": "2012-10-17",
   "Statement": [
       {
       "Effect": "Allow",
       "Action": [
            "ssmmessages:CreateControlChannel",
            "ssmmessages:CreateDataChannel",
            "ssmmessages:OpenControlChannel",
            "ssmmessages:OpenDataChannel"
       ],
      "Resource": "*"
      }
   ]
}

詳細については、[タスク IAM ロール] を参照してください。

2.    Amazon ECS でインターフェイス Amazon Virtual Private Cloud (Amazon VPC) エンドポイントを使用している場合は、Systems Manager Session Manager 用に次のエンドポイントを作成します。

• ec2messages.region.amazonaws.com
• ssm.region.amazonaws.com
• ssmmessages.region.amazonaws.com

詳細については、 ステップ 6 を参照してください。 (オプション) AWS PrivateLink を使用して、Session Manager の VPC エンドポイントを設定します。

3.    check-ecs-exec.sh スクリプトを実行して、お使いの AWS CLI 環境と Amazon ECS クラスターまたはタスクが Amazon ECS Exec に対応できる状態になっていることを確認します。前提条件を満たしていることを確認してください。詳細については、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 がタスクに対して有効になっていないこと、およびタスクロールに必要な SSM 権限がないことを示しています。

4.    アクセスキーやシークレットアクセスキーを指定するなど、コンテナレベルで IAM ユーザー認証情報を設定したかどうかを確認してください。コンテナレベルで IAM ユーザー認証情報を設定した場合、これによりタスクレベルの権限がオーバーライドされ、エラーが発生します。

Amazon ECS Exec を使用して正しいシェルでコンテナに入る

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

次のコマンドを実行して、ECS Exec を使用してコンテナに入ります。[example\ _shell] を自分のシェルに置き換えてください。

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

Amazon ECS Exec が問題を特定するためのログを生成する

SSM エージェントログを生成して、ECS Exec が Fargate タスク内で機能しない理由を特定します。コンテナ定義の環境セクションで次のコマンドを実行します。

コンソール:

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"
      ],

**注記:**アプリケーションが異なれば、シェルやエディタも異なります。アプリケーションごとにコマンドパラメータを確認および変更してください。

関連情報

ECS Exec を使用する