Docker Compose部署ECS失败：BackgroundjobsService的CloudFormation创建失败

核心问题背景 #

• CloudFormation部署时，BackgroundjobsService资源创建失败
• 该服务与其他服务的差异：无暴露端口、基于Ubuntu 20.04镜像（其他服务使用php-apache镜像）
• Dockerfile仅包含FROM ubuntu:20.04
• docker-compose.yml配置项：镜像地址、重启策略、环境变量文件、构建上下文
• 前置操作已完成：镜像构建并推送至ECR、任务定义创建成功、环境变量已配置
• 关键困境：无法定位错误日志

排查步骤 #

1. 提取CloudFormation本身的错误详情 #

• 登录AWS控制台进入CloudFormation页面，找到失败的堆栈
• 切换到事件标签页，定位BackgroundjobsService对应的失败事件，查看状态原因字段，这里通常会给出资源创建失败的直接提示（如权限不足、依赖缺失、配置格式错误）
• 若事件信息不足，查看堆栈的输出和变更集，确认是否存在参数传递错误

2. 检查ECS服务/任务的日志（即使服务未启动） #

• 手动启动测试任务验证：
  1. 进入ECS控制台，找到对应集群
  2. 在任务标签页点击运行新任务，选择已创建的BackgroundjobsService任务定义
  3. 启动后查看任务的停止原因和关联的CloudWatch日志（若已配置日志组）
• 若未配置日志，修改任务定义添加CloudWatch日志配置（指向已存在的日志组），重新触发CloudFormation部署后再查看日志

3. 验证Ubuntu镜像的可用性与启动命令 #

• 本地测试镜像启动：执行docker run -it --rm ubuntu:20.04，确认镜像能正常启动
• 检查docker-compose.yml是否遗漏启动命令：Ubuntu镜像默认无长期运行进程，若未指定启动命令，容器会启动后立即退出，导致ECS服务无法稳定运行，进而触发CloudFormation创建失败
  • 需在docker-compose.yml中添加command字段，指定长期运行命令（如测试用的command: tail -f /dev/null，或实际后台任务启动命令）

4. 检查CloudFormation中服务的端口配置 #

• 由于该服务无暴露端口，需确认CloudFormation模板中对应服务的端口映射配置是否正确：
  • 若模板误沿用了其他php-apache服务的端口配置，会导致资源创建失败
  • 确保服务的NetworkConfiguration中未配置不必要的端口绑定，或PortMappings字段为空（符合ECS服务配置要求）

5. 验证ECR镜像的权限与拉取能力 #

• 确认CloudFormation使用的IAM角色（或ECS任务执行角色）具备拉取该ECR镜像的权限：
  • 检查角色是否附加AmazonEC2ContainerRegistryReadOnly策略，或自定义策略包含ecr:GetDownloadUrlForLayer、ecr:BatchGetImage等权限
• 手动测试镜像拉取：在同VPC、同权限的EC2实例上执行登录命令后拉取镜像，确认能正常拉取

  aws ecr get-login-password --region <你的区域> | docker login --username AWS --password-stdin <你的账号ID>.dkr.ecr.<你的区域>.amazonaws.com
  docker pull <镜像地址>
  

6. 检查docker-compose转CloudFormation的配置问题（若使用转换工具） #

• 如果是通过ecs-cli compose或AWS Copilot将docker-compose.yml转换为CloudFormation模板，需确认转换过程中关键配置是否丢失：
  • 环境变量文件的引用是否正确转换为CloudFormation的EnvironmentFiles配置
  • 重启策略是否正确映射为ECS服务的DeploymentConfiguration中的重启设置

内容的提问来源于stack exchange，提问作者Chris Muench