如何为Auto Scaling组启动模板创建的EC2自动附加IAM角色

两次UserData方案失败的核心原因是操作逻辑完全错误：IAM实例角色绑定是EC2控制平面操作，必须在实例启动前由Launch Template/ASG指定，实例刚启动时无任何权限，不可能通过内部CLI命令给自己附加角色，属于典型的权限死循环。
另外之前手动配置的CloudWatch Agent规则只存在于临时运行的实例上，如果制作AMI时没有把配置和自启设置打包进去，新实例启动后自然不会自动上报日志。

1. 提前准备好IAM实例配置文件 #

• 先在IAM控制台创建专用的服务角色，信任实体选择EC2服务，附加AWS托管权限策略CloudWatchAgentServerPolicy，这个策略已经包含了CloudWatch Agent上报日志、指标需要的所有权限，不需要手写自定义策略。
• 角色创建完成后，系统会自动生成同名的实例配置文件（Instance Profile），后续直接选用即可。
  注意：这一步是控制台提前预置的操作，绝对不要把角色创建、绑定的逻辑写到实例启动脚本里

2. 修改Launch Template绑定角色（解决角色不自动附加的核心步骤） #

• 创建Launch Template的新版本，下拉到「高级详细信息」板块，找到IAM实例配置文件选项，直接选中上一步创建好的实例配置文件。
• 删掉之前UserData里所有和附加IAM角色相关的AWS CLI命令，这些命令在实例内部永远跑不通，只会导致脚本执行失败。
• 保存新版本后，把Launch Template的默认版本切换到这个新版本。

3. 配置CloudWatch Agent自动运行 #

两种方案选其一即可，生产环境优先选第一种，稳定性最高：

方案A：将Agent和配置打包进AMI（生产环境推荐） #

• 回到用来制作AMI的Staging基准实例，确认已经完成以下操作：
  • 已经安装对应操作系统版本的CloudWatch Agent
  • 已经把所有日志采集规则（业务日志路径、Docker日志路径、对应CloudWatch日志组名称等）写入配置文件/opt/aws/amazon-cloudwatch-agent/etc/amazon-cloudwatch-agent.json
  • 执行以下命令验证配置生效、设置开机自启：

    # 加载配置并启动agent
    /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -a fetch-config -m ec2 -s -c file:/opt/aws/amazon-cloudwatch-agent/etc/amazon-cloudwatch-agent.json
    # 配置开机自启
    systemctl enable amazon-cloudwatch-agent
    

• 确认Staging实例上Agent运行正常、日志上报正常后，再基于这个实例制作新的AMI，后续用这个AMI启动的新实例只要绑定了正确的IAM角色，开机后Agent会自动运行上报日志，不需要任何额外配置。

方案B：通过UserData自动安装配置Agent（临时快速生效用） #

如果暂时不想重新制作基准AMI，可以直接在Launch Template的UserData中写入以下启动脚本，注意脚本必须以#!/bin/bash开头，否则EC2不会识别执行：

#!/bin/bash
set -e
# 安装CloudWatch Agent，以下为Amazon Linux 2的安装命令，其他操作系统替换为对应安装命令即可
wget -q https://s3.amazonaws.com/amazoncloudwatch-agent/amazon_linux/amd64/latest/amazon-cloudwatch-agent.rpm
rpm -U ./amazon-cloudwatch-agent.rpm -q
# 写入Agent配置，替换为实际的日志采集规则
cat > /opt/aws/amazon-cloudwatch-agent/etc/amazon-cloudwatch-agent.json << 'EOF'
{
  "logs": {
    "logs_collected": {
      "files": {
        "collect_list": [
          {
            "file_path": "/var/log/messages",
            "log_group_name": "prod-ec2-syslog",
            "log_stream_name": "{instance_id}"
          }
          // 在这里追加业务日志、Docker日志路径配置
        ]
      }
    }
  }
}
EOF
# 启动Agent并设置开机自启
/opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -a fetch-config -m ec2 -s -c file:/opt/aws/amazon-cloudwatch-agent/etc/amazon-cloudwatch-agent.json
systemctl enable amazon-cloudwatch-agent

4. 验证生效 #

修改完Launch Template后，在绑定的ASG中执行一次实例刷新，等新实例启动完成后做两项检查：

• 在EC2控制台打开新实例详情页，切到「安全」标签页，确认实例已经正确绑定了预置的IAM角色
• 登录实例执行systemctl status amazon-cloudwatch-agent确认服务处于running状态，再到CloudWatch控制台确认对应日志组已经收到新实例上报的日志即可。

• 方案1失败：UserData中执行角色绑定命令时，实例本身没有任何IAM权限，没有调用associate-iam-instance-profile API的权限，自然无法完成角色绑定，后续Agent没有权限上报日志。
• 方案2导致ASG流程失败：大概率是UserData脚本执行报错（比如权限不足、命令不存在、脚本没有加解释器头），实例启动后状态检查不通过，ASG判定实例异常就会反复终止重建新实例，最终导致实例刷新流程失败。

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