CloudFormation YAML模板UserData中PowerShell脚本执行异常排查

核心问题拆解 #

从日志和现象来看，问题根源有两个：

1. UserData格式不符合EC2 Windows实例的解析规范，导致YAML解析失败后回退到XML模式，执行过程不稳定
2. PowerShell脚本本身存在语法错误，且缺乏必要的执行保障（比如权限、错误处理）

具体修复步骤 #

1. 修正UserData的格式 #

Windows实例的EC2Launch/EC2Config服务对UserData的格式要求严格，必须用标准的多部分脚本包装，同时避免YAML解析冲突。调整后的模板片段如下：

Resources:
  Instance:
    Properties:
      UserData:
        Fn::Base64: !Sub |
          <script>
            echo "UserData script started at $(date)" >> C:\cfn\log\userdata_exec.log
          </script>
          <powershell>
            # 设置PowerShell执行策略，避免权限拦截
            Set-ExecutionPolicy RemoteSigned -Force -Scope LocalMachine

            # 修正添加本地组成员的语法
            Add-LocalGroupMember -Group "你的组名" -Member "要添加的成员账户"

            # 安装Windows功能，添加错误处理和重启检测
            try {
              $installResult = Install-WindowsFeature -Name "你的功能名称" -IncludeManagementTools -ErrorAction Stop
              if ($installResult.RestartNeeded -eq 'Yes') {
                Write-Host "功能安装需要重启，将在5分钟后执行"
                Restart-Computer -Delay 300 -Force
              }
              "Windows功能安装成功" >> C:\cfn\log\userdata_exec.log
            } catch {
              "安装失败：$_" >> C:\cfn\log\userdata_exec.log
              exit 1
            }
          </powershell>
          <persist>true</persist>

• 用!Sub配合|确保脚本的换行和格式被完整保留
• 添加<persist>true</persist>防止实例重启后重复执行脚本（根据需求可调整为false）
• 增加自定义日志，方便追踪执行细节

2. 修复PowerShell脚本语法错误 #

• 原写法add-localgroupmember (my group member)不符合PowerShell语法，必须明确指定-Group和-Member参数，PowerShell不支持这种括号简写方式
• install-windowsfeature需要填写具体的功能名称（比如Web-Server、AD-Domain-Services），不能用占位符；添加try/catch捕获错误，避免脚本静默失败

3. 排查执行日志定位问题 #

如果问题仍存在，检查这两个日志文件：

• EC2Launch服务日志：C:\ProgramData\Amazon\EC2-Windows\Launch\Log\Ec2Launch.log（查看UserData的解析和执行触发情况）
• 自定义脚本日志：C:\cfn\log\userdata_exec.log（查看脚本每一步的执行结果）

4. 解决YAML解析失败问题 #

日志中的YAML解析失败，是因为EC2服务会尝试把UserData当作YAML格式解析，但你的脚本内容不符合YAML规范。通过用<script>、<powershell>等标准标签包装脚本，可避免解析冲突，让服务正确识别脚本类型。

验证步骤 #

1. 部署修改后的CloudFormation模板
2. 登录实例后执行以下命令验证：
   • 检查组成员：Get-LocalGroupMember -Group "你的组名"
   • 检查Windows功能：Get-WindowsFeature -Name "你的功能名称"
   • 查看日志确认执行过程：Get-Content C:\cfn\log\userdata_exec.log

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