TIL 实战：用 aws ecs execute-command 三步进入 ECS 容器-平芜编程栈

文档
教程
知识库

【免费下载链接】til

:memo: Today I Learned

项目地址：https://gitcode.com/gh_mirrors/ti/til

生产环境里的 Rails（或其他 Web）应用跑在 AWS ECS 容器中时，经常需要临时打开一个交互式 shell 来执行rails console、排查问题或运行一次性脚本。本文以 TIL 仓库中的 aws/ssh-into-an-ecs-container.md 笔记为主线，完整拆解「定位 region 与集群 → 找到任务 ID → 用execute-command建立交互会话」的全流程，并补充每个命令的输出解析、参数含义与常见前置条件。读完你可以直接在命令行里一步步进入任何 ECS 容器，不再依赖 AWS 控制台。

背景：为什么需要这条命令行链路

原笔记来自一次「连接生产环境 Rails console」的真实需求：Rails 应用通过 Flightcontrol 部署在 AWS ECS 容器中，为了访问rails console，必须先建立一个到容器的 SSH 式会话。整条链路可以拆成三个信息 + 一条命令：

region（区域，如us-east-2）；
cluster / container 标识（承载应用的集群或容器名）；
task ID（具体运行中的任务实例）；
最后用aws ecs execute-command发起交互式连接。

整个过程不需要打开浏览器控制台，全部通过 AWS CLI 完成，适合写进脚本或日常运维流程。

第一步：列出集群，一次性拿到 region 与集群名

执行aws ecs list-clusters列出当前账号下所有集群：

$ aws ecs list-clusters { "clusterArns": [ "arn:aws:ecs:us-east-2:123:cluster/rails-app-abc123" ] }

从返回的ARN（Amazon Resource Name）中可以直接读出两个关键信息：

region：ARN 中第二个字段，即us-east-2；
集群名：cluster/之后的部分，即rails-app-abc123。

也就是说，一条命令同时解决了「我该用哪个区域」和「我要进哪个集群」两个问题，无需再单独查询。原笔记将rails-app-abc123称为容器 ID，严格来说它是cluster 名称（最终execute-command中的--container参数取的是任务里具体容器的名称，在多容器任务中可能与集群名不同），实际使用时按 ARN 中cluster/后面的字段取值即可。

如果本机配置了多个 AWS 账号（profile），可以先aws configure list-profiles查看可用列表，再在命令中追加--profile参数指定账号，具体做法可参考仓库笔记 aws/use-specific-aws-profile-with-cli.md。若希望某个项目目录下默认使用特定账号，该笔记也给出了用AWS_PROFILE环境变量的方案。

第二步：列出任务，从任务 ARN 中提取 task ID

有了 region 和集群名，就可以列出该集群下正在运行的任务：

$ aws ecs list-tasks --region us-east-2 --cluster rails-app-abc123 { "taskArns": [ "arn:aws:ecs:us-east-2:123:task/rails-app-abc123/8526b3191d103bb1ff90c65a655ad004" ] }

任务 ARN 的结构是arn:aws:ecs:<region>:<account>:task/<cluster>/<task-id>，task ID 就是整条 URL 的最后一段：

8526b3191d103bb1ff90c65a655ad004

实操中需要注意两点：

如果集群里同时跑着多个任务（例如滚动发布期间新旧版本并存），taskArns会返回多行，此时可以用--desired-status RUNNING过滤，或结合--service <服务名>精确锁定某个服务的任务，再通过aws ecs describe-tasks确认目标任务的状态与容器列表；
任务 ID 也可以单独使用（形如8526b3191d103bb1ff90c65a655ad004），在execute-command中直接传这个短 ID 即可，不必传完整 ARN。

第三步：用 execute-command 建立交互式会话

把上面拿到的三个信息组装进aws ecs execute-command：

$ aws ecs execute-command \ --region us-east-2 \ --cluster rails-app-abc123 \ --container rails-app-abc123 \ --task 8526b3191d103bb1ff90c65a655ad004 \ --interactive \ --command "/bin/bash"

各参数的作用如下：

参数	取值来源	作用
`--region`	集群 ARN 中解析出的`us-east-2`	指定 API 请求的目标区域
`--cluster`	集群 ARN 中`cluster/`之后的部分	指定目标集群
`--container`	任务定义中的容器名	指定要进入的容器；任务只有一个容器时可省略，多容器任务必须显式指定
`--task`	任务 ARN 的尾段	指定目标任务实例
`--interactive`	固定	以交互模式启动会话，保持标准输入输出，效果类似本地`docker exec -it`的`-it`组合
`--command`	固定	在容器内执行的命令，这里用`/bin/bash`打开 bash shell

成功建立会话后，你会看到一个交互式 bash 提示符，可以执行ls、rails console等任意命令；输入exit即可退出并结束会话。

关于 shell 的选择：多数基于 Debian/Ubuntu 的镜像自带/bin/bash，极简镜像可能只提供/bin/sh，若 bash 不存在可改用--command "/bin/sh"。

前置条件：ECS Exec 不是「开箱即用」的

execute-command底层依赖 AWS 的ECS Exec（基于 SSM Session Manager）机制。原笔记默认任务已具备该能力，实际使用时若命令报错（如TargetNotConnectedException、权限不足等），应从以下三个方向排查，这些属于任务与集群侧的配置，而非 CLI 使用问题：

任务需启用 ECS Exec：EC2 启动类型的任务需在任务定义中设置enableExecuteCommand = true，Fargate 服务则需在创建服务或更新服务时开启；
容器内需包含 SSM Agent：镜像中要预装amazon-ssm-agent，或使用官方预置了该组件的 AWS 基础镜像；
任务 IAM 角色需具备对应权限：任务执行角色需要包含 SSM 相关的托管策略（如AmazonSSMManagedInstanceCore），调用方使用的 AWS 凭证也需要ecs:ExecuteCommand权限。

顺带一提，CLI 自身也要求版本足够新以支持execute-command子命令。关于 AWS CLI 的安装环境问题（例如help子命令报Could not find executable named 'groff'），可参考仓库笔记 aws/aws-cli-requires-groff-executable.md。

与本地 docker exec 的对照

如果之前在本地 Docker 环境工作过，会发现这套流程的「精神」与docker exec完全一致：先找到容器，再以交互模式进入。仓库笔记 devops/ssh-into-a-docker-container.md 给出了本地版本：

$ docker ps # 找到容器名 $ docker exec -it <name> /bin/bash

两者的差异在于定位方式：本地 Docker 用docker ps拿到的是宿主机上的容器名，而 ECS 场景必须跨过「集群 → 任务 → 容器」三层寻址，所以需要list-clusters和list-tasks两步先解析出 region、cluster 与 task ID，再交给execute-command。

进入容器之后：结合其他 TIL 笔记完成整条排查链路

建立 shell 会话只是手段，最终目的是在容器里做事。原笔记的应用场景是运行rails console连接生产数据库；进入容器后，建议按以下顺序组织排查链路：

在容器内执行目标命令（如bin/rails console），直接在交互会话中操作；
需要看应用日志时，不必反复进出容器，可直接用aws logs tail <log-group> --follow从命令行持续跟踪 CloudWatch 日志，具体方法与日志组定位技巧见仓库笔记 aws/find-and-follow-server-logs.md；
确认环境变量、进程状态后，用exit干净地退出会话。

小结

本文把「SSH 进入 ECS 容器」拆解为一条可复制的三步骤流程：list-clusters解析 region 与集群名 →list-tasks提取 task ID →execute-command建立交互式 bash 会话。核心信息全部来自 aws/ssh-into-an-ecs-container.md，并补充了 ARN 字段解析、多任务场景的筛选、ECS Exec 前置条件以及与本地docker exec的对照。对需要频繁在生产容器中执行rails console或排查问题的开发者来说，这套 CLI 链路值得收进自己的 TIL 笔记。