排查 EC2Launch v2 代理的问题 - Amazon Elastic Compute Cloud
常见场景Windows 事件日志EC2Launch v2 控制台日志输出

排查 EC2Launch v2 代理的问题

本节介绍 EC2Launch v2 的常见故障排除场景以及有关查看 Windows 事件日志及控制台日志输出和消息的信息。

常见故障排除场景

本节介绍常见的故障排除场景和解决步骤。

服务无法设置壁纸

解决方案

  1. 确保存在 %AppData%\Roaming\Microsoft\Windows\Start Menu\Programs\Startup\setwallpaper.lnk 。

  2. 检查 %ProgramData%\Amazon\EC2Launch\log\agent.log 是否发生任何错误。

服务无法运行用户数据

可能的原因：服务可能在运行用户数据之前失败。

解决方案

  1. 检查 %ProgramData%\Amazon\EC2Launch\state\previous-state.json。

  2. 查看 boot、network、preReady 和 postReadyLocalData 是否全部标记为成功。

  3. 如果其中一个阶段失败，请检查 %ProgramData%\Amazon\EC2Launch\log\agent.log 中的具体错误。

服务只运行一次任务

解决方案

  1. 检查任务的频率。

  2. 如果服务已在 Sysprep 之后运行，并且任务频率设置为 once，则该任务不会再次运行。

  3. 如果您希望任务在每次运行 EC2Launch v2 时运行，请将任务的频率设置为 always。

服务无法运行任务

解决方案

  1. 检查 %ProgramData%\Amazon\EC2Launch\log\agent.log 中的最新条目。

  2. 如果没有发生错误，请尝试从 "%ProgramFiles%\Amazon\EC2Launch\EC2Launch.exe" run 手动运行服务以查看任务是否成功。

服务多次运行用户数据

解决方案

用户数据在 EC2Launch v1 和 EC2Launch v2 之间的处理方式不同。将 persist 设置为 true 时，EC2Launch v1 在实例上将用户数据作为计划任务运行。如果 persist 设置为 false，则即使重新启动后退出或运行时中断，也不会计划该任务。

EC2Launch v2 将用户数据作为代理任务运行并跟踪其运行状态。如果用户数据发出计算机重启或用户数据在运行时中断，则运行状态将保持不变，pending 并且用户数据将在下次实例启动时再次运行。如果要阻止用户数据脚本多次运行，请使脚本具有幂等性。

以下示例幂极脚本设置计算机名称并加入域。

<powershell>
  $name = $env:computername
  if ($name -ne $desiredName) {
	Rename-Computer -NewName $desiredName
  }
  $domain = Get-ADDomain
  if ($domain -ne $desiredDomain) 
  {
	Add-Computer -DomainName $desiredDomain
  }
  $telnet = Get-WindowsFeature -Name Telnet-Client
  if (-not $telnet.Installed)
  {
	Install-WindowsFeature -Name "Telnet-Client"
  }
</powershell>
<persist>false</persist>

EC2Launch v1 中的计划任务在迁移到 EC2Launch v2 后无法运行

解决方案

迁移工具不会检测任何链接到 EC2Launch v1 脚本的计划任务；因此，它不会在 EC2Launch v2 中自动设置这些任务。要配置这些任务，请编辑 agent-config.yml 文件或使用 EC2Launch v2 设置对话框。例如，如果实例的计划任务正在运行 InitializeDisks.ps1，则在运行迁移工具之后，您必须在 EC2Launch v2 设置对话框中指定要初始化的卷。请参阅 使用 EC2Launch v2 设置对话框更改设置 程序的步骤 6。

服务初始化不为空的 EBS 卷

解决方案

在初始化卷之前，EC2Launch v2 会尝试检测该卷是否为空。如果卷不为空，则会跳过初始化。不初始化任何检测到不为空的卷。如果卷的前 4 KiB 为空，或者卷没有 Windows 可识别的驱动器布局，则该卷被视为空。在 Linux 系统上初始化和格式化的卷没有 Windows 可识别的驱动程序布局，例如 MBR 或 GPT。因此，它将被视为空并已初始化。如果要保留此数据，请不要依赖 EC2Launch v2 空驱动器检测。相反，请指定要在 EC2Launch v2 设置对话框（请参阅步骤 6）或 agent-config.yml 中初始化的卷。

setWallpaper 任务未启用，但壁纸会在重新启动时重置

setWallpaper 任务在每个现有用户的启动文件夹中创建 setwallpaper.lnk 快捷方式文件，但 Default User 除外。当用户在实例启动后首次登录时，此快捷方式文件就会运行。使用显示实例属性的自定义壁纸设置实例。删除 setWallpaper 任务不会删除此快捷方式文件。您必须手动删除此文件或使用脚本将其删除。

快捷方式路径是：

$env:SystemDrive/Users/<user>/AppData/Roaming/Microsoft/Windows/Start Menu/Programs/Startup/setwallpaper.lnk

解决方案

手动删除此文件，或使用脚本将其删除。

删除快捷方式文件的 PowerShell 脚本示例

foreach ($userDir in (Get-ChildItem "C:\Users" -Force -Directory).FullName)
{
	$startupPath = Join-Path $userDir -ChildPath "AppData\Roaming\Microsoft\Windows\Start Menu\Programs\Startup"
	if (Test-Path $startupPath)
	{
		$wallpaperSetupPath = Join-Path $startupPath -ChildPath "setwallpaper.lnk"
		if (Test-Path $wallpaperSetupPath)
		{
			Remove-Item $wallpaperSetupPath -Force -Confirm:$false
		}
	}
}

服务停留在运行状态

描述

EC2Launch v2 被阻止，日志消息（agent.log）与以下类似：

2022-02-24 08:08:58 Info: *****************************************************************************************
2022-02-24 08:08:58 Info: EC2Launch Service starting
2022-02-24 08:08:58 Info: Windows event custom log exists: Amazon EC2Launch
2022-02-24 08:08:58 Info: ACPI SPCR table not supported. Bailing Out
2022-02-24 08:08:58 Info: Serial port is in use. Waiting for Serial Port...
2022-02-24 08:09:00 Info: ACPI SPCR table not supported. Use default console port.
2022-02-24 08:09:02 Info: ACPI SPCR table not supported. Use default console port.
2022-02-24 08:09:04 Info: ACPI SPCR table not supported. Use default console port.
2022-02-24 08:09:06 Info: ACPI SPCR table not supported. Use default console port.
可能的原因

SAC 已启用并使用串行端口。有关更多信息，请参阅使用 SAC 排查 Windows 实例的问题。

解决方案

请尝试以下步骤来解决该问题：

  • 禁用使用串行端口的服务。

  • 如果您希望服务继续使用串行端口，请编写自定义脚本来执行启动代理任务，并将其作为计划的任务调用。

无效的 agent-config.yml 会阻止打开 EC2Launch v2 设置对话框

描述

EC2Launch v2 设置在打开对话框之前尝试解析 agent-config.yml 文件。如果 YAML 配置文件不遵循支持的架构，则对话框将显示以下错误：

Unable to parse configuration file agent-config.yml. Review configuration file. Exiting application.

解决方案

  1. 验证配置文件是否遵循支持的架构。

  2. 如果想从头开始，请将默认配置文件复制到 agent-config.yml 中。您可以使用“任务配置”部分中提供的示例 agent-config.yml。

  3. 您也可以通过删除 agent-config.yml 重新开始。EC2Launch v2 设置会生成空配置文件。

task:executeScript should be unique and only invoked once

描述

不能在同一阶段重复一个任务。

解决方案

有些任务必须作为数组输入，例如 executeScript 和 executeProgram。有关如何将脚本编写为数组的示例，请参阅 executeScript。

Windows 事件日志

EC2Launch v2 发布重要事件的 Windows 事件日志，例如服务启动、Windows 已就绪以及任务成功和失败。事件标识符唯一标识特定事件。每个事件都包含阶段、任务和级别信息以及描述。您可以使用事件标识符为特定事件设置触发器。

事件 ID 提供有关事件的信息，并唯一标识某些事件。事件 ID 的最低有效位表示事件的严重性。

活动 最低有效位
Success . . .0
Informational . . .1
Warning . . .2
Error . . .3

当服务启动或停止时生成的与服务相关的事件，包括个位数事件标识符。

活动 个位数标识符
Success 0
Informational 1
Warning 2
Error 3

EC2LaunchService.exe 事件的事件消息以 Service: 开头。EC2Launch.exe 事件的事件消息不以 Service: 开头。

四位数的事件 ID 包括有关事件阶段、任务和严重性的信息。

事件 ID 格式

下表显示了 EC2Launch v2 事件标识符的格式。

3 2 1 0

S

T

L

表中的字母和数字代表以下事件类型和定义。

Event type 定义

S（阶段）

0 – 服务级别消息

1 – Boot

2 – Network

3 – PreReady

5 – Windows 准备就绪

6 – Postready

7 – UserData

T（任务）

由相应的两个值表示的任务在每个阶段都不同。要查看事件的完整列表，请参阅 Windows 事件日志架构。
L（事件级别）

0 – 成功

1 – 信息性

2 – 警告

3 – 错误

事件 ID 示例

以下是示例事件 ID。

  • 5000 – Windows 已准备好使用

  • 3010 – PreReady 阶段中的激活 Windows 任务已成功执行

  • 6013 – Postready 本地数据阶段中的设置壁纸任务遇到错误

Windows 事件日志架构

消息/事件 ID 事件消息
. . .0 Success
. . .1 Informational
. . .2 Warning
. . .3 Error
x EC2Launch service-level logs
0 EC2Launch service exited successfully
1 EC2Launch service informational logs
2 EC2Launch service warning logs
3 EC2Launch service error logs
10 Replace state.json with previous-state.json
100 Serial Port
200 Sysprep
300 PrimaryNic
400 Metadata
x000 Stage (1 digit), Task (2 digits), Status (1 digit)
1000 Boot
1010 Boot - extend_root_partition
2000 Network
2010 Network - add_routes
3000 PreReady
3010 PreReady - activate_windows
3020 PreReady - install_egpu_manager
3030 PreReady - set_monitor_on
3040 PreReady - set_hibernation
3050 PreReady - set_admin_account
3060 PreReady - set_dns_suffix
3070 PreReady - set_wallpaper
3080 PreReady - set_update_schedule
3090 PreReady - output_log
3100 PreReady - enable_open_ssh
5000 Windows is Ready to use
6000 PostReadyLocalData
7000 PostReadyUserData
6010/7010 PostReadyLocal/UserData - set_wallpaper
6020/7020 PostReadyLocal/UserData - set_update_schedule
6030/7030 PostReadyLocal/UserData - set_hostname
6040/7040 PostReadyLocal/UserData - execute_program
6050/7050 PostReadyLocal/UserData - execute_script
6060/7060 PostReadyLocal/UserData - manage_package
6070/7070 PostReadyLocal/UserData - initialize_volume
6080/7080 PostReadyLocal/UserData - write_file
6090/7090 PostReadyLocal/UserData - start_ssm
7100 PostReadyUserData - enable_open_ssh
6110/7110 PostReadyLocal/UserData - enable_jumbo_frames

EC2Launch v2 控制台日志输出

本部分包含 EC2Launch v2 的示例控制台日志输出，并列出所有 EC2Launch v2 控制台日志错误消息，以帮助您排查问题。有关实例控制台输出及如何进行访问的更多信息，请参阅 实例控制台输出。

EC2Launch v2 控制台日志输出

以下是 EC2Launch v2 的示例控制台日志输出。

2023/11/30 20:18:53Z: Windows sysprep configuration complete.
2023/11/30 20:18:57Z: Message: Waiting for access to metadata...
2023/11/30 20:18:57Z: Message: Meta-data is now available.
2023/11/30 20:18:57Z: AMI Origin Version: 2023.11.15
2023/11/30 20:18:57Z: AMI Origin Name: Windows_Server-2022-English-Full-Base
2023/11/30 20:18:58Z: OS: Microsoft Windows NT 10.0.20348
2023/11/30 20:18:58Z: OsVersion: 10.0
2023/11/30 20:18:58Z: OsProductName: Windows Server 2022 Datacenter
2023/11/30 20:18:58Z: OsBuildLabEx: 20348.1.amd64fre.fe_release.210507-1500
2023/11/30 20:18:58Z: OsCurrentBuild: 20348
2023/11/30 20:18:58Z: OsReleaseId: 2009
2023/11/30 20:18:58Z: Language: en-US
2023/11/30 20:18:58Z: TimeZone: UTC
2023/11/30 20:18:58Z: Offset: UTC +0000
2023/11/30 20:18:58Z: Launch: EC2 Launch v2.0.1643
2023/11/30 20:18:58Z: AMI-ID: ami-1234567890abcdef1
2023/11/30 20:18:58Z: Instance-ID: i-1234567890abcdef0
2023/11/30 20:18:58Z: Instance Type: c5.large
2023/11/30 20:19:00Z: Driver: AWS NVMe Driver v1.5.0.33
2023/11/30 20:19:00Z: SubComponent: AWS NVMe Driver v1.5.0.33; EnableSCSIPersistentReservations: 0
2023/11/30 20:19:00Z: Driver: AWS PV Driver Package v8.4.3
2023/11/30 20:19:01Z: Driver: Amazon Elastic Network Adapter v2.6.0.0
2023/11/30 20:19:01Z: RDPCERTIFICATE-SUBJECTNAME: EC2AMAZ-SO1T009
2023/11/30 20:19:01Z: RDPCERTIFICATE-THUMBPRINT: 1234567890ABCDEF1234567890ABCDEF1234567890
2023/11/30 20:19:09Z: SSM: Amazon SSM Agent v3.2.1705.0
2023/11/30 20:19:13Z: Username: Administrator
2023/11/30 20:19:13Z: Password: <Password>
1234567890abcdef1EXAMPLEPASSWORD
</Password>
2023/11/30 20:19:14Z: User data format: no_user_data	
2023/11/30 20:19:14Z: EC2LaunchTelemetry: IsTelemetryEnabled=true
2023/11/30 20:19:14Z: EC2LaunchTelemetry: AgentOsArch=windows_amd64
2023/11/30 20:19:14Z: EC2LaunchTelemetry: IsAgentScheduledPerBoot=true
2023/11/30 20:19:14Z: EC2LaunchTelemetry: AgentCommandErrorCode=0
2023/11/30 20:19:14Z: Message: Windows is Ready to use

EC2Launch v2 控制台日志消息

以下是所有 EC2Launch v2 控制台日志消息的列表。

Message: Error EC2Launch service is stopping. {error message}
 Error setting up EC2Launch agent folders
 See instance logs for detail
 Error stopping service
 Error initializing service
Message: Windows sysprep configuration complete
Message: Invalid administrator username: {invalid username}
Message: Invalid administrator password
Username: {username}
Password: <Password>{encrypted password}</Password>
AMI Origin Version: {amiVersion}
AMI Origin Name: {amiName}
Microsoft Windows NT {currentVersion}.{currentBuildNumber}
OsVersion: {currentVersion}
OsProductName: {productName}
OsBuildLabEx: {buildLabEx}
OsCurrentBuild: {currentBuild}
OsReleaseId: {releaseId}
Language: {language}
TimeZone: {timeZone}
Offset: UTC {offset}
Launch agent: EC2Launch {BuildVersion}
AMI-ID: {amiId}
Instance-ID: {instanceId}
Instance Type: {instanceType}
RDPCERTIFICATE-SUBJECTNAME: {certificate subject name}
RDPCERTIFICATE-THUMBPRINT: {thumbprint hash}
SqlServerBilling: {sql billing}
SqlServerInstall: {sql patch leve, edition type}
Driver: AWS NVMe Driver {version}
Driver: Inbox NVMe Driver {version}
Driver: AWS PV Driver Package {version}
Microsoft-Hyper-V is installed.
Unable to get service status for vmms
Microsoft-Hyper-V is {status}
SSM: Amazon SSM Agent {version}
AWS VSS Version: {version}
Message: Windows sysprep configuration complete
Message: Windows is being configured. SysprepState is {state}
Windows is still being configured. SysprepState is {state}
Message: Windows is Ready to use
Message: Waiting for meta-data accessibility...
Message: Meta-data is now available.
Message: Still waiting for meta-data accessibility...
Message: Failed to find primary network interface...retrying...
User data format: {format}