AWS Builder Center: Learn, Build and Connect with builders in the AWS community

AWS Builder Center is the official home for builders on AWS. Share and read what others are working on, follow people who inspire you, explore training and workshops, and find tools to support what you're building.

如何排查我在 Fargate 任务中使用 ECS Exec 时出现的错误？

4 分钟阅读

我想解决在我的 AWS Fargate 任务中使用 Amazon Elastic Container Service (Amazon ECS) Exec 时收到的错误。

解决方法

**注意：**如果您在运行 AWS 命令行界面 (AWS CLI) 命令时收到错误，请参阅 AWS CLI 错误故障排除。此外，请确保您使用的是最新版本的 AWS CLI。

当您在 Fargate 任务中使用 ECS Exec 时，可能会收到以下错误消息之一：

"An error occurred (InvalidParameterException) when calling the ExecuteCommand operation: The execute command failed because execute command was not enabled when the task was run or the execute command agent isn't running.Wait and try again or run a new task with execute command enabled and try again."
"An error occurred (TargetNotConnectedException) when calling the ExecuteCommand operation: The execute command failed due to an internal error.Try again later."

最佳做法是使用 AWS CloudShell 对 Fargate 任务上的 ECS Exec 进行故障排除。CloudShell 预装了 AWS Systems Manager Agent (SSM Agent) 和 AWS CLI。

InvalidParameterException 错误

如果为 Fargate 任务禁用 ExecuteCommand 选项，则您会收到 InvalidParameterException 错误。

要解决此问题，请完成以下步骤：

要检查 enableExecuteCommand 参数是设置为 true 还是 false，请运行 describe-tasks 命令：

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 蓝绿部署，请启动 CODE_DEPLOY 部署，而不是 force-new-deployment。您不能将 force-new-deployment 用于蓝绿部署，因为强制部署会启动滚动更新。

要检查 ExecuteCommandAgent 的状态，请运行 describe-tasks 命令：

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 角色已经拥有所需的权限，请确保服务控制策略 (SCP) 不会阻止任务与 SSM Agent 的连接。
如果您将 Amazon Virtual Private Cloud (Amazon VPC) 接口端点用于 Amazon ECS，请创建以下端点：
ec2messages.region.amazonaws.com
ssm.region.amazonaws.com
ssmmessages.region.amazonaws.com
**注意：**将 region 替换为您的区域。

要确认您的 AWS CLI 环境和 Amazon ECS 集群或任务已为 Amazon ECS Exec 做好准备，请运行 check-ecs-exec.sh 脚本。check-ecs-exec.sh 脚本的输出显示了在使用 ECS Exec 之前必须解决的问题。有关先决条件和用法的信息，请参阅 GitHub 网站上的 Amazon ECS Exec Checker（Amazon ECS Exec 检查程序）。
以下输出示例显示，该任务的 ECS Exec 已关闭，并且该任务角色没有所需的 Systems Manager 权限：

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，必须在任务定义中将 ReadonlyRootFilesystem 参数设置为 false。如果 ReadonlyRootFileSystem 为 true，则 SSM Agent 无法创建所需的目录。

验证您是否在容器级别配置了 IAM 用户凭证，例如访问密钥或秘密访问密钥。
**注意：**在检查身份验证时，SSM Agent 使用适用于 Java 的 AWS SDK。如果您将容器实例中的访问密钥或秘密访问密钥配置为环境变量，则会覆盖任务级别的权限。要使用 ECS Exec，容器级别的 IAM 凭证必须为 SSM Agent 提供权限。
在任务定义中，确认 pidMode 未设置为任务。
**注意：**每个进程 ID (PID) 命名空间只能有一个 ECS Exec 会话。如果您在任务中共享 PID 命名空间，则只能在一个容器中启动 ECS Exec 会话。

使用 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 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"

**注意：**不同的应用程序有不同的 Shell 和编辑器。请根据应用程序的要求修改上述命令参数。

如果使用的是 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"
    ],

主题: Containers
标签: AWS Fargate
语言: 中文 (简体)

如何排查我在 Fargate 任务中使用 ECS Exec 时出现的错误？

解决方法

InvalidParameterException 错误

TargetNotConnectedException 错误

相关视频

相关内容