EC2Launch v2 エージェントの問題をトラブルシューティングする

このセクションでは、EC2Launch v2 での一般的なトラブルシューティングシナリオ、Windows イベントログの表示に関する情報、およびコンソールログの出力とメッセージについて説明します。

一般的なトラブルシューティングのシナリオ

このセクションでは、一般的なトラブルシューティングのシナリオと解決手順を示します。

サービスで壁紙を設定できない

サービスでユーザーデータを実行できない

考えられる原因: ユーザーデータを実行する前にサービスが失敗した可能性があります。

サービスはタスクを 1 回だけ実行する

サービスでタスクを実行できない

サービスはユーザーデータを複数回実行する

解決方法

ユーザーデータは、EC2Launch v1 と EC2Launch v2 では異なる方法で処理されます。persist が true に設定されている場合、EC2Launch v1 はユーザーデータをインスタンスでスケジュールされたタスクとして実行します。persist が false に設定されている場合、タスクが再起動して終了したり、実行中に中断された場合でも、タスクはスケジュールされません。

EC2Launch v2 は、ユーザーデータをエージェントタスクとして実行し、実行状態を追跡します。ユーザーデータがコンピュータの再起動を発行した場合、または実行中にユーザーデータが中断された場合、実行状態は pending として持続し、ユーザーデータは次回のインスタンスの起動時に再び実行されます。ユーザーデータスクリプトが複数回実行されないようにするには、スクリプトをべき等にします。

次のべき等スクリプト例では、コンピュータ名を設定し、ドメインに参加します。

<powershell>
  $name = $env:computername
  if ($name -ne $desiredName) {
	Rename-Computer -NewName $desiredName
  }
  $domain = Get-ADDomain
  if ($domain -ne $desiredDomain) 
  {
	Add-Computer -DomainName $desiredDomain
  }
  $telnet = Get-WindowsFeature -Name Telnet-Client
  if (-not $telnet.Installed)
  {
	Install-WindowsFeature -Name "Telnet-Client"
  }
</powershell>
<persist>false</persist>

EC2Launch v2 への移行後、EC2Launch v1 のスケジュールされたタスクが実行されない

解決方法

移行ツールは、EC2Launch v1 スクリプトにリンクされているスケジュールされたタスクを検出しないため、EC2Launch v2 のタスクは自動的にセットアップされません。タスクを設定するには、agent-config.yml ファイルを編集するか、EC2Launch v2 設定ダイアログボックスを使用します。例えば、インスタンスのタスクが InitializeDisks.ps1 を実行するようにスケジュールされている場合は、移行ツールを実行した後、EC2Launch v2 の設定ダイアログボックスで、初期化するボリュームを指定する必要があります。EC2Launch v2 設定ダイアログボックスを使用して設定を変更する の手順については、ステップ 6 を参照してください。

空ではない EBS ボリュームがサービスによって初期化される

解決方法

ボリュームが初期化される前に、EC2Launch v2 は、そのボリュームにデータがないこと確認します。ボリュームが空でない場合、初期化はスキップされます。空でないことが検出されたボリュームは初期化されません。ボリュームの最初の 4 KiB が空の場合、またはボリュームに Windows を認識できるドライブレイアウトがない場合、ボリュームは空と見なされます。Linux システムで初期化およびフォーマットされたボリュームには、Windows を認識できるドライブレイアウト (MBR や GPT など) がありません。したがって、それは空とみなされ、初期化されます。このデータを保持する場合、EC2Launch v2 による空ドライブの検出には頼らないでください。代わりに、EC2Launch v2 設定ダイアログボックス (ステップ 6 を参照) または agent-config.yml で、初期化するボリュームを指定します。

setWallpaper タスクは有効になっていないものの、再起動時にウォールペーパーがリセットされる

setWallpaper タスクは、既存の (Default User を除く) 各ユーザーのスタートアップフォルダ内に、ショートカットファイル setwallpaper.lnk を作成します。このショートカットファイルは、ユーザーがインスタンスの起動後に初めてログインしたときに実行されます。インスタンス属性を表示するカスタム壁紙があるインスタンスが設定されます。この setWallpaper タスクを削除しても、このショートカットファイルは削除されません。このファイルは手動で削除するか、スクリプトを使用して削除する必要があります。

ショートカットパスは次のとおりです。

$env:SystemDrive/Users/<user>/AppData/Roaming/Microsoft/Windows/Start Menu/Programs/Startup/setwallpaper.lnk

解決方法

このファイルを手動で削除するか、スクリプトを使用して削除します。

ショートカットファイルを削除する PowerShell スクリプトの例

foreach ($userDir in (Get-ChildItem "C:\Users" -Force -Directory).FullName)
{
	$startupPath = Join-Path $userDir -ChildPath "AppData\Roaming\Microsoft\Windows\Start Menu\Programs\Startup"
	if (Test-Path $startupPath)
	{
		$wallpaperSetupPath = Join-Path $startupPath -ChildPath "setwallpaper.lnk"
		if (Test-Path $wallpaperSetupPath)
		{
			Remove-Item $wallpaperSetupPath -Force -Confirm:$false
		}
	}
}

サービスは実行中ステータスでスタックしています

説明

EC2Launch v2 は、次のようなログ (agent.log) でブロックされます。

2022-02-24 08:08:58 Info: *****************************************************************************************
2022-02-24 08:08:58 Info: EC2Launch Service starting
2022-02-24 08:08:58 Info: Windows event custom log exists: Amazon EC2Launch
2022-02-24 08:08:58 Info: ACPI SPCR table not supported. Bailing Out
2022-02-24 08:08:58 Info: Serial port is in use. Waiting for Serial Port...
2022-02-24 08:09:00 Info: ACPI SPCR table not supported. Use default console port.
2022-02-24 08:09:02 Info: ACPI SPCR table not supported. Use default console port.
2022-02-24 08:09:04 Info: ACPI SPCR table not supported. Use default console port.
2022-02-24 08:09:06 Info: ACPI SPCR table not supported. Use default console port.

考えられる原因

SAC が有効化され、シリアルポートを使用しています。詳細については、「SAC を使用して Windows インスタンスをトラブルシューティングする」を参照してください。

解決方法

この問題を解決するには、以下の手順を実行します。

無効なagent-config.ymlは EC2Launch v2 設定ダイアログボックスが開くことを防止します

説明

EC2Launch v2 設定は、ダイアログボックスを開く前に agent-config.yml ファイルの解析を試みます。YAML 設定ファイルがサポートされているスキーマに準拠しない場合、ダイアログボックスに次のエラーが表示されます。

Unable to parse configuration file agent-config.yml. Review configuration file. Exiting application.

task:executeScript should be unique and only invoked once

説明

同じステージでタスクを繰り返すことはできません。

解決方法

一部のタスクは、executeScript と executeProgram などの配列として入力する必要があります。スクリプトを配列として書き込む方法の一例については、executeScriptを参照してください。

Windows イベントログ

EC2Launch v2 は、サービスの開始、Windows の準備完了、さらにタスクの成否などの重要なイベントに関する Windows イベントログを発行します。イベント識別子は、特定のイベントを一意に識別します。各イベントには、ステージ、タスク、レベル情報、説明が含まれます。イベント識別子を使用して、特定のイベントのトリガーを設定できます。

イベント識別子は、イベントに関する情報を提供し、いくつかのイベントを一意に識別します。イベント ID の最下位桁は、イベントの重大度を示します。

サービスの開始時または停止時に生成されるサービスに関するイベントには、1 桁のイベント識別子が含まれます。

EC2LaunchService.exe イベントのイベントメッセージは、Service: から始まります。EC2Launch.exe イベントのイベントメッセージは、Service: で始まるものではありません。

4 桁のイベント ID には、イベントのステージ、タスク、重大度に関する情報が含まれます。

イベント ID 形式

次の表に EC2Launch v2 でのイベント識別子の形式を示します。

表内の文字と数字は、次のイベントタイプと定義を表します。

イベント ID の例

イベント ID の例を次に示します。

Windows イベントログのスキーマ

EC2Launch v2 コンソールログ出力

このセクションには、サンプルの EC2Launch v2 コンソールログ出力が含まれており、EC2Launch v2 コンソールログエラーメッセージのうち、問題のトラブルシューティングに役立つものを一覧表示しています。インスタンスコンソール出力とそのアクセス方法の詳細については、「インスタンスコンソール出力」を参照してください。

EC2Launch v2 コンソールログ出力

以下に示しているのは、サンプルの EC2Launch v2 コンソールログ出力です。

2023/11/30 20:18:53Z: Windows sysprep configuration complete.
2023/11/30 20:18:57Z: Message: Waiting for access to metadata...
2023/11/30 20:18:57Z: Message: Meta-data is now available.
2023/11/30 20:18:57Z: AMI Origin Version: 2023.11.15
2023/11/30 20:18:57Z: AMI Origin Name: Windows_Server-2022-English-Full-Base
2023/11/30 20:18:58Z: OS: Microsoft Windows NT 10.0.20348
2023/11/30 20:18:58Z: OsVersion: 10.0
2023/11/30 20:18:58Z: OsProductName: Windows Server 2022 Datacenter
2023/11/30 20:18:58Z: OsBuildLabEx: 20348.1.amd64fre.fe_release.210507-1500
2023/11/30 20:18:58Z: OsCurrentBuild: 20348
2023/11/30 20:18:58Z: OsReleaseId: 2009
2023/11/30 20:18:58Z: Language: en-US
2023/11/30 20:18:58Z: TimeZone: UTC
2023/11/30 20:18:58Z: Offset: UTC +0000
2023/11/30 20:18:58Z: Launch: EC2 Launch v2.0.1643
2023/11/30 20:18:58Z: AMI-ID: ami-1234567890abcdef1
2023/11/30 20:18:58Z: Instance-ID: i-1234567890abcdef0
2023/11/30 20:18:58Z: Instance Type: c5.large
2023/11/30 20:19:00Z: Driver: AWS NVMe Driver v1.5.0.33
2023/11/30 20:19:00Z: SubComponent: AWS NVMe Driver v1.5.0.33; EnableSCSIPersistentReservations: 0
2023/11/30 20:19:00Z: Driver: AWS PV Driver Package v8.4.3
2023/11/30 20:19:01Z: Driver: Amazon Elastic Network Adapter v2.6.0.0
2023/11/30 20:19:01Z: RDPCERTIFICATE-SUBJECTNAME: EC2AMAZ-SO1T009
2023/11/30 20:19:01Z: RDPCERTIFICATE-THUMBPRINT: 1234567890ABCDEF1234567890ABCDEF1234567890
2023/11/30 20:19:09Z: SSM: Amazon SSM Agent v3.2.1705.0
2023/11/30 20:19:13Z: Username: Administrator
2023/11/30 20:19:13Z: Password: <Password>
1234567890abcdef1EXAMPLEPASSWORD
</Password>
2023/11/30 20:19:14Z: User data format: no_user_data	
2023/11/30 20:19:14Z: EC2LaunchTelemetry: IsTelemetryEnabled=true
2023/11/30 20:19:14Z: EC2LaunchTelemetry: AgentOsArch=windows_amd64
2023/11/30 20:19:14Z: EC2LaunchTelemetry: IsAgentScheduledPerBoot=true
2023/11/30 20:19:14Z: EC2LaunchTelemetry: AgentCommandErrorCode=0
2023/11/30 20:19:14Z: Message: Windows is Ready to use

EC2Launch v2 コンソールログメッセージ

以下に示しているのは、すべての EC2Launch v2 コンソールログメッセージのリストです。

Message: Error EC2Launch service is stopping. {error message}
 Error setting up EC2Launch agent folders
 See instance logs for detail
 Error stopping service
 Error initializing service
Message: Windows sysprep configuration complete
Message: Invalid administrator username: {invalid username}
Message: Invalid administrator password
Username: {username}
Password: <Password>{encrypted password}</Password>
AMI Origin Version: {amiVersion}
AMI Origin Name: {amiName}
Microsoft Windows NT {currentVersion}.{currentBuildNumber}
OsVersion: {currentVersion}
OsProductName: {productName}
OsBuildLabEx: {buildLabEx}
OsCurrentBuild: {currentBuild}
OsReleaseId: {releaseId}
Language: {language}
TimeZone: {timeZone}
Offset: UTC {offset}
Launch agent: EC2Launch {BuildVersion}
AMI-ID: {amiId}
Instance-ID: {instanceId}
Instance Type: {instanceType}
RDPCERTIFICATE-SUBJECTNAME: {certificate subject name}
RDPCERTIFICATE-THUMBPRINT: {thumbprint hash}
SqlServerBilling: {sql billing}
SqlServerInstall: {sql patch leve, edition type}
Driver: AWS NVMe Driver {version}
Driver: Inbox NVMe Driver {version}
Driver: AWS PV Driver Package {version}
Microsoft-Hyper-V is installed.
Unable to get service status for vmms
Microsoft-Hyper-V is {status}
SSM: Amazon SSM Agent {version}
AWS VSS Version: {version}
Message: Windows sysprep configuration complete
Message: Windows is being configured. SysprepState is {state}
Windows is still being configured. SysprepState is {state}
Message: Windows is Ready to use
Message: Waiting for meta-data accessibility...
Message: Meta-data is now available.
Message: Still waiting for meta-data accessibility...
Message: Failed to find primary network interface...retrying...
User data format: {format}