使用 EC2Launch v2 代理在 EC2 Windows 实例启动期间执行任务 - Amazon Elastic Compute Cloud
EC2Launch v2 概念EC2Launch v2 任务概览EC2Launch v2 目录结构遥测
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

使用 EC2Launch v2 代理在 EC2 Windows 实例启动期间执行任务

默认情况下，从 Amazon Windows Server 2022 和 Windows Server 2025 AMI 启动的所有受支持的 Amazon EC2 实例包含 EC2Launch v2 启动代理 (EC2Launch.exe)。我们还提供 Windows Server 2016 和 2019 AMI，其中安装了 EC2Launch v2 作为默认的启动代理。除了包含 EC2Launch v1 的 Windows Server 2016 和 2019 AMI 之外，还提供了这些 AMI。您可以在 Amazon EC2 控制台 AMI 页面的搜索中输入以下前缀来搜索默认包含 EC2Launch v2 的 Windows AMI：EC2LaunchV2-Windows_Server-*。

要比较启动代理版本的功能，请参阅 比较 Amazon EC2 启动代理。

EC2Launch v2 在实例启动期间执行任务，并可在实例停止并稍后启动或重新启动时运行。EC2Launch v2 还可按需执行任务。部分任务可自动启用，而其他任务必须手动启用。EC2Launch v2 服务支持所有 EC2Config 和 EC2Launch 功能。

此服务使用配置文件来控制其操作。您可以使用图形工具或直接将其作为单个 .yml 文件 (agent-config.yml) 进行编辑，以此来更新配置文件。有关文件位置的更多信息，请参阅 EC2Launch v2 目录结构。

EC2Launch v2 发布 Windows 事件日志，帮助您进行故障排除和设置触发器。有关更多信息，请参阅 Windows 事件日志。

支持的操作系统版本

EC2Launch v2 代理支持以下 Windows Server 操作系统（OS）版本：

  • Windows Server 2025

  • Windows Server 2022

  • Windows Server 2019（长期服务渠道和半年期服务渠道）

  • Windows Server 2016

默认运行的任务

EC2Launch v2 代理在初始实例启动期间默认仅运行以下任务一次。任务按照其在启动阶段的运行顺序进行组织。

Boot 阶段

  • extendRootPartition

PreReady 阶段

  • activateWindows

  • setDnsSuffix

  • setAdminAccount

  • setWallpaper

PostReady 阶段

  • startSsm

EC2Launch v2 概念

在考虑使用 EC2Launch v2 时，以下概念很有用。

agent-config

agent-config 是位于 EC2Launch v2 的配置文件夹中的文件。它包括用于 boot、network、PreReady 和 PostReady 阶段的配置。此文件用于指定在 AMI 首次引导或以后引导时，应运行任务的实例配置。

默认情况下，EC2Launch v2 安装会安装一个 agent-config 文件，其中包含在标准 Amazon Windows AMI 中使用的推荐配置。您可以更新配置文件以更改 EC2Launch v2 为您的 AMI 指定的默认引导体验。有关文件位置的更多信息，请参阅 EC2Launch v2 目录结构。

Frequency

任务频率决定任务的运行时间，具体取决于引导上下文。大多数任务的频率只有一次。您可以指定 executeScript 任务的频率。

您将在 EC2Launch v2 任务配置 中看到以下频率。

  • 一次 — 任务在 AMI 首次引导时（完成了 Sysprep）运行一次。

  • 始终 — 任务在每次启动代理运行时都会运行。启动代理在以下情况运行：

    • 实例启动或重新启动时

    • EC2Launch 服务运行时

    • EC2Launch.exe run 被调用

阶段

阶段是 EC2Launch v2 代理运行的任务的逻辑分组。某些任务只能在特定阶段运行。另一些任务可以分多个阶段运行。使用 agent-config.yml 时，必须指定阶段列表以及每个阶段内运行的任务列表。

该服务按以下顺序运行阶段：

第 1 阶段：启动

第 2 阶段：网络

第 3 阶段：PreReady

Windows 准备就绪

PreReady 阶段完成后，该服务会将 Windows is ready 消息发送到 Amazon EC2 控制台。

第 4 阶段：PostReady

用户数据在 PostReady 阶段运行。有些脚本版本在 agent-config.yml 文件 PostReady 阶段之前运行，有些则在之后运行，如下所示：

在 agent-config.yml 之前：

  • YAML 用户数据版本 1.1

  • XML 用户数据

在 agent-config.yml 之后

  • YAML 用户数据版本 1.0（用于向后兼容的旧版本）

有关示例阶段和任务，请参阅 示例：agent-config.yml。

使用用户数据时，必须指定要运行的启动代理的任务列表。阶段是默认的。有关示例任务，请参阅 示例：用户数据。

EC2Launch v2 会按照您在 agent-config.yml 和用户数据中指定的顺序运行任务列表。阶段按顺序运行。上一阶段完成后，开始下一阶段。任务也按顺序运行。

Task

您可以调用任务来对实例执行操作。您可以在 agent-config.yml 文件中或通过用户数据配置任务。有关 EC2Launch v2 的可用任务列表，请参阅 EC2Launch v2 任务。有关任务配置架构和详细信息，请参阅 EC2Launch v2 任务配置。

用户数据

用户数据是在启动实例时可配置的数据。您可以更新用户数据以动态更改如何配置自定义 AMI 或快速启动 AMI。EC2Launch v2 支持 60 kB 用户数据输入长度。用户数据仅包括 UserData 阶段，因此在 agent-config 文件之后运行。您可以在使用启动实例向导启动实例时输入用户数据，也可以从 EC2 控制台修改用户数据。有关使用用户的更多信息，请参阅Amazon EC2 如何处理 Windows 实例的用户数据。

EC2Launch v2 任务概览

EC2Launch v2 可以在每次引导时执行以下任务：

  • 设置新的（可选）自定义壁纸，以呈现有关实例的信息。

  • 为在本地计算机上创建的管理员账户设置属性。

  • 将 DNS 后缀添加到搜索后缀列表中。只有尚不存在的后缀才会添加到列表中。

  • 为任何附加卷设置驱动器盘符，并扩展它们以使用可用空间。

  • 将配置中的文件写入磁盘。

  • 运行 EC2Launch v2 配置文件或 user-data 中指定的脚本。user-data 的脚本可以是纯文本，也可以是压缩文件，并以 base64 格式提供。

  • 使用给定参数运行程序。

  • 设置计算机名称。

  • 将实例信息发送到 Amazon EC2 控制台。

  • 向 Amazon EC2 控制台发送 RDP 证书指纹。

  • 请动态扩展操作系统分区，以包含所有未分区的空间。

  • 运行用户数据。有关指定用户数据的更多信息，请参阅EC2Launch v2 任务配置。

  • 设置非持久静态路由以访问元数据服务和 Amazon KMS 服务器。

  • 将非引导分区设置为 mbr 或 gpt。

  • 在 Sysprep 之后启动 Systems Manager 服务。

  • 优化 ENA 设置。

  • 为更高版本的 Windows 启用 OpenSSH。

  • 启用巨型帧。

  • 将 Sysprep 设置为与 EC2Launch v2 一起运行。

  • 发布 Windows 事件日志。

EC2Launch v2 目录结构

EC2Launch v2 应安装在以下目录中：

  • 服务二进制文件：%ProgramFiles%\Amazon\EC2Launch

  • 服务数据（设置、日志文件和状态文件）：%ProgramData%\Amazon\EC2Launch

注意

默认情况下，Windows 会隐藏 C:\ProgramData 下的文件和文件夹。要查看 EC2Launch v2 目录和文件，必须在 Windows 资源管理器中输入路径，或者更改文件夹属性以显示隐藏的文件和文件夹。

%ProgramFiles%\Amazon\EC2Launch 目录包含二进制文件和支持库。它包括以下子目录：

  • settings

    • EC2LaunchSettingsUI.exe：用于修改 agent-config.yml 文件的用户界面

    • YamlDotNet.dll：用于支持用户界面中部分操作的 DLL

  • tools

    • ebsnvme-id.exe：用于检查实例上 EBS 卷的元数据的工具

    • AWSAcpiSpcrReader.exe：用于确定要使用的正确 COM 端口的工具

    • EC2LaunchEventMessage.dll：用于支持 EC2Launch 的 Windows 事件日志记录的 DLL

  • service

    • EC2LaunchService.exe：当启动代理作为一项服务运行时所启动的 Windows 服务可执行文件

  • EC2AgentTelemetry.dll：用于支持 EC2 代理遥测的 DLL

  • EC2Launch.exe：主要 EC2Launch 可执行文件

  • EC2LaunchAgentAttribution.txt：EC2Launch 中使用的代码的归因

%ProgramData%\Amazon\EC2Launch 目录包含以下子目录。服务生成的所有数据（包括日志、配置和状态）都存储在此目录中。

  • config – 配置

    服务配置文件作为 agent-config.yml 存储在此目录中。此文件可以进行更新以修改、添加或删除由服务运行的原定设置任务。在此目录中创建文件的权限仅限于管理员账户，以防止特权提升。

  • log – 实例日志

    服务（agent.log）、控制台（console.log）、性能（bench.log）、错误（err.log）和遥测（telemetry.log）的日志都存储在此目录中。日志文件会在服务的后续执行时附加。

  • state – 服务状态数据

    服务用于确定应运行哪些任务的状态存储在此处。其中有一个 .run-once 文件，指示服务是否已在 Sysprep 之后运行（因此，频率为一次的任务在下次运行时将跳过）。此子目录包含 state.json 和 previous-state.json，用于跟踪每个任务的状态。

  • sysprep – Sysprep

    此目录包含的文件用于确定 Sysprep 在创建可重复使用的自定义 Windows AMI 时，需要执行哪些操作。

  • wallpaper – 墙纸

    此墙纸图像存储在此目录中。

遥测

遥测是附加信息，可帮助 Amazon 更好地了解您的需求、诊断问题并提供功能，以改善 Amazon Web Services 服务 带给您的体验。

EC2Launch v2 版本 2.1.592 及更高版本会收集遥测，例如使用情况指标和错误。此数据是从运行 EC2Launch v2 的 Amazon EC2 实例收集的。这包括 Amazon 拥有的所有 Windows AMI。

EC2Launch v2 收集以下类型的遥测：

  • 使用情况信息 — 代理命令、安装方法和计划的运行频率。

  • 错误和诊断信息 — 代理安装错误代码、运行错误代码和错误调用堆栈。

从 2.0.592 到 2.1.1 版本收集的数据示例：

2025/07/18 22:38:52Z: EC2LaunchTelemetry: IsTelemetryEnabled=true
2025/07/18 22:38:52Z: EC2LaunchTelemetry: AgentOsArch=windows_amd64
2025/07/18 22:38:52Z: EC2LaunchTelemetry: IsAgentScheduledPerBoot=true
2025/07/18 22:38:52Z: EC2LaunchTelemetry: AgentCommandErrorCode=0
2025/07/18 22:38:52Z: EC2LaunchTelemetry: AdminPasswordTypeCode=0
2025/07/18 22:38:52Z: EC2LaunchTelemetry: IpConflictDetectionCode=0
2025/07/18 22:38:52Z: EC2LaunchTelemetry: AgentErrorLocation=addroutes.go:49

从 2.2.63 版本开始，EC2 代理遥测数据被格式化为 JSON 对象：

{"type":"EC2AgentTelemetry","agentId":"WindowsLaunchAgentV2" ... }

预设情况下，遥测处于启用状态。您可以随时禁用遥测收集。

在实例上禁用遥测

要禁用单个实例的遥测，您可以设置系统环境变量，也可以使用 MSI 修改安装。

要通过设置系统环境变量来禁用遥测，请以管理员身份运行以下命令。

setx /M EC2LAUNCH_TELEMETRY 0

要使用 MSI 禁用遥测，请在下载 MSI 后运行以下命令。

msiexec /i ".\AmazonEC2Launch.msi" Remove="Telemetry" /q
EC2Launch v2 的更多主题