EC2Launch v2 에이전트와 관련된 문제 해결

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

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

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

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

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

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

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

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

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

해결 방법

사용자 데이터는 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.

task:executeScript should be unique and only invoked once

설명

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

해결 방법

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

Windows 이벤트 로그

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

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

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

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

네 자리의 이벤트 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}