# EC2Launch v2 エージェントの問題をトラブルシューティングする このセクションでは、EC2Launch v2 での一般的なトラブルシューティングシナリオ、Windows イベントログの表示に関する情報、およびコンソールログの出力とメッセージについて説明します。 **Topics** + [一般的なシナリオ](#ec2launchv2-troubleshooting-scenarios) + [Windows イベントログ](#ec2launchv2-windows-event-logs) + [EC2Launch v2 コンソールログ出力](#ec2launchv2-console-output) ## 一般的なトラブルシューティングのシナリオ このセクションでは、一般的なトラブルシューティングのシナリオと解決手順を示します。 **Topics** + [サービスで壁紙を設定できない](#ec2launchv2-troubleshooting-wallpaper) + [サービスでユーザーデータを実行できない](#ec2launchv2-troubleshooting-user-data) + [サービスはタスクを 1 回だけ実行する](#ec2launchv2-troubleshooting-task-once) + [サービスでタスクを実行できない](#ec2launchv2-troubleshooting-task-failed) + [サービスはユーザーデータを複数回実行する](#ec2launchv2-troubleshooting-user-data-more-than-once) + [EC2Launch v2 への移行後、EC2Launch v1 のスケジュールされたタスクが実行されない](#ec2launchv2-troubleshooting-scheduled-tasks-migration) + [空ではない EBS ボリュームがサービスによって初期化される](#ec2launchv2-troubleshooting-ebs-initialize) + [`setWallpaper` タスクは有効になっていないものの、再起動時にウォールペーパーがリセットされる](#ec2launchv2-troubleshooting-wallpaper-resets) + [サービスは実行中ステータスでスタックしています](#ec2launchv2-troubleshooting-service-stuck-running) + [無効な`agent-config.yml`は EC2Launch v2 設定ダイアログボックスが開くことを防止します](#ec2launchv2-troubleshooting-invalid-agent-config) + [`task:executeScript should be unique and only invoked once`](#ec2launchv2-troubleshooting-executescript) ### サービスで壁紙を設定できない **解決策** 1. `%AppData%\Roaming\Microsoft\Windows\Start Menu\Programs\Startup\setwallpaper.lnk` が存在することを確認します。 1. `%ProgramData%\Amazon\EC2Launch\log\agent.log` をチェックし、エラーが発生したかどうかを確認します。 ### サービスでユーザーデータを実行できない **考えられる原因**: ユーザーデータを実行する前にサービスが失敗した可能性があります。 **解決策** 1. `%ProgramData%\Amazon\EC2Launch\state\previous-state.json` をチェックします。 1. `boot`、`network`、`preReady`、`postReadyLocalData` のすべてが成功とマークされているかどうかを確認します。 1. いずれかのステージが失敗した場合は、特定のエラーの `%ProgramData%\Amazon\EC2Launch\log\agent.log` を確認します。 ### サービスはタスクを 1 回だけ実行する **解決策** 1. タスクの頻度を確認します。 1. サービスが Sysprep 後に実行済みであり、タスクの頻度が `once` に設定されている場合、タスクは再度実行されません。 1. EC2Launch v2 が実行されるたびにタスクを実行する場合は、タスクの頻度を `always` に設定します。 ### サービスでタスクを実行できない **解決策** 1. `%ProgramData%\Amazon\EC2Launch\log\agent.log` の最新のエントリを確認します。 1. エラーが発生しなかった場合は、`"%ProgramFiles%\Amazon\EC2Launch\EC2Launch.exe" run` からサービスを手動で実行し、タスクが成功するかどうかを確認します。 ### サービスはユーザーデータを複数回実行する **解決策** ユーザーデータは、EC2Launch v1 と EC2Launch v2 では異なる方法で処理されます。`persist` が `true` に設定されている場合、EC2Launch v1 はユーザーデータをインスタンスでスケジュールされたタスクとして実行します。`persist` が `false` に設定されている場合、タスクが再起動して終了したり、実行中に中断された場合でも、タスクはスケジュールされません。 EC2Launch v2 は、ユーザーデータをエージェントタスクとして実行し、実行状態を追跡します。ユーザーデータがコンピュータの再起動を発行した場合、または実行中にユーザーデータが中断された場合、実行状態は `pending` として持続し、ユーザーデータは次回のインスタンスの起動時に再び実行されます。ユーザーデータスクリプトが複数回実行されないようにするには、スクリプトをべき等にします。 次のべき等スクリプト例では、コンピュータ名を設定し、ドメインに参加します。 ``` $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" } false ``` ### EC2Launch v2 への移行後、EC2Launch v1 のスケジュールされたタスクが実行されない **解決策** 移行ツールは、EC2Launch v1 スクリプトにリンクされているスケジュールされたタスクを検出しないため、EC2Launch v2 のタスクは自動的にセットアップされません。タスクを設定するには、[`agent-config.yml`](ec2launch-v2-settings.md#ec2launch-v2-task-configuration) ファイルを編集するか、[EC2Launch v2 設定ダイアログボックス](ec2launch-v2-settings.md#ec2launch-v2-ui)を使用します。例えば、インスタンスのタスクが `InitializeDisks.ps1` を実行するようにスケジュールされている場合は、移行ツールを実行した後、EC2Launch v2 の設定ダイアログボックスで、初期化するボリュームを指定する必要があります。[EC2Launch v2 設定ダイアログボックスを使用して設定を変更する](ec2launch-v2-settings.md#ec2launch-v2-ui) の手順については、ステップ 6 を参照してください。 ### 空ではない EBS ボリュームがサービスによって初期化される **解決策** ボリュームが初期化される前に、EC2Launch v2 は、そのボリュームにデータがないこと確認します。ボリュームが空でない場合、初期化はスキップされます。空でないことが検出されたボリュームは初期化されません。ボリュームの最初の 4 KiB が空の場合、またはボリュームに [ Windows を認識できるドライブレイアウト](https://learn.microsoft.com/en-us/windows/win32/api/winioctl/ns-winioctl-drive_layout_information_ex)がない場合、ボリュームは空と見なされます。Linux システムで初期化およびフォーマットされたボリュームには、Windows を認識できるドライブレイアウト (MBR や GPT など) がありません。したがって、それは空とみなされ、初期化されます。このデータを保持する場合、EC2Launch v2 による空ドライブの検出には頼らないでください。代わりに、[EC2Launch v2 設定ダイアログボックス](ec2launch-v2-settings.md#ec2launch-v2-ui) (ステップ 6 を参照) または [`agent-config.yml`](ec2launch-v2-task-definitions.md#ec2launch-v2-initializevolume) で、初期化するボリュームを指定します。 ### `setWallpaper` タスクは有効になっていないものの、再起動時にウォールペーパーがリセットされる `setWallpaper` タスクにより、すべての既存ユーザーのスタートアップフォルダ内に `setwallpaper.lnk` ショートカットファイルが作成されます。このショートカットファイルは、ユーザーがインスタンスの起動後に初めてログインしたときに実行されます。インスタンス属性を表示するカスタム壁紙があるインスタンスが設定されます。この `setWallpaper` タスクを削除しても、このショートカットファイルは削除されません。このファイルは手動で削除するか、スクリプトを使用して削除する必要があります。 ショートカットパスは次のとおりです。 `$env:SystemDrive/Users//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 インスタンスをトラブルシューティングする](troubleshoot-using-serial-console.md#troubleshooting-sac)」を参照してください。 **解決策** この問題を解決するには、以下の手順を実行します。 + このシリアルポートを使用しているサービスを、無効にします。 + サービスでこのシリアルポートを引き続き使用する場合は、起動エージェントタスクを実行するカスタムスクリプトを作成し、スケジュールされたタスクとして起動します。 ### 無効な`agent-config.yml`は EC2Launch v2 設定ダイアログボックスが開くことを防止します **説明** EC2Launch v2 設定は、ダイアログボックスを開く前に `agent-config.yml` ファイルの解析を試みます。YAML 設定ファイルがサポートされているスキーマに準拠しない場合、ダイアログボックスに次のエラーが表示されます。 `Unable to parse configuration file agent-config.yml. Review configuration file. Exiting application.` **解決策** 1. 設定ファイルが [[supported schema]](ec2launch-v2-settings.md#ec2launch-v2-schema-agent-config) (サポートされているスキーマ) に準拠していることを検証します。 1. 最初から始めたい場合は、デフォルトの設定ファイルを `agent-config.yml` にコピーします。「タスク設定セクション」に提供されている [サンプル `agent-config.yml`](ec2launch-v2-settings.md#ec2launch-v2-example-agent-config) を使用できます。 1. `agent-config.yml` を削除して最初からやり直すこともできます。EC2Launch v2 設定は空の設定ファイルを生成します。 ### `task:executeScript should be unique and only invoked once` **説明** 同じステージでタスクを繰り返すことはできません。 **解決策** 一部のタスクは、[**executeScript**](ec2launch-v2-task-definitions.md#ec2launch-v2-executescript) と [**executeProgram**](ec2launch-v2-task-definitions.md#ec2launch-v2-executeprogram) などの配列として入力する必要があります。スクリプトを配列として記述する方法の例については、「[**executeScript**](ec2launch-v2-task-definitions.md#ec2launch-v2-executescript)」を参照してください。 ## Windows イベントログ EC2Launch v2 は、サービスの開始、Windows の準備完了、さらにタスクの成否などの重要なイベントに関する Windows イベントログを発行します。イベント識別子は、特定のイベントを一意に識別します。各イベントには、ステージ、タスク、レベル情報、説明が含まれます。イベント識別子を使用して、特定のイベントのトリガーを設定できます。 イベント識別子は、イベントに関する情報を提供し、いくつかのイベントを一意に識別します。イベント ID の最下位桁は、イベントの重大度を示します。 | イベント | 最下位桁 | | --- | --- | | Success | . . .0 | | Informational | . . .1 | | Warning | . . .2 | | Error | . . .3 | サービスの開始時または停止時に生成されるサービスに関するイベントには、1 桁のイベント識別子が含まれます。 | イベント | 1 桁の識別子 | | --- | --- | | Success | 0 | | Informational | 1 | | Warning | 2 | | Error | 3 | `EC2LaunchService.exe` イベントのイベントメッセージは、`Service:` から始まります。`EC2Launch.exe` イベントのイベントメッセージは、`Service:` で始まるものではありません。 4 桁のイベント ID には、イベントのステージ、タスク、重大度に関する情報が含まれます。 **Topics** + [イベント ID 形式](#ec2launchv2-windows-event-logs-format) + [イベント ID の例](#ec2launchv2-windows-event-logs-id-examples) + [Windows イベントログのスキーマ](#ec2launch-v2-windows-event-logs-schema) ### イベント ID 形式 次の表に EC2Launch v2 でのイベント識別子の形式を示します。 | 3 | 2 1 | 0 | | --- | --- | --- | | S | T | L | 表内の文字と数字は、次のイベントタイプと定義を表します。 | イベントタイプ | 定義 | | --- | --- | | S (ステージ) | 0 - サービスレベルのメッセージ 1 - Boot 2 - Network 3 - PreReady 5 - Windows is Ready 6 - PostReady 7 - User Data | | T (タスク) | 対応する 2 つの値で表されるタスクは、ステージごとに異なります。イベントの詳細なリストを表示するには、[Windows イベントログのスキーマ](#ec2launch-v2-windows-event-logs-schema)を参照してください。 | | L (イベントのレベル) | 0 - 成功 1 - 情報 2 - 警告 3 - エラー | ### イベント ID の例 イベント ID の例を次に示します。 + `5000` - Windows の使用準備完了 + `3010` - PreReady ステージの Windows のアクティブ化タスクが成功しました + `6013` - PostReady ローカルデータステージの壁紙の設定タスクでエラーが発生しました ### Windows イベントログのスキーマ | メッセージ ID/イベント ID | イベントメッセージ | | --- | --- | | . . .0 | Success | | . . .1 | Informational | | . . .2 | Warning | | . . .3 | Error | | x | EC2Launch service-level logs | | 0 | EC2Launch service exited successfully | | 1 | EC2Launch service informational logs | | 2 | EC2Launch service warning logs | | 3 | EC2Launch service error logs | | 10 | Replace state.json with previous-state.json | | 100 | Serial Port | | 200 | Sysprep | | 300 | PrimaryNic | | 400 | Metadata | | x000 | Stage (1 digit), Task (2 digits), Status (1 digit) | | 1000 | Boot | | 1010 | Boot - extend\$1root\$1partition | | 2000 | Network | | 2010 | Network - add\$1routes | | 3000 | PreReady | | 3010 | PreReady - activate\$1windows | | 3020 | PreReady - install\$1egpu\$1manager | | 3030 | PreReady - set\$1monitor\$1on | | 3040 | PreReady - set\$1hibernation | | 3050 | PreReady - set\$1admin\$1account | | 3060 | PreReady - set\$1dns\$1suffix | | 3070 | PreReady - set\$1wallpaper | | 3080 | PreReady - set\$1update\$1schedule | | 3090 | PreReady - output\$1log | | 3100 | PreReady - enable\$1open\$1ssh | | 5000 | Windows is Ready to use | | 6000 | PostReadyLocalData | | 7000 | PostReadyUserData | | 6010/7010 | PostReadyLocal/UserData - set\$1wallpaper | | 6020/7020 | PostReadyLocal/UserData - set\$1update\$1schedule | | 6030/7030 | PostReadyLocal/UserData - set\$1hostname | | 6040/7040 | PostReadyLocal/UserData - execute\$1program | | 6050/7050 | PostReadyLocal/UserData - execute\$1script | | 6060/7060 | PostReadyLocal/UserData - manage\$1package | | 6070/7070 | PostReadyLocal/UserData - initialize\$1volume | | 6080/7080 | PostReadyLocal/UserData - write\$1file | | 6090/7090 | PostReadyLocal/UserData - start\$1ssm | | 7100 | PostReadyUserData - enable\$1open\$1ssh | | 6110/7110 | PostReadyLocal/UserData - enable\$1jumbo\$1frames | ## EC2Launch v2 コンソールログ出力 このセクションには、サンプルの EC2Launch v2 コンソールログ出力が含まれており、EC2Launch v2 コンソールログエラーメッセージのうち、問題のトラブルシューティングに役立つものを一覧表示しています。インスタンスコンソール出力とそのアクセス方法の詳細については、「[インスタンスコンソール出力](troubleshoot-unreachable-instance.md#instance-console-console-output)」を参照してください。 **Topics** + [EC2Launch v2 コンソールログ出力](#ec2launchv2-console-log-output) + [EC2Launch v2 コンソールログメッセージ](#ec2launchv2-console-log-messages) ### EC2Launch v2 コンソールログ出力 以下に示しているのは、サンプルの EC2Launch v2 コンソールログ出力です。この例の一部の値は、中括弧で囲まれた代表的なテキストに置き換えられます。 ``` 2025/07/22 21:26:53Z: Windows sysprep configuration complete. 2025/07/22 21:26:53Z: Message: Waiting for access to metadata... 2025/07/22 21:26:53Z: Message: Meta-data is now available. 2025/07/22 21:26:53Z: AMI Origin Version: 2024.12.13 2025/07/22 21:26:53Z: AMI Origin Name: Windows_Server-2022-English-Full-Base 2025/07/22 21:26:53Z: OS: Microsoft Windows NT 10.0.20348 2025/07/22 21:26:53Z: OsVersion: 10.0 2025/07/22 21:26:53Z: OsProductName: Windows Server 2022 Datacenter 2025/07/22 21:26:53Z: OsBuildLabEx: 20348.1.amd64fre.fe_release.210507-1500 2025/07/22 21:26:53Z: OsCurrentBuild: 20348 2025/07/22 21:26:53Z: OsReleaseId: 2009 2025/07/22 21:26:53Z: Language: en-US 2025/07/22 21:26:53Z: TimeZone: UTC 2025/07/22 21:26:53Z: Offset: UTC +0000 2025/07/22 21:26:53Z: Launch: EC2 Launch v2.2.63 2025/07/22 21:26:53Z: AMI-ID: ami-1234567890abcdef1 2025/07/22 21:26:53Z: Instance-ID: i-1234567890abcdef0 2025/07/22 21:26:54Z: Instance Type: t3.xlarge 2025/07/22 21:26:54Z: Driver: AWS NVMe Driver v1.6.0.35 2025/07/22 21:26:54Z: SubComponent: 1.6.0.35; EnableSCSIPersistentReservations: 0 2025/07/22 21:26:54Z: Driver: AWS PV Driver Package v8.5.0 2025/07/22 21:26:55Z: Driver: Amazon Elastic Network Adapter v2.8.0.0 2025/07/22 21:26:55Z: HOSTNAME: EC2AMAZ-9FJG5CC 2025/07/22 21:26:55Z: RDPCERTIFICATE-SUBJECTNAME: {certificate subject name} 2025/07/22 21:26:55Z: RDPCERTIFICATE-THUMBPRINT: {thumbprint hash} 2025/07/22 21:26:56Z: SSM: Amazon SSM Agent v3.3.2746.0 2025/07/22 21:26:57Z: User data format: no_user_data 2025/07/22 21:26:57Z: EC2LaunchTelemetry: IsTelemetryEnabled=true 2025/07/22 21:26:57Z: EC2LaunchTelemetry: AgentOsArch=windows_amd64 2025/07/22 21:26:57Z: EC2LaunchTelemetry: IsAgentScheduledPerBoot=true 2025/07/22 21:26:57Z: EC2LaunchTelemetry: AgentCommandErrorCode=1 2025/07/22 21:26:57Z: EC2LaunchTelemetry: AdminPasswordTypeCode=0 2025/07/22 21:26:57Z: EC2LaunchTelemetry: AgentErrorLocation=execute_windows.go:410 2025/07/22 21:26:57Z: EC2LaunchTelemetry: IpConflictDetectionCode=0 2025/07/22 21:26:57Z: Message: Windows is Ready to use {"type":"EC2AgentTelemetry","agentId":"WindowsLaunchAgentV2", ...} {"type":"EC2AgentTelemetry","agentId":"WindowsLaunchAgentV2", ...} ``` ### EC2Launch v2 コンソールログメッセージ 以下に示しているのは、すべての EC2Launch v2 コンソールログメッセージのリストです。 ``` Error EC2Launch service is stopping. {error message} ``` 停止したサービスエラーの詳細： + `Error setting up EC2Launch agent folders` + `See instance logs for detail` + `Error stopping service` + `Error initializing service` ``` Windows sysprep configuration complete ``` ``` Invalid administrator username: {invalid username} ``` ``` Invalid administrator password Username: {username} Password: {encrypted password} ``` 次のメッセージは、AMI の詳細を含む情報ブロックです。 ``` 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} HOSTNAME: {computer name} 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} SSM: Amazon SSM Agent {version} AWS VSS Version: {version} ``` ``` Windows sysprep configuration complete. Windows is being configured. 'SysprepState is {state}' Windows is still being configured. 'SysprepState is {state}' Windows is Ready to use Waiting for access to metadata... Meta-data is now available. Metadata is not available for this instance. Timed out waiting for access to metadata. User data format: {format} ``` EC2Launch v2 テレメトリメッセージには、起動テレメトリプロパティ値が含まれます。バージョン 2.2.63 以降、EC2 エージェントテレメトリデータは JSON オブジェクトとしてフォーマットされます。 ``` EC2LaunchTelemetry: {telemetry property} ``` ``` {"type":"EC2AgentTelemetry","agentId":"WindowsLaunchAgentV2" ... } ```