如何解决在我的 Fargate 任务上执行 Amazon ECS Exec 时收到的错误？

简短描述

在 Fargate 任务上使用 Amazon ECS Exec 时，您可能会收到以下错误消息：

• 调用 ExecuteCommand 操作时出现错误 (InvalidParameterException)： 执行命令失败，原因是在运行任务时没有启用执行命令，或者执行命令代理没有运行。请稍等然后重试，或者运行一个启用了执行命令的新任务然后重试。
• 调用 ExecuteCommand 操作时出现错误 (TargetNotConnectedException)： 由于内部错误，执行命令失败。请稍后重试。

要解决这些错误，请对 InvalidParameter 和 TargetNotConnectedException 进行故障排除。

解决方法

**注意：**使用 AWS CloudShell 是一种最佳实践。CloudShell 预装了 AWS Systems Manager 会话管理器插件和 AWS 命令行界面 (AWS CLI)。如果在运行 AWS CLI 命令时收到错误，请确认您运行的是最新版本的 AWS CLI。

**重要事项：**请将 AWS CLI 命令中的所有 example 字符串替换为您的值。例如，将 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 Virtual Private Cloud (Amazon VPC) 接口端点与 Amazon ECS 一起使用，请为 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 检查程序。

**注意：**运行 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 Agent 日志以确定为什么 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 Agent 日志，并将其传输到 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