EC2Launch v2 設定ダイアログボックスを使用して設定を変更する EC2Launch v2 のディレクトリ構造 CLI を使用した EC2Launch v2 の設定 EC2Launch v2 タスクの設定 EC2Launch v2 の終了コードと再起動 EC2Launch v2 とSysprep

EC2Launch v2 の設定

このセクションでは、EC2Launch v2 の設定を構成する方法について説明します。

トピックは以下のとおりです。

EC2Launch v2 設定ダイアログボックスを使用して設定を変更する
EC2Launch v2 のディレクトリ構造
CLI を使用した EC2Launch v2 の設定
EC2Launch v2 タスクの設定
EC2Launch v2 の終了コードと再起動
EC2Launch v2 とSysprep

EC2Launch v2 設定ダイアログボックスを使用して設定を変更する

次の手順では、EC2Launch v2 設定ダイアログボックスを使用して、設定を有効または無効にする方法を示します。

注記

agent-config.yml ファイルでカスタムタスクを正しく設定した場合、Amazon EC2Launch 設定ダイアログボックスを開こうとすると、エラーが発生します。スキーマの例については、「例：agent-config.yml」を参照してください。

Windows インスタンスを起動して接続します。
[スタート] メニューから、[すべてのプログラム] を選択し、[EC2Launch 設定] に移動します。
[EC2Launch 設定] ダイアログボックスの [全般] タブで、次の設定を有効または無効にすることができます。
1. コンピュータ名の設定
  
  この設定を有効にすると (デフォルトでは無効になっています)、ブートごとに現在のホスト名が希望するホスト名と比較されます。ホスト名が一致しない場合、ホスト名はリセットされ、システムは必要に応じて再起動して、新しいホスト名を取得します。カスタムホスト名が指定されていない場合は、16 進形式のプライベート IPv4 アドレスを使用して生成されます。例えば、ip-AC1F4E6 などです。既存のホスト名が変更されないようにするには、この設定を有効にしないでください。
2. ブートボリュームの拡張
  
  この設定は、Disk 0/Volume 0 を動的に拡張し、未使用の領域を含めます。独自のサイズを指定したルートデバイスボリュームからインスタンスを起動するときに便利です。
3. 管理者アカウントの設定
  
  有効にすると、ローカルマシンに作成される管理者アカウントのユーザー名とパスワードの属性を設定できます。この機能を有効にしないと、Sysprep 後に管理者アカウントがシステムに作成されません。adminPasswordtype が Specify である場合のみ、adminPasswordにパスワードを入力します。
  
  パスワードの種類は次のとおりです。
  1. Random
    
    EC2Launch は、ユーザーのキーを使用してパスワードを生成し、暗号化します。この設定はインスタンス起動後に無効になるため、インスタンスを再起動したり、停止して起動した場合でもパスワードは保持されます。
  2. Specify
    
    EC2Launch は、adminPassword で指定したパスワードを使用します。指定したパスワードがシステム要件を満たさない場合は、代わりに EC2Launch によってランダムなパスワードが生成されます。このパスワードはクリアテキストとして agent-config.yml に保存され、Sysprep で管理者パスワードが設定されると削除されます。EC2Launch は、ユーザーのキーを使用してパスワードを暗号化します。
  3. Do not set
    
    EC2Launch は、unattend.xml ファイルで指定したパスワードを使用します。unattend.xml でパスワードを指定しないと、管理者アカウントは無効になります。
4. SSM サービスの開始
  
  選択された Systems Manager サービスの起動が Sysprep の後に有効化されます。EC2Launch v2 は前述のすべてのタスクを実行し、SSM Agent は Run Command やステートマネージャーなどの Systems Manager 機能に対するリクエストを処理します。
  
  Run Command を使用して既存のインスタンスをアップグレードすることで、最新バージョンの EC2Launch v2 サービスや SSM Agent を使用できるようになります。詳細については、AWS Systems Manager ユーザーガイドの「Run Command を使用した SSM Agent の更新」を参照してください。
5. ENA の最適化
  
  選択すると、ENA の受信側のスケーリングおよび受信キューの深さの設定を AWS 用に最適化するように ENA 設定が設定されます。詳細については、RSS CPU アフィニティを設定するを参照してください。
6. SSH の有効化
  
  この設定では、より新しいバージョンの Windows で OpenSSH を有効にし、リモートシステム管理を許可できます。
7. ジャンボフレームの有効化
  
  ジャンボフレームを有効にする場合は、これを選択します。ジャンボフレームは、ネットワーク通信に意図しない影響を及ぼす可能性があるため、ジャンボフレームがシステムに与える影響をよく理解した上で有効にしてください。ジャンボフレームの詳細については、「ジャンボフレーム (9001 MTU)」を参照してください。
8. イメージングの準備
  
  EC2 インスタンスのシャットダウンに Sysprep を使用するかしないかを選択します。EC2Launch v2 で Sysprep を実行する場合は、[Sysprep でシャットダウン] を選択します。
[DNS サフィックス] タブで、完全修飾ドメイン名を指定せずに、EC2 で実行されているサーバーの DNS 解決用に DNS サフィックスのリストを追加するかどうかを選択できます。DNS サフィックスには、$REGION 変数と $AZ 変数を含めることができます。まだ存在しないサフィックスのみがリストに追加されます。
[壁紙] タブでは、背景画像を使用してインスタンスの壁紙を設定し、表示する壁紙のインスタンスの詳細を指定できます。Amazon EC2 は、ログインするたびに詳細を生成します。

次のコントロールで壁紙を設定できます。
- [壁紙にインスタンスの詳細を表示] - このチェックボックスは、壁紙のインスタンス詳細表示を有効または無効にします。
- [画像パス (.jpg)] - 壁紙の背景として使用する画像へのパスを指定します。
- [壁紙に表示する属性を選択] - 壁紙に表示するインスタンスの詳細のチェックボックスを選択します。壁紙からインスタンスの詳細を削除するには、以前に選択したチェックボックスをオフにします。
- [壁紙にインスタンスタグを表示] - 壁紙にインスタンスタグを表示するには、次のいずれかの設定を選択します。
  - [なし] - 壁紙にインスタンスタグを表示しないでください。
  - [すべて表示] - 壁紙にすべてのインスタンスタグを表示します。
  - [フィルター済みを表示] - 指定したインスタンスタグを壁紙に表示します。この設定を選択すると、[インスタンスタグフィルター] ボックスが表示され、壁紙に表示するインスタンスタグを追加できます。
    
    注記
    壁紙にタグを表示するには、メタデータのタグを有効にする必要があります。インスタンスのタグおよびメタデータの詳細については、「インスタンスメタデータ内のインスタンスタグの使用」を参照してください。
[ボリューム] タブで、インスタンスにアタッチされているボリュームを初期化するかどうかを選択します。有効にすると、追加ボリュームのドライブ文字が設定され、使用可能な領域を使用するようにドライブ文字が拡張されます。[すべて] を選択すると、すべてのストレージボリュームが初期化されます。[デバイス] を選択すると、リストで指定されているデバイスのみが初期化されます。初期化するデバイスごとに、デバイスを入力する必要があります。EC2 コンソールにリストされているデバイス (xvdb や /dev/nvme0n1 など) を使用します。ドロップダウンリストには、インスタンスにアタッチされているストレージボリュームが表示されます。インスタンスにアタッチされていないデバイスを入力するには、テキストフィールドに入力します。

[名前]、[文字]、[パーティション] は、オプションのフィールドです。[パーティション] に値を指定しないと、2 TB より大きいストレージボリュームは GPT パーティションタイプで初期化され、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 - EC2Launch の Windows イベントログ記録をサポートするための DLL。
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 - サービスの状態データ

実行するタスクを決定するためにサービスで使用する状態がここに保存されます。Sysprep 後にサービスが実行済みであるかどうかを示す .run-once ファイルがあり、これにより、頻度が 1 回のタスクは次の実行でスキップされます。このサブディレクトリには、各タスクのステータスを追跡するための previous-state.json と state.json があります。
sysprep - Sysprep

このディレクトリ内のファイルを使用して、再利用可能なカスタマイズされた Windows AMI の作成時に Sysprep で実行するオペレーションを決定します。

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

agent-config.yml を指定された形式 (JSON または YAML) で印刷します。書式が指定されていない場合、agent-config.yml は以前に指定された書式で印刷されます。

例


ec2launch get-agent-config -f json

例 2

以下の PowerShell コマンドは、agent-config ファイルを JSON 形式で編集および保存する方法を示しています。


$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

このタスクの主な目的は、次回実行時にエージェントをリセットすることです。そのために、resetコマンドは EC2Launch v2 EC2Launch のすべてのエージェント状態データをローカルディレクトリから削除します (を参照) 。EC2Launch v2 のディレクトリ構造リセットすると、オプションでサービスログと Sysprep ログが削除されます。

スクリプトの動作は、エージェントがスクリプトを実行するモード (インラインかデタッチモード) によって異なります。

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

注記
インラインスクリプトが reset または sysprep コマンドを発行すると、すぐに実行され、エージェントがリセットされます。現在のタスクが終了すると、エージェントはそれ以上のタスクを実行せずにシャットダウンします。
例えば、コマンドを発行するタスクの後にタスク (ユーザーデータの実行後にデフォルトで含まれる) が続く場合、その startSsm タスクは実行されず、Systems Manager サービスは開始されません。
デタッチ済み: 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 — エージェントが実行されておらず、最後に既知の実行の状態が不明です。これは、次のいずれかの 1 つを意味します。
- 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 エージェントはスクリプトを 1 つずつ実行します (detach: false)。これはデフォルトの設定です。

注記
インラインスクリプトが reset または sysprep コマンドを発行すると、すぐに実行され、エージェントがリセットされます。現在のタスクが終了すると、エージェントはそれ以上のタスクを実行せずにシャットダウンします。
例えば、コマンドを発行するタスクの後にタスク (ユーザーデータの実行後にデフォルトで含まれる) が続く場合、その startSsm タスクは実行されず、Systems Manager サービスは開始されません。
デタッチ済み: 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 ファイル) に新しい壁紙を設定し、選択したインスタンスの詳細を表示します。

Syntax


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

入力

パラメータ

--allowed-tags [tag-name-1, tag-name-n]: (オプション) 壁紙に表示するインスタンスタグ名の Base64 エンコードされた JSON 配列。このタグまたは --all-tags を使用できますが、両方は使用できません。
--attributes attribute-string-1, attribute-string-n: (オプション) 壁紙に設定を適用する wallpaper 属性文字列のコンマ区切りのリスト。
[--path | -p] path-string: (必須) wallpaper 背景画像ファイルのパスを指定します。

Flags

--all-tags: (オプション) 壁紙にすべてのインスタンスタグを表示します。このタグまたは --allowed-tags を使用できますが、両方は使用できません。
[--help | -h]: wallpaper コマンドに関するヘルプを表示します。

EC2Launch v2 タスクの設定

このセクションでは、agent-config.ymlとユーザーデータの設定スキーマ、タスク、詳細、および例が含まれます。

タスクと例

スキーマ：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	ユーザーデータタスクは、エージェント設定ファイルの `PostReady` ステージの前に実行されます。システムマネージャーエージェントを開始する前にユーザーデータを実行します (EC2Launch v1 および EC2Config と同じ動作)。*	EC2Launch v2 バージョン 2.0.1245
1.0	廃止されます。ユーザーデータタスクは、エージェント設定ファイルの `PostReady` ステージ後に実行されます。これには EC2Launch v1 との下位互換性はありません。システムマネージャーエージェントの起動とユーザーデータタスクの間の競合状態による影響を受けます。	EC2Launch v2 バージョン 2.0.0

* デフォルトの agent-config.yml ファイルで使用した場合。

タスク定義

各タスクには、独自のプロパティと要件があります。詳細については、ドキュメントに含める個々のタスクを参照してください。

タスク

activateWindows
enableJumboFrames
enableOpenSsh
executeProgram
executeScript
extendRootPartition
initializeVolume
optimizeEna
setAdminAccount
setDnsSuffix
setHostName
setWallpaper
startSsm
sysprep
writeFile

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 タスクを実行できます。

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

入力

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

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 タスクを実行できます。

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

入力

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

frequency (文字列)

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

once
always

type (文字列)

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

batch
powershell

arguments (文字列のリスト)

(オプション) シェルに渡す文字列引数のリスト。このパラメータは、type: batch ではサポートされません。

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: Amazon 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 サフィックスの設定方法の詳細については、「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

注記

壁紙にタグを表示するには、メタデータのタグを有効にする必要があります。インスタンスのタグおよびメタデータの詳細については、「インスタンスメタデータ内のインスタンスタグの使用」を参照してください。

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

EC2Launch v2 の終了コードと再起動

EC2Launch v2 を使用して、スクリプトによる終了コードの処理方法を定義できます。デフォルトでは、スクリプトで最後に実行されたコマンドの終了コードは、スクリプト全体の終了コードとしてレポートされます。例えば、スクリプトに 3 つのコマンドが含まれており、最初のコマンドが失敗したが、次のコマンドが成功した場合、実行ステータスは、最後のコマンドが成功したために success として報告されます。

スクリプトでインスタンスを再起動する場合、再起動がスクリプトの最後のステップで実行されるようになっていても、そのスクリプト内で exit 3010 を指定する必要があります。exit 3010 は、インスタンスを再起動し、さらに 3010 以外の終了コードが返されるか再起動が最大回数に達するまで、スクリプトを再度呼び出すように EC2Launch v2 に指示します。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 を作成する」を参照してください。

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

サブスクライブ

のトラブルシューティング

EC2Launch v2 の設定

トピックは以下のとおりです。

EC2Launch v2 設定ダイアログボックスを使用して設定を変更する

注記

注記

EC2Launch v2 のディレクトリ構造

注記

CLI を使用した EC2Launch v2 の設定

コマンド

collect-logs

get-agent-config

list-volumes

reset

注記

注記

run

status

sysprep

注記

注記

validate

version

壁紙

Syntax

入力

パラメータ

Flags

EC2Launch v2 タスクの設定

タスクと例

スキーマ：agent-config.yml

ドキュメント構造: agent-config.yml

例：agent-config.yml

スキーマ：ユーザーデータ

注記

文書構造: ユーザーデータ

例: ユーザーデータ

注記

変更ログ: ユーザーデータ

タスク定義

タスク

activateWindows

enableJumboFrames

enableOpenSsh

executeProgram

executeProgram タスクの出力ファイル

例 1: 1 つの引数を使用する設定実行可能ファイル

例 2: 2 つの引数を使用する VLC 実行可能ファイル

executeScript

注記

注記

注記

executeScript タスクの出力ファイル

例 1: Hello world 出力テキストファイル

例 2: 2 つのスクリプトを実行する

例 3: 再起動を伴うべき等システム設定

extendRootPartition

initializeVolume

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

例 2: インスタンスにアタッチされた EBS ボリュームを初期化

optimizeEna

setAdminAccount

setDnsSuffix

setHostName

setWallpaper

注記

壁紙設定

例

注記

startSsm

sysprep

writeFile

EC2Launch v2 の終了コードと再起動

EC2Launch v2 とSysprep

スキーマ：`agent-config.yml`

例：`agent-config.yml`

`executeProgram` タスクの出力ファイル

`executeScript` タスクの出力ファイル