EC2Launch v2 啟動任務的任務定義 - Amazon Elastic Compute Cloud
activateWindows enableJumboFrames enableOpenSsh executeProgramexecuteScriptextendRootPartition initializeVolumeoptimizeEna setAdminAccountsetDnsSuffix setHostName setWallpaper startSsmsysprepwriteFile

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

EC2Launch v2 啟動任務的任務定義

EC2Launch v2 在啟動或統計期間執行的每個任務都有自己的屬性和要求集。任務詳細資訊包括任務執行頻率的設定 – 一次或一律、其執行的代理程式開機程序階段、語法和YAML文件範例。如需詳細資訊，請檢閱此參考中顯示的任務詳細資訊。

activateWindows

針對一組 AWS KMS 伺服器啟用 Windows。如果偵測到執行個體為 Bring-Your-Own-License （BYOL），則會略過啟用。

Frequency — 一次

AllowedStages — [PreReady]

Inputs —

activation：(映射)

type：(字串) 要使用的啟動類型，設定為 amazon

範例

task: activateWindows
  inputs:
    activation:
    type: amazon

enableJumboFrames

啟用 Jumbo Frames，這會增加網路轉接器的最大傳輸單位 （MTU）。如需詳細資訊，請參閱大型影格 （9001MTU）。

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 任務。

頻率：可設定，請參閱輸入。

輸入

本節包含要執行之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.tmp
executeProgram 任務的輸出檔案
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 任務。

頻率：可設定，請參閱輸入。

輸入

本節包含要執行之executeScript任務的一或多個指令碼 （輸入）。每個輸入可以包含下列可設定設定：

頻率 (字串)

(必要) 僅指定下列其中一個值：

  • once

  • always

類型 (字串)

(必要) 僅指定下列其中一個值：

  • batch

  • powershell

引數 (字串清單)

（選用） 要傳遞至 Shell 的字串引數清單 （而非指令碼PowerShell ）。type: batch 不支援此參數。如果未傳遞任何引數，EC2Launchv2 預設會新增下列引數：-ExecutionPolicy Unrestricted。

內容 (字串)

(必要) 指令碼內容。

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.tmp
executeScript 任務的輸出檔案
UserScript.ext

包含 executeScript 任務執行的指令碼。檔案的副檔名取決於您在 executeScript 任務的 type 參數中指定的指令碼類型，如下所示：

  • 如果類型為 batch，則檔案副檔名為 .bat。

  • 如果類型為 powershell，則檔案副檔名為 .ps1。

Output.tmp

包含 executeScript 任務執行之指令碼的執行期輸出。

Err.tmp

包含 executeScript 任務執行之指令碼的執行期錯誤訊息。

範例

下列範例示範如何使用 executeScript 任務執行內嵌指令碼。

範例 1：Hello World 輸出文字檔案

此範例顯示執行 PowerShell 指令碼以在C:磁碟機上建立「Hello world」文字檔案executeScript的任務。

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: 適用於 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磁碟區

此範例顯示初始化連接至執行個體之所有空白EBS磁碟區initializeVolume的任務。

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 Suffix for EC2 Windows 啟動代理程式。

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
注意

您必須在中繼資料中啟用標籤，才能在桌布上顯示標籤。如需有關執行個體標籤和中繼資料的詳細資訊，請參閱 使用執行個體中繼資料檢視 EC2 執行個體的標籤。

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