本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
EC2Launch v2 設定
本節包含有關如何進行 EC2Launch v2 設定的資訊。
主題包括：
使用 EC2Launch v2 設定對話方塊變更設定
下列程序說明如何使用 EC2Launch v2 對話方塊啟用或停用設定。
注意
如果您在 agent-config.yml 檔案中不當設定自訂任務，並嘗試開啟 Amazon EC2Launch 設定對話方塊，您將收到錯誤。有關架構範例，請參閱 範例：agent-config.yml。
-
啟動和連線至 Windows 執行個體。
-
從「開始」功能表選擇所有程式,，然後瀏覽至 EC2Launch 設定。
-
在 Ec2 服務屬性對話方塊的一般索引標籤中，啟用或停用下列設定。
-
Set Computer Name (設定電腦名稱)
如果啟用此設定 (預設為停用)，則會在每次開機時將目前主機名稱與所需主機名稱進行比較。如果主機名稱不相符，則會重設主機名稱，然後系統會選擇性地重新開機以取得新的主機名稱。如果未指定自訂主機名稱，則會使用十六進位格式的私有 IPv4 地址產生名稱，例如：
ip-AC1F4E6。若要避免現有的主機名稱遭到修改，請勿啟用此設定。 -
延伸開機磁碟區
此設定將動態擴充
Disk 0/Volume 0，以包含任何尚未分割的空間。此設定在執行個體是從自訂大小的根裝置磁碟區啟動時很有用。 -
設定管理員帳戶
啟用後，您可以為本機電腦上建立的管理員帳戶設定使用者名稱和密碼屬性。如果未啟用此功能，遵循 Sysprep 的系統不會建立系統管理員帳戶。只有在
adminPassword是adminPasswordtype時，才要在Specify中提供密碼。密碼類型的定義如下：
-
RandomEC2Launch 會產生密碼並以使用者金鑰將其加密。系統會在執行個體啟動後停用此設定，以便執行個體重新開機或停止再啟動時，能持續使用這個密碼。
-
SpecifyEC2Launch 會使用您在
adminPassword中指定的密碼 如果該密碼不符合系統要求，EC2Launch 會改為產生隨機密碼。系統會將該密碼以純文字存放於agent-config.yml，並在 Sysprep 設定管理員密碼後予以刪除。EC2Launch 會以使用者金鑰加密該密碼。 -
Do not setEC2Launch 會使用您在未使用的 .xml 檔案中指定的密碼。如果您未在 unattend.xml 中指定密碼，會停用管理員帳戶。
-
-
啟動 SSM 服務
選取此選項時，Systems Manager 服務會啟用，以啟動以下 Sysprep。EC2Launch v2 將執行先前所述的所有任務，而且 SSM Agent 將處理 Systems Manager 功能的請求，例如執行命令和狀態管理員。
您可使用執行命令升級現有執行個體，以使用 EC2Launch v2 服務和 SSM Agent 的最新版本。如需詳細資訊，請參閱《AWS Systems Manager 使用者指南》中的使用執行命令更新 SSM Agent。
-
最佳化 ENA
選取時，ENA 設定會設定為確保 ENA 接收端調整和接收佇列深度設定已針對最佳化 AWS。如需詳細資訊，請參閱 設定 RSS CPU 親和性。
-
啟用 SSH
此設定會啟用適用於較新版本 Windows 的 OpenSSH，以允許遠端系統管理。
-
啟用巨型訊框
選取以啟用「巨型訊框」。「巨型訊框」可能會對您的網路通訊產生意想不到的影響，因此在啟用之前，請務必了解「巨型訊框」對您的系統的影響。如需「巨型訊框」的詳細資訊，請參閱 巨型訊框 (9001 MTU)。
-
準備建立映像
選取是否希望 EC2 執行個體在使用 Sysprep 的情況下關閉。當您想要使用 EC2Launch v2 執行 Sysprep 時，請選擇 Shutdown with Sysprep (使用 Sysprep 關機)。
-
-
在DNS 尾碼標籤上，您可以選取是否要為 EC2 中執行之伺服器的 DNS 解析新增 DNS 尾碼清單，而不需提供完整網域名稱。DNS 尾碼可以包含變數
$REGION和$AZ。只有不存在的尾碼才會新增到清單中。
-
在桌布索引標籤中，您可以使用背景圖片來設定執行個體桌布，並指定要顯示之桌布的執行個體詳細資訊。Amazon EC2 會在您每次登入時產生詳細資訊。
您可以使用下列控制項來設定桌布。
-
在桌布上顯示執行個體詳細資訊 - 此核取方塊會啟用或停用桌布上的執行個體詳細資訊顯示。
-
圖片路徑 (.jpg) - 指定要用作桌布背景的圖片路徑。
-
選取要在桌布上顯示的屬性 - 選取要顯示在桌布上之執行個體詳細資訊的核取方塊。清除要從桌布中移除的先前選取的執行個體詳細資訊的核取方塊。
-
在桌布上顯示執行個體標籤 - 選取下列其中一個設定以在桌布上顯示執行個體標籤：
-
無 - 不在桌布上顯示任何執行個體標籤。
-
顯示全部 - 在桌布上顯示所有執行個體標籤。
-
顯示篩選結果 - 在桌布上顯示指定的執行個體標籤。當您選取此設定時，可以在執行個體標籤篩選方塊中新增您想要顯示在桌布上的執行個體標籤。
注意
您必須在中繼資料中啟用標籤，才能在桌布上顯示標籤。如需有關執行個體標籤和中繼資料的詳細資訊，請參閱 使用執行個體中繼資料中的執行個體標籤。
-
-
-
在磁碟區標籤上，選取是否要初始化連線至執行個體的磁碟區。啟用會設定任何額外磁碟區的磁碟機代號，並將它們延伸到使用可用空間。如果您選取全部，則會初始化所有儲存磁碟區。如果您選取裝置，則只會初始化清單中指定的裝置。您必須為每個要初始化的裝置輸入裝置。使用 EC2 主控台上列出的裝置，例如，
xvdb或/dev/nvme0n1。下拉式清單會顯示連接到執行個體的儲存磁碟區。若要輸入未連接到執行個體的裝置，請在文字欄位中輸入該裝置。名稱、字母和分割區是選填欄位。如果沒有為磁碟分割區指定任何值，則會以 GPT 磁碟分割區類型初始化大於 2 TB 的儲存磁碟區，而小於 2 TB 的磁碟分割區會以 MBR 磁碟分割區類型初始化。如果已設定裝置，且非 NTFS 裝置包含磁碟分割區表格，或磁碟的前 4 KB 會包含資料，接著系統會略過磁碟並記錄動作。
以下是從 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
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– DLL，用於支援 EC2 啟動的 Windows 事件記錄。
-
-
service-
EC2LaunchService.exe– 啟動代理程式以服務方式執行時，所啟動的 Windows 服務可執行檔。
-
-
EC2Launch.exe– 主 EC2Launch 可執行檔 -
EC2LaunchAgentAttribution.txt– EC2 Launch 中使用的代碼屬性
%ProgramData%\Amazon\EC2Launch 目錄包含下列子目錄。服務產生的所有資料，包括日誌、組態和狀態，都會儲存在此目錄中。
-
config– 組態服務組態檔案儲存在此目錄中為
agent-config.yml。此檔案可以更新，以修改、新增或移除服務所執行的預設任務。在此目錄中建立檔案的許可限制為系統管理員帳戶，以防止權限提升。 -
log– 執行個體日誌服務 (
agent.log)、主控台 (console.log)、效能 (bench.log) 和錯誤 (error.log) 的日誌會儲存在此目錄中。日誌會在後續執行服務時附加。 -
state– 服務狀態資料服務用來判斷應該執行哪些任務的狀態會儲存在此處。有一個
.run-once檔案會指出服務是否已在 Sysprep 之後執行 (因此，下次執行時會略過頻率為一次的任務)。此子目錄包含state.json和previous-state.json以追蹤每個任務的狀態。 -
sysprep– Sysprep此目錄包含的檔案，可用來判斷 Sysprep 在建立可重複使用的自訂 Windows AMI 時要執行哪些作業。
使用 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 v2 代理程式會一次執行一個指令碼 (
detach: false)。這是預設設定。注意
當內嵌指令碼發出 reset 或 sysprep 命令時，它會立即執行並重設代理程式。目前任務完成後，代理程式就會關閉，而不執行任何後續任務。
例如，如果發出命令的任務後緊接著一個
startSsm任務 (預設情況下會在使用者資料執行之後包含)，則任務不會執行，而且 Systems Manager 服務永遠不會啟動。 - Detached
-
EC2Launch v2 代理程式會與其他任務同時執行指令碼 (
detach: true)。注意
當分離的指令碼發出 reset 或 sysprep 命令時，這些命令會等待代理程式完成再執行。executeScript 之後的任務仍會執行。
範例
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 的說明
status
取得 EC2Launch v2 代理程式的狀態。選擇性地封鎖處理程序，直到代理程式完成為止。處理程序結束程式碼會決定代理程式狀態：
-
0– 代理程式已執行且成功。 -
1– 代理程式已執行且失敗。 -
2– 代理程式仍在執行中。 -
3– 代理程式處於未知狀態。代理程式狀態為未執行或已停止。 -
4– 嘗試擷取代理程式狀態時發生錯誤。 -
5– 代理程式未執行，且上次已知執行的狀態未知。這可能表示以下其中一項：-
state.json和previous-state.json均被刪除。 -
previous-state.json已毀損。
這是執行 reset 命令後的代理程式狀態。
-
範例：
ec2launch status -b
用途
ec2launch status [flags]
Flags
-b,--block
封鎖處理程序，直到代理程式完成執行
-h,--help
status 的說明
sysprep
此任務的主要目標是在下次代理程式執行時重設該代理程式。為此，sysprep 命令會重設代理程式狀態、更新 unattend.xml 檔案、停用 RDP，然後執行 Sysprep。
指令碼行為取決於代理程式執行指令碼的模式 (內嵌或分離)。
- 內嵌 (預設)
-
EC2Launch v2 代理程式會一次執行一個指令碼 (
detach: false)。這是預設設定。注意
當內嵌指令碼發出 reset 或 sysprep 命令時，它會立即執行並重設代理程式。目前任務完成後，代理程式就會關閉，而不執行任何後續任務。
例如，如果發出命令的任務後緊接著一個
startSsm任務 (預設情況下會在使用者資料執行之後包含)，則任務不會執行，而且 Systems Manager 服務永遠不會啟動。 - Detached
-
EC2Launch v2 代理程式會與其他任務同時執行指令碼 (
detach: true)。注意
當分離的指令碼發出 reset 或 sysprep 命令時，這些命令會等待代理程式完成再執行。executeScript 之後的任務仍會執行。
範例：
ec2launch sysprep
用途
ec2launch sysprep [flags]
Flags
-c,--clean
在 sysprep 前清除執行個體日誌
-h,--help
Sysprep 說明
-s,--shutdown
在 sysprep 後關閉執行個體
validate
驗證 agent-config 檔案 C:\ProgramData\Amazon\EC2Launch\config\agent-config.yml。
範例
ec2launch validate
用途
ec2launch validate [flags]
Flags
-h , --help
validate 的說明
version
取得可執行版本。
範例
ec2launch version
用途
ec2launch version [flags]
Flags
-h, --help
version 的說明
桌布
將新桌布設定為提供的桌布路徑 (.jpg 檔案)，並顯示選取的執行個體詳細資料。
語法
ec2launch wallpaper ^ --path="C:\ProgramData\Amazon\EC2Launch\wallpaper\Ec2Wallpaper.jpg" ^ --all-tags ^ --attributes=hostName,instanceId,privateIpAddress,publicIpAddress,instanceSize,availabilityZone,architecture,memory,network
輸入
參數
-允許標籤 [標籤名稱 -1,]tag-name-n-
(選用) 要顯示在桌布上的 Base64 編碼 JSON 執行個體標籤名稱陣列。您可以使用此標籤或
--all-tags，但不能同時使用兩者。 -屬性屬性字符串 -1，attribute-string-n-
(選用) 要將設定套用至桌布的
wallpaper屬性字串清單 (以逗號分隔)。 - [--path | -p]
path-string -
(必要) 指定
wallpaper背景圖片檔案路徑。
旗標
- --all-tags
-
(選用) 在桌布上顯示所有執行個體標籤。您可以使用此標籤或
--allowed-tags，但不能同時使用兩者。 - [--help | -h]
-
顯示 wallpaper 命令的說明。
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
結構描述：使用者資料
下列 JSON 和 YAML 範例顯示使用者資料的文件結構。Amazon EC2 會剖析您在文件中指定的 tasks 陣列中命名的每個任務。每個任務都有自己的屬性集和要求集。如需詳細資訊，請參閱 任務定義。
注意
任務只能在使用者資料任務陣列中出現一次。
文件結構：使用者資料
JSON
{ "version": "1.1", "tasks": [ { "task": "string", "inputs": { ... }, }, ... ] }
YAML
version: 1.1 tasks: - task: string inputs: ... ...
範例：使用者資料
如需使用者資料的詳細資訊，請參閱 在您的 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>
若要將 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 代理程式版本。
| 使用者資料版本 | 詳細資訊 | 引入於 |
|---|---|---|
| 1.1 |
|
EC2Launch v2 2.0.1245 版 |
| 1.0 |
|
EC2Launch v2 2.0.0 版 |
* 與預設 agent-config.yml 檔案搭配使用時。
任務定義
每個任務都有自己的屬性集和要求集。如需詳細資訊，請參閱您要在文件中包含的個別任務。
任務
activateWindows
對一組 AWS KMS 伺服器啟動視窗。如果偵測到執行個體為自帶授權 (BYOL)，則會略過啟動。
Frequency — 一次
AllowedStages — [PreReady]
Inputs —
activation：(映射)
type：(字串) 要使用的啟動類型，設定為 amazon
範例
task: activateWindows inputs: activation: type: amazon
enableJumboFrames
啟用「巨型訊框」，以增加網路介面卡的最大傳輸單位 (MTU)。如需詳細資訊，請參閱 巨型訊框 (9001 MTU)。
Frequency – 始終
AllowedStages — [PostReady, UserData]
Inputs — 無
範例
task: enableJumboFrames
enableOpenSsh
啟用 Windows OpenSSH，並將執行個體的公開金鑰新增至授權的金鑰資料夾。
Frequency — 一次
AllowedStages — [PreReady, UserData]
Inputs — 無
範例
以下範例示範如何在執行個體上啟用 OpenSSH，以及如何將執行個體的公有金鑰新增至授權的金鑰資料夾。此組態僅適用於執行 Windows Server 2019 及更新版本的執行個體。
task: enableOpenSsh
executeProgram
執行具有可選引數和指定頻率的程式。
階段：您可以在 PreReady、PostReady 和 UserData 階段執行 executeProgram 任務。
頻率：可設定，請參閱輸入。
- 輸入
-
您可以設定執行期參數，如下所示：
- 頻率 (字串)
-
(必要) 僅指定下列其中一個值：
-
once -
always
-
- 路徑 (字串)
-
(必要) 要執行的可執行檔的檔案路徑。
- 引數 (字串清單)
-
(選用) 以逗號分隔的引數清單，作為輸入提供給程式。
- runAs (字串)
-
(必要) 必須設定為
localSystem
- 輸出
-
所有任務都會將日誌檔案條目寫入
agent.log檔案。executeProgram任務的其他輸出會分別儲存在動態命名的資料夾中，如下所示：%LocalAppData%\Temp\EC2Launch#########\outputfilename.tmp輸出檔案的確切路徑包含在
agent.log檔案中，例如：Program file is created at: C:\Windows\system32\config\systemprofile\AppData\Local\Temp\EC2Launch123456789\ExecuteProgramInputs.tmp Output file is created at: C:\Windows\system32\config\systemprofile\AppData\Local\Temp\EC2Launch123456789\Output.tmp Error file is created at: C:\Windows\system32\config\systemprofile\AppData\Local\Temp\EC2Launch123456789\Err.tmpexecuteProgram任務的輸出檔案ExecuteProgramInputs.tmp-
包含可執行檔的路徑，以及
executeProgram任務在執行時傳送給其所有輸入參數。 Output.tmp-
包含
executeProgram任務執行之程式的執行期輸出。 Err.tmp-
包含
executeProgram任務執行之程式的執行期錯誤訊息。
- 範例
-
下列範例說明如何透過
executeProgram任務，從執行個體上的本機目錄執行可執行檔。範例 1：具有一個引數的設定可執行檔
此範例顯示在靜默模式下執行設定可執行檔的
executeProgram任務。task: executeProgram inputs: - frequency: always path: C:\Users\Administrator\Desktop\setup.exe arguments: ['-quiet']範例 2：具有兩個引數的 VLC 可執行檔
此範例顯示執行 VLC 可執行檔的
executeProgram任務，其中兩個引數作為輸入參數傳遞。task: executeProgram inputs: - frequency: always path: C:\vlc-3.0.11-win64.exe arguments: ['/L=1033','/S'] runAs: localSystem
executeScript
執行具有可選引數和指定頻率的指令碼。指令碼行為取決於代理程式執行指令碼的模式 (內嵌或分離)。
- 內嵌 (預設)
-
EC2Launch v2 代理程式會一次執行一個指令碼 (
detach: false)。這是預設設定。注意
當內嵌指令碼發出 reset 或 sysprep 命令時，它會立即執行並重設代理程式。目前任務完成後，代理程式就會關閉，而不執行任何後續任務。
例如，如果發出命令的任務後緊接著一個
startSsm任務 (預設情況下會在使用者資料執行之後包含)，則任務不會執行，而且 Systems Manager 服務永遠不會啟動。 - Detached
-
EC2Launch v2 代理程式會與其他任務同時執行指令碼 (
detach: true)。注意
當分離的指令碼發出 reset 或 sysprep 命令時，這些命令會等待代理程式完成再執行。executeScript 之後的任務仍會執行。
階段：您可以在 PreReady、PostReady 和 UserData 階段執行 executeScript 任務。
頻率：可設定，請參閱輸入。
- 輸入
-
您可以設定執行期參數，如下所示：
- 頻率 (字串)
-
(必要) 僅指定下列其中一個值：
-
once -
always
-
- 類型 (字串)
-
(必要) 僅指定下列其中一個值：
-
batch -
powershell
-
- 引數 (字串清單)
-
(選用) 傳遞給 shell 的字串引數清單。
type: batch不支援此參數。 - 內容 (字串)
-
(必要) 指令碼內容。
- runAs (字串)
-
(必要) 僅指定下列其中一個值：
-
admin -
localSystem
-
- 分離 (布林值)
-
(選用) EC2Launch v2 代理程式預設為一次執行一個指令碼 (
detach: false)。若要與其他任務同時執行指令碼，請將值設定為true(detach: true)。注意
當
detach設定為true時，指令碼結束代碼 (包括3010) 沒有任何作用。
- 輸出
-
所有任務都會將日誌檔案條目寫入
agent.log檔案。executeScript任務執行之指令碼的其他輸出會分別儲存在動態命名的資料夾中，如下所示：%LocalAppData%\Temp\EC2Launch#########\outputfilename.ext輸出檔案的確切路徑包含在
agent.log檔案中，例如：Program file is created at: C:\Windows\system32\config\systemprofile\AppData\Local\Temp\EC2Launch123456789\UserScript.ps1 Output file is created at: C:\Windows\system32\config\systemprofile\AppData\Local\Temp\EC2Launch123456789\Output.tmp Error file is created at: C:\Windows\system32\config\systemprofile\AppData\Local\Temp\EC2Launch123456789\Err.tmpexecuteScript任務的輸出檔案UserScript.ext-
包含
executeScript任務執行的指令碼。檔案的副檔名取決於您在executeScript任務的type參數中指定的指令碼類型，如下所示：-
如果類型為
batch，則檔案副檔名為.bat。 -
如果類型為
powershell，則檔案副檔名為.ps1。
-
Output.tmp-
包含
executeScript任務執行之指令碼的執行期輸出。 Err.tmp-
包含
executeScript任務執行之指令碼的執行期錯誤訊息。
- 範例
-
下列範例示範如何使用
executeScript任務執行內嵌指令碼。範例 1：Hello World 輸出文字檔案
此範例顯示
executeScript執行 PowerShell 指令碼以在C:磁碟機上建立「Hello world」文字檔的工作。task: executeScript inputs: - frequency: always type: powershell runAs: admin content: |- New-Item -Path 'C:\PowerShellTest.txt' -ItemType File Set-Content 'C:\PowerShellTest.txt' "Hello world"範例 2：執行兩個指令碼
此範例顯示
executeScript任務可以執行多個指令碼，而指令碼類型不一定需要相符。第一個指令碼 (
type: powershell) 會將執行個體上目前執行的程序摘要寫入位於C:磁碟機上的文字檔案。第二個指令碼 (
batch) 會將系統資訊寫入Output.tmp檔案。task: executeScript inputs: - frequency: always type: powershell content: | Get-Process | Out-File -FilePath C:\Process.txt runAs: localSystem - frequency: always type: batch content: | systeminfo範例 3：具有重新啟動功能的等冪系統組態
此範例顯示
executeScript任務，其執行等冪指令碼以執行下列系統組態，並在每個步驟之間重新啟動：-
重新命名電腦。
-
將電腦加入網域。
-
啟用 Telnet。
該指令碼確保每個操作只執行一次。這可以防止重新啟動循環，並讓指令碼具有等冪性。
task: executeScript inputs: - frequency: always type: powershell runAs: localSystem content: |- $name = $env:ComputerName if ($name -ne $desiredName) { Rename-Computer -NewName $desiredName exit 3010 } $domain = Get-ADDomain if ($domain -ne $desiredDomain) { Add-Computer -DomainName $desiredDomain exit 3010 } $telnet = Get-WindowsFeature -Name Telnet-Client if (-not $telnet.Installed) { Install-WindowsFeature -Name "Telnet-Client" exit 3010 } -
extendRootPartition
延伸根磁碟區以使用磁碟上的所有可用空間。
Frequency — 一次
AllowedStages — [Boot]
Inputs — 無
範例
task: extendRootPartition
initializeVolume
初始化連接到執行個體的空白磁碟區，以便啟動和分割這些磁碟區。如果啟動代理程式偵測到磁碟區並非空白，就會略過初始化。如果磁碟區的前 4 KiB 空白，或磁碟區沒有 Windows 可辨識的磁碟機配置
不論磁碟機是否已經初始化，在此任務執行時永遠都會套用 letter 輸入參數。
initializeVolume 任務會執行下列動作。
-
將磁碟屬性
offline和readonly設為 false。 -
建立分割區。如果未在
partition輸入參數中指定分割區類型，會套用下列預設值：-
如果磁碟大小小於 2 TB，請將分割區類型設為
MBR。 -
如果磁碟大小大於等於 2 TB，請將分割區類型設為
GPT。
-
-
將磁碟區格式化為 NTFS。
-
將磁碟區標籤設定如下：
-
如果有指定，請使用
name輸入參數的值。 -
如果磁碟區為暫時性，且未指定名稱，請將磁碟區標籤設為
Temporary Storage Z。
-
-
如果磁碟區為暫時性 (SSD 或 HDD，而非 Amazon EBS)，請在磁碟區的根目錄建立
Important.txt檔案，其中包含下列內容：This is an 'Instance Store' disk and is provided at no additional charge. *This disk offers increased performance since it is local to the host *The number of Instance Store disks available to an instance vary by instance type *DATA ON THIS DRIVE WILL BE LOST IN CASES OF IMPAIRMENT OR STOPPING THE INSTANCE. PLEASE ENSURE THAT ANY IMPORTANT DATA IS BACKED UP FREQUENTLY For more information, please refer to: Amazon EC2 執行個體存放區. -
將磁碟機代號設定為
letter輸入參數中指定的值。
階段：您可以在 PostReady 和 UserData 階段執行 initializeVolume 任務。
頻率：始終。
- 輸入
-
您可以設定執行期參數，如下所示：
- devices (映射清單)
-
(視情況而定) 啟動代理程式初始化之每個裝置的組態。
initialize輸入參數設為devices時，此為必要項目。-
device (字串，必要) – 在建立執行個體期間識別裝置。例如，
xvdb、xvdf或\dev\nvme0n1。 -
letter (字串，選用) – 一個字元。要指派的磁碟機代號。
-
name (字串，選用) – 要指派的磁碟區名稱。
-
partition (字串，選用) – 為要建立的分割區類型指定下列任一個值，或根據磁碟區大小讓啟動代理程式設定預設值：
-
MBR
-
GPT
-
-
- initialize (字串)
-
(必要) 僅指定下列其中一個值：
-
all -
devices
-
- 範例
-
下列範例說明
initializeVolume任務的輸入組態範例。範例 1：在執行個體上初始化兩個磁碟區
此範例說明在執行個體上初始化兩個次要磁碟區的
initializeVolume任務。範例中的裝置DataVolume2為暫時性。task: initializeVolume inputs: initialize: devices devices: - device: xvdb name: DataVolume1 letter: D partition: mbr - device: /dev/nvme0n1 name: DataVolume2 letter: E partition: gpt
範例 2：初始化連接至執行個體的 EBS 磁碟區
此範例說明 initializeVolume 任務，這會初始化所有連接至執行個體的空白 EBS 磁碟區。
task: initializeVolume inputs: initialize: all
optimizeEna
根據目前的執行個體類型最佳化 ENA 設定；可能會將執行個體重新開機。
Frequency — 永遠
AllowedStages — [PostReady, UserData]
Inputs — 無
範例
task: optimizeEna
setAdminAccount
為在本機電腦上建立的預設管理員帳戶設定屬性。
Frequency — 一次
AllowedStages — [PreReady]
Inputs —
name：(字串) 管理員帳戶的名稱
password：(映射)
type：(字符) 策略來設置密碼，無論是 static、random 或 doNothing
data：(字串) 儲存資料，如果 type 欄位是靜態的話
範例
task: setAdminAccount inputs: name: Administrator password: type: random
setDnsSuffix
將 DNS 尾碼新增至搜尋尾碼清單。只有不存在的尾碼才會加入到清單中。如需啟動代理程式如何設定 DNS 尾碼的詳細資訊，請參閱。設定 DNS 尾碼
Frequency – 始終
AllowedStages — [PreReady]
Inputs —
suffixes：(字串清單) 一或多個有效 DNS 尾碼清單；有效的替代變數為 $REGION 和 $AZ
範例
task: setDnsSuffix inputs: suffixes: - $REGION.ec2-utilities.amazonaws.com
setHostName
將電腦的主機名稱設定為自訂字串，或者如果 hostName 未指定，則設定私有 IPv4 地址。
Frequency — 永遠
AllowedStages — [PostReady, UserData]
Inputs —
hostName：(字串) 選擇性的主機名稱，必須格式化如下。
-
必須等於或少於 15 個字元
-
必須只包含英數字元 (a-z、A-Z、0-9) 和連字號 (-) 字元。
-
不得完全由數字字元組成。
reboot：(布林值) 表示當主機名被更改時是否允許重新啟動
範例
task: setHostName inputs: reboot: true
setWallpaper
除了 Default User 之外，在每個現有使用者的啟動資料夾中建立 setwallpaper.lnk 捷徑檔案。使用者在執行個體啟動後第一次登入時，此捷徑檔案會執行。這會使用顯示執行個體屬性的自訂桌布，設定執行個體。
捷徑檔案路徑為：
$env:SystemDrive/Users/<user>/AppData/Roaming/Microsoft/Windows/Start Menu/Programs/Startup/setwallpaper.lnk
注意
移除 setWallpaper 任務時，不會刪除此捷徑檔案。如需詳細資訊，請參閱 setWallpaper 任務未啟用，但桌布會在重新啟動時重設。
階段：您可以在 PreReady 和 UserData 階段設定桌布。
頻率：always
桌布組態
您可以使用下列設定來配置桌布。
- 輸入
-
您提供的輸入參數，以及可以設定桌布的屬性：
- 屬性 (字串清單)
-
(選用) 您可以將以下一個或多個屬性新增至桌布：
-
architecture -
availabilityZone -
hostName -
instanceId -
instanceSize -
memory -
network -
privateIpAddress -
publicIpAddress
-
- instanceTags
-
(選用) 您可以使用下列其中一個選項來進行此設定。
-
AllTags(字串) — 將所有實體標籤新增至桌布。
instanceTags: AllTags -
instanceTags (字串清單) – 指定要新增至桌布的執行個體標籤名稱清單。例如：
instanceTags: - Tag 1 - Tag 2
-
- 路徑 (字串)
-
(必要) 要用於桌布圖片的本機 .jpg 格式圖片檔案的檔案名稱路徑。
範例
下列範例顯示設定桌布背景圖片檔案路徑的桌布組態輸入，以及名為 Tag 1 和 Tag 2 的執行個體標籤，以及包含執行個體的主機名稱、執行個體 ID 及私有和公有 IP 地址的屬性。
task: setWallpaper inputs: path: C:\ProgramData\Amazon\EC2Launch\wallpaper\Ec2Wallpaper.jpg attributes: - hostName - instanceId - privateIpAddress - publicIpAddress instanceTags: - Tag 1 - Tag 2
注意
您必須在中繼資料中啟用標籤，才能在桌布上顯示標籤。如需有關執行個體標籤和中繼資料的詳細資訊，請參閱 使用執行個體中繼資料中的執行個體標籤。
startSsm
依照 Sysprep 開始 Systems Manager (SSM) 服務。
Frequency — 永遠
AllowedStages — [PostReady, UserData]
Inputs — 無
範例
task: startSsm
sysprep
重設服務狀態、更新 unattend.xml、停用 RDP，以及執行 Sysprep。只有在所有其他任務完成後才會執行此任務。
Frequency — 一次
AllowedStages — [UserData]
Inputs —
clean：(布林值）在執行 Sysprep 之前清除執行個體日誌
shutdown：(布林值）在執行 Sysprep 後關閉執行個體
範例
task: sysprep inputs: clean: true shutdown: true
writeFile
將檔案寫入目的地。
Frequency — 請參閱 Inputs
AllowedStages — [PostReady, UserData]
Inputs —
frequency：(字符) 其中一個 once 或 always
destination：(字符) 要寫入內容的路徑
content：(字符) 要寫入文本的目的地
範例
task: writeFile inputs: - frequency: once destination: C:\Users\Administrator\Desktop\booted.txt content: Windows Has Booted
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 的詳細資訊，請參閱 建立自訂 Windows AMI。
