EC2Launch v2 起動タスクのタスク定義 - Amazon Elastic Compute Cloud
activateWindows enableJumboFrames enableOpenSsh executeProgramexecuteScriptextendRootPartition initializeVolumeoptimizeEna setAdminAccountsetDnsSuffix setHostName setWallpaper startSsmsysprepwriteFile

EC2Launch v2 起動タスクのタスク定義

EC2Launch v2 が起動時に実行する各タスクには、独自のプロパティと要件のセットがあります。タスクの詳細には、タスクの実行頻度 (1 回のみ、または毎回) に関する設定、タスクが実行されるエージェントのブートプロセスのステージ、構文、および YAML ドキュメントの例が含まれます。詳細については、このリファレンスに示されているタスクの詳細を確認してください。

activateWindows

AWS KMS サーバーのセットに対して Windows をアクティブ化します。インスタンスが Bring-Your-Own-License (BYOL) であることが検出された場合、アクティベーションはスキップされます。

Frequency - 1 回

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 - 1 回

AllowedStages - [PreReady, UserData]

Inputs - なし

例

次の例は、インスタンスで OpenSSH を有効にし、インスタンスのパブリックキーを認証済みキーフォルダーに追加する方法を示しています。この設定は、Windows Server 2019 以降のバージョンを実行しているインスタンスでのみ機能します。

task: enableOpenSsh

executeProgram

オプションの引数と指定された頻度でプログラムを実行します。

[ステージ]: PreReady、PostReady、および UserData のステージ中に executeProgram タスクを実行できます。

[周波数]: 設定可能です。「入力」を参照してください。

入力

このセクションには、executeProgram タスクを実行するための 1 つ以上のプログラム (入力) が含まれます。各入力には、次の設定を含めることができます:

frequency (文字列)

(必須) 次の値のいずれかを正確に指定します。

  • once

  • always

パス (文字列)

(必須) 実行する実行可能ファイルのファイルパス。

arguments (文字列のリスト)

(オプション) 入力としてプログラムに提供する引数のカンマ区切りのリスト。

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: 1 つの引数を使用する設定実行可能ファイル

この例は、設定実行可能ファイルを Quiet モードで実行する executeProgram タスクを示しています。

task: executeProgram
  inputs:
    - frequency: always
      path: C:\Users\Administrator\Desktop\setup.exe
      arguments: ['-quiet']
例 2: 2 つの引数を使用する VLC 実行可能ファイル

この例は、入力パラメータとして渡された 2 つの引数を使用して VLC 実行可能ファイルを実行する executeProgram タスクを示しています。

task: executeProgram
  inputs:
    - frequency: always
      path: C:\vlc-3.0.11-win64.exe 
      arguments: ['/L=1033','/S']
      runAs: localSystem

executeScript

オプションの引数と指定された頻度でスクリプトを実行します。スクリプトの動作は、エージェントがスクリプトを実行するモード (インラインかデタッチモード) によって異なります。

インライン (デフォルト)

EC2Launch v2 エージェントはスクリプトを 1 つずつ実行します (detach: false)。これはデフォルトの設定です。

注記

インラインスクリプトが reset または sysprep コマンドを発行すると、すぐに実行され、エージェントがリセットされます。現在のタスクが終了すると、エージェントはそれ以上のタスクを実行せずにシャットダウンします。

例えば、コマンドを発行するタスクの後にタスク (ユーザーデータの実行後にデフォルトで含まれる) が続く場合、その startSsm タスクは実行されず、Systems Manager サービスは開始されません。

デタッチ済み

EC2Launch v2 エージェントは、他のタスクと同時にスクリプトを実行します (detach: true)。

注記

デタッチされたスクリプトが reset または sysprep コマンドを発行すると、それらのコマンドはエージェントが終了するのを待ってから実行します。ExecuteScript の後のタスクは引き続き実行されます。

[ステージ]: PreReady、PostReady、および UserData のステージ中に executeScript タスクを実行できます。

[周波数]: 設定可能です。「入力」を参照してください。

入力

このセクションには、executeScript タスクを実行するための 1 つ以上のスクリプト (入力) が含まれます。各入力には、次の設定を含めることができます:

frequency (文字列)

(必須) 次の値のいずれかを正確に指定します。

  • once

  • always

type (文字列)

(必須) 次の値のいずれかを正確に指定します。

  • batch

  • powershell

arguments (文字列のリスト)

(オプション) (PowerShell スクリプトではなく) シェルに渡す文字列引数のリスト。このパラメータは、type: batch ではサポートされません。引数が渡されない場合、EC2Launch v2 はデフォルトで次の引数を追加します: -ExecutionPolicy Unrestricted

content (文字列)

(必須) インラインスクリプトのコンテンツ。

runAs (文字列)

(必須) 次の値のいずれかを正確に指定します。

  • admin

  • localSystem

デタッチ (ブール値)

(オプション) EC2Launch v2 エージェントは、スクリプトを一度に 1 つずつ実行するようデフォルトで設定されています (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: 2 つのスクリプトを実行する

この例は、executeScript タスクが複数のスクリプトを実行できること、およびスクリプトの種類が必ずしも一致する必要がないことを示しています。

最初のスクリプト (type: powershell) は、インスタンス上で現在実行されているプロセスの概要を C: ドライブ上のテキストファイルに書き込みます。

2 番目のスクリプト (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 を有効にします。

スクリプトは、各オペレーションが 1 回だけ実行されるようにします。これにより、再起動ループが防止され、スクリプトがべき等になります。

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 - 1 回

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 に設定します。

  • ボリュームがエフェメラル (Amazon EBS ではなく SSD または HDD) である場合は、ボリュームのルートに次の内容を持つ 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 入力パラメータで指定された値に設定します。

Stages:: PostReady および UserData のステージ中に initializeVolume タスクを実行できます。

Frequency: 常時。

入力

ランタイムパラメータは次のように設定できます。

devices (マップのリスト)

(条件付き) 起動エージェントが初期化する各デバイスの設定です。initialize 入力パラメータが devices に設定されている場合に必須です。

  • device (文字列、必須) — インスタンスの作成中にデバイスを識別します。例えば、xvdb、xvdf、または \dev\nvme0n1 などです。

  • letter (文字列、オプション) — 1 文字です。割り当てるドライブ文字です。

  • name (文字列、オプション) — 割り当てるボリューム名です。

  • partition (文字列、オプション) — 作成するパーティションのタイプに次のいずれかの値を指定するか、ボリュームサイズに基づいて起動エージェントをデフォルトにします。

    • mbr

    • gpt

initialize (文字列)

(必須) 次の値のいずれかを正確に指定します。

  • all

  • devices

例

以下は、initializeVolume タスクの入力構成の例です。

例 1: インスタンス上の 2 つのボリュームを初期化

こちらは、インスタンス上の 2 つのセカンダリボリュームを初期化する 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 - 1 回

AllowedStages - [PreReady]

Inputs -

name: (文字列) 管理者アカウントの名前

password: (マップ)

type: (文字列) パスワードを設定する戦略 (static、random、doNothing のいずれかとして設定)

data: (文字列) type フィールドが静的な場合にデータを保存

例

task: setAdminAccount
inputs:
  name: Administrator
  password:
  type: random

setDnsSuffix

検索サフィックスのリストに DNS サフィックスを追加します。まだ存在しないサフィックスのみがリストに追加されます。起動エージェントによる DNS サフィックスの設定方法の詳細については、「EC2 Windows 起動エージェントの DNS サフィックスを設定する」を参照してください。

Frequency - 常に

AllowedStages - [PreReady]

Inputs -

suffixes: (文字列のリスト) 1 つ以上の有効な 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 タスクは有効になっていないものの、再起動時にウォールペーパーがリセットされる」を参照してください。

Stages: PreReady および UserData の各ステージ中にウォールペーパーを設定できます。

頻度: always

壁紙設定

次の設定を使用して壁紙を設定できます。

入力

指定した入力パラメータと、壁紙を設定するために設定できる属性:

属性 (文字列のリスト)

(オプション) 壁紙には、次の属性を 1 つ以上追加できます。

  • architecture

  • availabilityZone

  • hostName

  • instanceId

  • instanceSize

  • memory

  • network

  • privateIpAddress

  • publicIpAddress

InstanceTags

(オプション) この設定には、次のオプションを 1 つだけ使用できます。

  • AllTags (文字列) - すべてのインスタンスタグを壁紙に追加します。

    instanceTags: AllTags

  • instanceTags (文字列のリスト) - 壁紙に追加するインスタンスタグ名のリストを指定します。例:

    instanceTags:
  - Tag 1
  - Tag 2
パス (文字列)

(必須) 壁紙画像に使用するローカル .jpg 形式の画像ファイルのファイル名パス。

例

次の例は、壁紙背景画像のファイルパス、Tag 1 および Tag 2 という名前のインスタンスタグ、およびインスタンスのホスト名、インスタンス ID、プライベート IP アドレスとパブリック 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 - 1 回

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