如何疑難排解在 Fargate 任務中使用 ECS Exec 時收到的錯誤？

簡短說明

當您在 Fargate 任務上使用 ECS Exec 時，可能會收到下列錯誤訊息之一：

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

解決方法

注意： 如果您在執行 AWS Command Line Interface (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 錯誤。

若要解決此問題，請完成下列步驟：

1. 執行 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。
2. 如果 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 進行藍/綠部署，因為此選項會啟動捲動更新。
3. 執行以下 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。
4. 檢查命令的輸出以檢查 ExecuteCommand 代理程式的狀態。如果 ExecuteCommandAgent 的 lastStatus 不是 RUNNING，請檢查 ExecuteCommandAgent 代理程式日誌以確定根本原因。繼續產生 ECS Exec 日誌以識別問題疑難排解步驟，以產生 ExecuteCommandAgent 日誌。
   如果由於您在容器中設定了代理程式而導致 ExecuteCommandAgent 無法檢索憑證，則將下列 NO_PROXY 選項新增至容器執行個體設定檔：

   env no_proxy=169.254.169.254,169.254.170.2

TargetNotConnectedException 錯誤

若要解決 TargetNotConnectionException 錯誤，請執行以下動作。

新增所需的權限，並確認網路組態正確

請完成下列步驟：

1. 將所需的權限新增至您的 Amazon ECS 任務 AWS Identity and Access Management (IAM) 角色。如果任務 IAM 角色已具有所需的權限，請檢查是否有任何服務控制政策 (SCP) 阻止該任務與 SSM 代理程式的連線。
2. 如果您將 Amazon Virtual Private Cloud (Amazon VPC) 介面端點與 Amazon ECS 結合使用，請建立下列端點：
   ec2messages.region.amazonaws.com
   ssm.region.amazonaws.com
   ssmmessages.region.amazonaws.com
   注意： 將 region (區域) 替換為您的區域。
3. 若要確認您的 AWS CLI 環境和 Amazon ECS 叢集或任務已準備好執行 ECS Exec，請執行 check-ecs-exec.sh 指令碼。有關先決條件和使用情況的信息，請參閱 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 已關閉，且任務角色沒有所需的 Systems Manager 權限。注意： 您必須在任務定義中將 ReadonlyRootFilesystem 參數設為 false 才能執行 ECS Exec。如果 ReadonlyRootFileSystem 為 true，則 SSM 代理程式無法建立所需的目錄。

檢查您是否在容器層級設定了 IAM 使用者憑證，例如存取金鑰或私密存取金鑰。SSM 代理程式在檢查驗證時使用適用於 Java 的 AWS SDK。如果您將容器執行個體中的存取金鑰或私密存取金鑰設定為環境變數，則會覆寫任務層級權限。若要使用 ECS Exec，容器層級的 IAM 憑證必須為 SSM 代理程式提供權限。

使用 ECS Exec 透過正確的 Shell 進入容器

不同的基礎映像中可以有不同的 Shell。如果您使用不正確的 Shell，則會收到錯誤。確保您根據應用程式映像使用了正確的 Shell。

若要使用 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 代理程式日誌：

主控台：

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"

注意： 不同的應用程式有不同的 Shell 和編輯器。根據應用程式的要求修改上述命令參數。

如果您使用 awslogs 日誌驅動程式，則上述命令會產生 SSM 代理程式日誌，並將其傳輸到 Amazon CloudWatch 日誌群組。如果您使用其他日誌驅動程式或日誌記錄端點，則 SSM 代理程式日誌將會傳輸到這些位置。

JSON 範例：

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

相關資訊

使用 ECS Exec