AWS CloudFormation中EC2实例user-data的Docker配置未生效问题

核心排查方向 #

1. 检查user-data的cloud-config格式是否合规 #

cloud-init仅会解析以#cloud-config开头的配置文件，若你的user-data未添加该标识，runcmd字段会被直接忽略。同时runcmd必须采用列表格式，而非连续的shell命令字符串：

#cloud-config
packages:
  - docker
runcmd:
  - systemctl start docker
  - systemctl enable docker
  - usermod -aG docker ec2-user

若你误将runcmd写成单行shell脚本，cloud-init不会识别并执行其中的命令。

2. 深挖cloud-init日志的执行细节 #

查看两份关键日志，定位runcmd未执行的具体原因：

• 执行cat /var/log/cloud-init.log | grep runcmd，确认cloud-init是否加载了runcmd模块，是否有模块初始化失败的报错。
• 执行cat /var/log/cloud-init-output.log，查看runcmd阶段的输出，是否存在命令执行失败（如systemctl start docker因SELinux、内核不兼容报错）。

3. 验证Docker实际安装状态 #

即使日志显示“安装完成”，仍需确认Docker二进制文件是否存在：

• 执行ls /usr/bin/docker，若返回文件不存在，说明Docker安装过程存在静默失败（如实例无联网权限拉取yum包、源配置错误）。
• 若文件存在但执行docker version提示找不到命令，检查ec2-user的PATH环境变量：执行echo $PATH，确认/usr/bin是否在路径中，若不在，可手动添加：

  echo "export PATH=\$PATH:/usr/bin" >> /home/ec2-user/.bashrc
  source /home/ec2-user/.bashrc
  

4. 排查AWS Batch实例的初始化特殊性 #

AWS Batch的EC2实例会优先启动Batch代理服务，可能干扰cloud-init的执行顺序：

• 检查Compute Environment配置，确认未启用覆盖自定义user-data的初始化脚本。
• 尝试将user-data改为纯shell脚本格式（替代cloud-config），避免解析冲突：

  #!/bin/bash
  yum update -y
  yum install -y docker
  systemctl start docker
  systemctl enable docker
  usermod -aG docker ec2-user
  # 无需重新登录即可生效组权限
  echo "newgrp docker" >> /home/ec2-user/.bash_profile
  

快速修复建议 #

• 优先改用纯shell脚本格式的user-data，避免cloud-config的格式陷阱。
• 实例在私有子网时，确保配置NAT网关或Amazon Linux yum源的VPC端点，保证Docker包可正常拉取。
• 若遇SELinux阻止Docker启动，临时关闭并配置永久生效：

  setenforce 0
  sed -i 's/SELINUX=enforcing/SELINUX=permissive/' /etc/selinux/config
  

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