如何疑難排解在我的 Fargate 任務上執行 Amazon ECS Exec 時收到的錯誤？

簡短描述

在 Fargate 任務上使用 Amazon ECS Exec 時，您可能會收到下列錯誤陳述式：

• 調用 ExecuteCommand 操作時發生錯誤 (InvalidParameterException)： 執行命令失敗，因為在任務執行或執行命令代理程式未執行時，未啟用執行命令。請稍候再試一次，或在啟用執行命令的情況下執行新任務，然後再試一次。
• 調用 ExecuteCommand 時發生錯誤 (TargetNotConnectedException)： 由於內部錯誤，執行命令失敗。請稍後再試一次。

若要解決這些錯誤，請疑難排解 InvalidParameter 和 TargetNotConnectedException。

解決方法

**注意：**使用 AWS CloudShell 是最佳做法。CloudShell 預先安裝了 AWS Systems Manager Session Manager 外掛程式和 AWS Command Line Interface (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-deployment 選項會建立新部署，以啟動新任務，並根據服務的部署組態停止舊任務。如需詳細資訊，請參閱輪流更新。

疑難排解 TargetNotConnectedException 錯誤

若要解決 TargetNotConnectionException 錯誤，請完成下列步驟：

• 檢查所需的權限和網路設定。
• 使用 Amazon ECS Exec 使用正確 Shell 進入容器。
• 為 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) 端點，請為系統管理員工作階段管理員建立下列端點：

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

如需詳細資訊，請參閱步驟 6： (選用) 使用 AWS PrivateLink 為工作階段管理員設定 VPC 端點。

3.    執行 check-ecs-exec.sh 指令碼，確認您的 AWS CLI 環境和 Amazon ECS 叢集或任務已準備就緒，可供 Amazon ECS Exec 使用。確定您符合先決條件。如需詳細資訊，請參閱 GitHub 網站上的 Amazon ECS Exec 檢查程式。

**注意：**執行 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 透過正確的 Shell 進入容器

不同的基本影像中可能會有不同的 Shell，而使用不正確的 Shell 會導致錯誤。確保您根據應用程式映像使用正確的 Shell。

執行下列命令以使用 ECS Exec 進入容器。用您的 example_shell 取代 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"
      ],

**注意：**不同的應用程式有不同的 shell 和編輯器。確保根據您的應用程式查看和修改命令參數。

相關資訊

使用 ECS Exec