配置 Windows 实例的 EC2Launch v2 设置

本节包含有关如何配置 EC2Launch v2 的设置的信息。

使用 EC2Launch v2 设置对话框更改设置

以下是根据在 EC2Launch 对话框中输入的设置创建的示例配置 YAML 文件。

version: 1.0
config:
  - stage: boot
	tasks:
      - task: extendRootPartition
  - stage: preReady
    tasks:
      - task: activateWindows
        inputs:
          activation:
            type: amazon
      - task: setDnsSuffix
        inputs:
          suffixes:
            - $REGION.ec2-utilities.amazonaws.com
      - task: setAdminAccount
        inputs:
          password:
            type: random
      - task: setWallpaper
        inputs:
          path: C:\ProgramData\Amazon\EC2Launch\wallpaper\Ec2Wallpaper.jpg
          attributes:
            - hostName
            - instanceId
            - privateIpAddress
            - publicIpAddress
            - instanceSize
            - availabilityZone
            - architecture
            - memory
            - network
  - stage: postReady
    tasks:
      - task: startSsm

使用 CLI 配置 EC2Launch v2

您可以使用命令行界面 (CLI) 配置 EC2Launch 设置和管理服务。以下部分包含您可用于管理 EC2Launch v2 的 CLI 命令的描述和使用信息。

collect-logs

收集 EC2Launch 的日志文件，压缩文件，并将其放置在指定的目录中。

示例

ec2launch collect-logs -o C:\Mylogs.zip

用法

ec2launch collect-logs [flags]

Flags

-h, --help

collect-logs 的帮助

-o, --output string

压缩输出日志文件的路径

get-agent-config

以指定的格式（JSON 或 YAML）输出 agent-config.yml。如果未指定格式，则会以先前指定的格式输出 agent-config.yml。

示例

ec2launch get-agent-config -f json

示例 2

以下 PowerShell 命令展示了如何以 JSON 格式编辑和保存 agent-config 文件。

$config = & "$env:ProgramFiles/Amazon/EC2Launch/EC2Launch.exe" --format json | ConvertFrom-Json
$jumboFrame =@"
{
   "task": "enableJumboFrames"
}
"@
$config.config | %{if($_.stage -eq 'postReady'){$_.tasks += (ConvertFrom-Json -InputObject $jumboFrame)}}
$config | ConvertTo-Json -Depth 6 | Out-File -encoding UTF8
$env:ProgramData/Amazon/EC2Launch/config/agent-config.yml

用法

ec2launch get-agent-config [flags]

Flags

-h, --help

get-agent-config 的帮助

-f, --format string

agent-config 文件的输出格式：json、yaml

list-volumes

列出附加到实例的所有存储卷，包括临时卷和 EBS 卷。

示例

ec2launch list-volumes

用法

ec2launch list-volumes

Flags

-h, --help

list-volumes 的帮助

重置

此任务的主要目标是在代理下次运行时对其进行重置 为此，reset 命令从本地 EC2Launch 目录中删除 EC2Launch v2 的所有代理状态数据（请参阅 EC2Launch v2 目录结构）。重置可选择性地删除服务和 Sysprep 日志。

脚本行为取决于代理在哪种模式下运行脚本：内联或分离。

示例

ec2launch reset -c

用法

ec2launch reset [flags]

Flags

-c, --clean

在reset前清除实例日志

-h, --help

reset 的帮助

run

运行 EC2Launch v2。

示例

ec2launch run

用法

ec2launch run [flags]

Flags

-h, --help

run 的帮助

状态

获取 EC2Launch v2 代理的状态。也可选择在代理完成运行之前阻止该进程。进程退出代码决定了代理状态：

示例：

ec2launch status -b

用法

ec2launch status [flags]

Flags

-b,--block

在代理完成运行前阻止才进程

-h,--help

status 的帮助

sysprep

此任务的主要目标是在代理下次运行时对其进行重置 为此，sysprep 命令会重置代理状态、更新 unattend.xml 文件、禁用 RDP 并运行 Sysprep。

脚本行为取决于代理在哪种模式下运行脚本：内联或分离。

示例：

ec2launch sysprep

用法

ec2launch sysprep [flags]

Flags

-c,--clean

在sysprep前清除实例日志

-h,--help

Sysprep 的帮助

-s,--shutdown

sysprep之后关闭实例

验证

验证 agent-config 文件 C:\ProgramData\Amazon\EC2Launch\config\agent-config.yml。

示例

ec2launch validate

用法

ec2launch validate [flags]

Flags

-h ，--help

validate 的帮助

版本

获取可执行版本。

示例

ec2launch version

用法

ec2launch version [flags]

Flags

-h, --help

version 的帮助

wallpaper

将新壁纸设置为提供的壁纸路径（.jpg 文件），并显示选定的实例详细信息。

语法

ec2launch wallpaper ^
--path="C:\ProgramData\Amazon\EC2Launch\wallpaper\Ec2Wallpaper.jpg" ^
--all-tags ^
--attributes=hostName,instanceId,privateIpAddress,publicIpAddress,instanceSize,availabilityZone,architecture,memory,network

输入

EC2Launch v2 任务配置

本节包括 agent-config.yml 和用户数据的配置架构、任务、详细信息和示例。

架构：agent-config.yml

agent-config.yml 文件的结构如下所示。请注意，不能在同一阶段重复一个任务。有关任务属性，请参阅随后的任务说明。

文档结构：agent-config.yml

JSON

{
	"version": "1.0",
	"config": [
		{
			"stage": "string",
			"tasks": [
				{
					"task": "string",
					"inputs": {
						...
					}
				},
				...
			]
		},
		...
	]
}

YAML

version: 1.0
config:
- stage: string
  tasks:
  - task: string
	inputs:
	  ...
  ...
...

示例：agent-config.yml

以下示例显示了 agent-config.yml 配置文件的设置。

version: 1.0
config:
- stage: boot
  tasks:
  - task: extendRootPartition
- stage: preReady
  tasks:
  - task: activateWindows
    inputs:
      activation:
        type: amazon
  - task: setDnsSuffix
    inputs:
      suffixes:
      - $REGION.ec2-utilities.amazonaws.com
  - task: setAdminAccount
    inputs:
      password:
        type: random
  - task: setWallpaper
    inputs:
      path: C:\ProgramData\Amazon\EC2Launch\wallpaper\Ec2Wallpaper.jpg
      attributes:
      - hostName
      - instanceId
      - privateIpAddress
      - publicIpAddress
      - instanceSize
      - availabilityZone
      - architecture
      - memory
      - network
- stage: postReady
  tasks:
  - task: startSsm

配置在启动或重启期间运行的 EC2Launch v2 用户数据脚本

以下 JSON 和 YAML 示例显示了用户数据的文档结构。Amazon EC2 解析您在文档中指定的 tasks 数组中命名的每个任务。每个任务都有自己的一组属性和要求。有关详细信息，请参阅 EC2Launch v2 启动任务的任务定义。

文档结构：用户数据

JSON

{
	"version": "1.1",
	"tasks": [
		{
			"task": "string",
			"inputs": {
				...
			},
		},
		...
	]
}

YAML

version: 1.1
tasks:
- task: string
  inputs:
    ...
...

示例：用户数据

有关用户数据的更多信息，请参阅 Amazon EC2 如何处理 Windows 实例的用户数据。

以下 YAML 文档示例显示了 EC2Launch v2 作为用户数据运行的 PowerShell 脚本，用于创建文件。

version: 1.1
tasks:
- task: executeScript
  inputs:
  - frequency: always
    type: powershell
    runAs: localSystem
    content: |-
      New-Item -Path 'C:\PowerShellTest.txt' -ItemType File

您可以对用户数据使用与先前版本的启动代理兼容的 XML 格式。EC2Launch v2 在 UserData 阶段将脚本作为 executeScript 任务运行。为了符合 EC2Launch v1 和 EC2Config 的行为，默认情况下，用户数据脚本以附加/内联进程运行。

您可以添加可选标签来自定义脚本的运行方式。例如，要在实例重新启动时运行用户数据脚本以及在实例启动时运行一次用户数据脚本，您可以使用以下标签：

<persist>true</persist>

示例：

<powershell>
  $file = $env:SystemRoot + "\Temp" + (Get-Date).ToString("MM-dd-yy-hh-mm")
  New-Item $file -ItemType file
</powershell>
<persist>true</persist>

您可以使用 <powershellArguments> 标签来指定一个或多个 PowerShell 参数。如果未传递任何参数，则默认情况下，EC2Launch v2 会添加以下参数：-ExecutionPolicy Unrestricted。

示例：

<powershell>
  $file = $env:SystemRoot + "\Temp" + (Get-Date).ToString("MM-dd-yy-hh-mm")
  New-Item $file -ItemType file
</powershell>
<powershellArguments>-ExecutionPolicy Unrestricted -NoProfile -NonInteractive</powershellArguments>

要将 XML 用户数据脚本作为分离的进程运行，请在您的用户数据中添加以下标签。

<detach>true</detach>

示例：

<powershell>
  $file = $env:SystemRoot + "\Temp" + (Get-Date).ToString("MM-dd-yy-hh-mm")
  New-Item $file -ItemType file
</powershell>
<detach>true</detach>

更改日志：用户数据

下表列出了用户数据更改，并将其交叉引用至适用的 EC2Launch v2 代理版本。

* 与默认 agent-config.yml 文件结合使用时。

EC2Launch v2 退出代码并重新启动

您可以使用 EC2Launch v2 定义脚本如何处理退出代码。默认情况下，脚本中运行的最后一个命令的退出代码将报告为整个脚本的退出代码。例如，如果脚本包含三个命令，而第一个命令失败，但以下命令成功，则运行状态将报告为 success，因为最后一个命令成功。

如果您希望脚本重启实例，则必须在脚本中指定 exit 3010，即使重启是脚本中的最后一步，也必须在脚本中指定。exit 3010 指示 EC2Launch v2 重新启动实例并再次调用脚本，直到它返回不是 3010 的退出代码，或者直到达到最大重启计数为止。EC2Launch v2 允许每个任务最多重启 5 次。如果您尝试使用其他机制（例如）从脚本重启实例 Restart-Computer，则脚本运行状态将不一致。例如，它可能会陷入重启循环或不执行重启。

如果您使用的是与旧代理兼容的 XML 用户数据格式，则用户数据的运行时间可能会超过您预期的运行时间。有关更多信息，请参阅排查部分中的服务多次运行用户数据。

EC2Launch v2 和 Sysprep

EC2Launch v2 服务会运行 Sysprep，借助该 Microsoft 工具您可以创建可重复使用的自定义 Windows AMI。在 EC2Launch v2 调用 Sysprep 时，会使用 %ProgramData%\Amazon\EC2Launch 中的设置文件来确定要执行的操作。您可以使用 EC2Launch 设置对话框间接编辑这些文件，也可以直接使用 YAML 编辑器或文本编辑器直接编辑。然而，有些高级设置并未包含在 EC2Launch 设置 对话框中，因此您必须直接编辑这些条目。

如果您在更新某实例的设置之后从中创建了一个 AMI，则新设置会应用到所有从新 AMI 启动的实例。有关创建 AMI 的信息，请参阅创建 Amazon EBS-backed AMI。