EC2Launch v2 문제 해결 - Amazon Elastic Compute Cloud
일반적인 시나리오Windows 이벤트 로그EC2Launch v2 콘솔 로그 출력

EC2Launch v2 문제 해결

이 섹션에서는 EC2Launch v2에 대한 일반적인 문제 해결 시나리오, Windows 이벤트 로그 보기에 대한 정보 및 콘솔 로그 출력과 메시지를 보여줍니다.

일반적인 문제 해결 시나리오

이 섹션에서는 일반적인 문제 해결 시나리오와 해결 단계를 보여 줍니다.

서비스에서 월페이퍼를 설정하지 못함

해결 방법

  1. %AppData%\Roaming\Microsoft\Windows\Start Menu\Programs\Startup\setwallpaper.lnk가 있는지 확인합니다.

  2. %ProgramData%\Amazon\EC2Launch\log\agent.log를 검토해 오류가 발생했는지 확인합니다.

서비스에서 사용자 데이터를 실행하지 못함

가능한 원인: 사용자 데이터를 실행하기 전에 서비스가 실패했을 수 있습니다.

해결 방법

  1. %ProgramData%\Amazon\EC2Launch\state\previous-state.json을 검토합니다.

  2. boot, network, preReady 및 postReadyLocalData가 모두 성공으로 표시되었는지 확인합니다.

  3. 스테이지 중 하나가 실패한 경우 %ProgramData%\Amazon\EC2Launch\log\agent.log에서 구체적인 오류를 확인합니다.

서비스가 태스크를 한 번만 실행함

해결 방법

  1. 작업 빈도를 확인합니다.

  2. 서비스가 Sysprep 이후에 이미 실행되었고 작업 빈도가 once로 설정된 경우 작업이 다시 실행되지 않습니다.

  3. EC2Launch v2가 실행될 때마다 태스크를 실행하려는 경우 태스크 빈도를 always로 설정합니다.

서비스에서 작업을 실행하지 못함

해결 방법

  1. %ProgramData%\Amazon\EC2Launch\log\agent.log에서 최근 항목을 확인합니다.

  2. 오류가 발생하지 않은 경우 "%ProgramFiles%\Amazon\EC2Launch\EC2Launch.exe" run에서 수동으로 서비스를 실행하여 작업이 성공했는지 확인합니다.

서비스가 사용자 데이터를 두 번 이상 실행함

해결 방법

사용자 데이터는 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는 볼륨을 초기화하기 전에 볼륨이 비어 있는지 여부를 감지합니다. 볼륨이 비어 있지 않으면 초기화를 건너뜁니다. 비어 있지 않은 것으로 감지된 볼륨은 초기화되지 않습니다. 볼륨의 처음 4KiB가 비어 있거나 볼륨에 Windows 인식 가능한 드라이브 레이아웃이 없는 경우 볼륨은 비어 있는 것으로 간주됩니다. Linux 시스템에서 초기화되고 포맷된 볼륨에는 MBR 또는 GPT와 같은 Windows 인식 가능한 드라이브 레이아웃이 없습니다. 따라서 비어 있고 초기화된 것으로 간주됩니다. 이 데이터를 보존하려면 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.

해결 방법

  1. 구성 파일이 지원되는 스키마를 따르는지 확인합니다.

  2. 처음부터 시작하려면 기본 구성 파일을 agent-config.yml에 복사하세요. 작업 구성 섹션의 agent-config.yml 예시를 사용할 수 있습니다.

  3. agent-config.yml을 삭제하여 다시 시작할 수도 있습니다. EC2Launch v2 설정은 빈 구성 파일을 생성합니다.

task:executeScript should be unique and only invoked once

설명

동일한 단계에서는 작업을 반복할 수 없습니다.

해결 방법

executeScript 및 executeProgram과 같은 일부 작업은 배열로 입력해야 합니다. 스크립트를 배열로 작성하는 방법의 예제는 executeScript를 참조하세요.

Windows 이벤트 로그

EC2Launch v2는 서비스 시작, Windows 준비, 태스크 성공 및 실패와 같은 중요한 이벤트에 대한 Windows 이벤트 로그를 게시합니다. 이벤트 식별자는 특정 이벤트를 고유하게 식별합니다. 각 이벤트에는 스테이지, 작업 및 레벨 정보와 설명이 포함됩니다. 이벤트 식별자를 사용하여 특정 이벤트에 대한 트리거를 설정할 수 있습니다.

이벤트 ID는 이벤트에 대한 정보를 제공하고 일부 이벤트를 고유하게 식별합니다. 이벤트 ID의 최하위 자릿수는 이벤트의 심각도를 나타냅니다.

Event 최하위 자릿수
Success . . .0
Informational . . .1
Warning . . .2
Error . . .3

서비스가 시작되거나 중지될 때 생성되는 서비스 관련 이벤트에는 한 자리의 이벤트 식별자가 포함됩니다.

Event 한 자리의 식별자
Success 0
Informational 1
Warning 2
Error 3

EC2LaunchService.exe 이벤트에 대한 이벤트 메시지는 Service:로 시작합니다. EC2Launch.exe 이벤트에 대한 이벤트 메시지는 Service:로 시작하지 않습니다.

네 자리의 이벤트 ID에는 이벤트의 단계, 작업 및 심각도에 대한 정보가 포함됩니다.

이벤트 ID 형식

다음 표에는 EC2Launch v2 이벤트 식별자의 형식이 나와 있습니다.

3 2 1 0

S

T

L

표의 문자와 숫자는 다음과 같은 이벤트 유형 및 정의를 나타냅니다.

이벤트 유형 정의

S(스테이지)

0 - 서비스 수준 메시지

1 - 부팅

2 - 네트워크

3 - 사전 준비

5 - Windows 준비

6 - 사후 준비

7 - 사용자 데이터

T(작업)

해당 두 값으로 표시되는 작업은 각 스테이지마다 다릅니다. 전체 이벤트 목록을 보려면 Windows 이벤트 로그 스키마를 참조하세요.
L(이벤트 수준)

0 - 성공

1 - 정보

2 - 경고

3 - 오류

이벤트 ID 예

다음은 이벤트 ID의 예입니다.

  • 5000 - Windows를 사용할 준비가 됨

  • 3010 - 사전 준비 스테이지에서 Windows 활성화 작업 성공

  • 6013 - 사후 준비 로컬 데이터 스테이지에서 월페이퍼 설정 작업에 오류 발생

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_root_partition
2000 Network
2010 Network - add_routes
3000 PreReady
3010 PreReady - activate_windows
3020 PreReady - install_egpu_manager
3030 PreReady - set_monitor_on
3040 PreReady - set_hibernation
3050 PreReady - set_admin_account
3060 PreReady - set_dns_suffix
3070 PreReady - set_wallpaper
3080 PreReady - set_update_schedule
3090 PreReady - output_log
3100 PreReady - enable_open_ssh
5000 Windows is Ready to use
6000 PostReadyLocalData
7000 PostReadyUserData
6010/7010 PostReadyLocal/UserData - set_wallpaper
6020/7020 PostReadyLocal/UserData - set_update_schedule
6030/7030 PostReadyLocal/UserData - set_hostname
6040/7040 PostReadyLocal/UserData - execute_program
6050/7050 PostReadyLocal/UserData - execute_script
6060/7060 PostReadyLocal/UserData - manage_package
6070/7070 PostReadyLocal/UserData - initialize_volume
6080/7080 PostReadyLocal/UserData - write_file
6090/7090 PostReadyLocal/UserData - start_ssm
7100 PostReadyUserData - enable_open_ssh
6110/7110 PostReadyLocal/UserData - enable_jumbo_frames

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}