EC2Launch v2 에이전트 문제 해결

EC2Launch v2 에이전트 문제 해결

이 섹션은 EC2Launch v2의 일반적인 문제 해결 시나리오, Windows 이벤트 로그 보기 정보, 콘솔 로그 출력 및 메시지를 보여줘요.

출처: 문서

본문

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

이 섹션은 일반적인 문제 해결 시나리오와 해결 단계를 보여줘요.

  • 서비스가 배경화면을 설정하지 못함
  • 서비스가 사용자 데이터를 실행하지 못함
  • 서비스가 태스크를 한 번만 실행함
  • 서비스가 태스크를 실행하지 못함
  • 서비스가 사용자 데이터를 두 번 이상 실행함
  • EC2Launch v2로 마이그레이션한 후 EC2Launch v1의 예약 태스크가 실행 실패
  • 서비스가 비어 있지 않은 EBS 볼륨을 초기화함
  • setWallpaper 태스크가 활성화되지 않았는데 재부팅 시 배경화면이 리셋됨
  • 서비스가 running 상태에서 멈춤
  • 잘못된 agent-config.yml로 EC2Launch v2 설정 대화 상자를 열 수 없음
  • task:executeScript는 고유해야 하며 한 번만 호출돼야 함

서비스가 배경화면을 설정하지 못함

해결 방법
  • %AppData%\Roaming\Microsoft\Windows\Start Menu\Programs\Startup\setwallpaper.lnk가 존재하는지 확인합니다.
  • %ProgramData%\Amazon\EC2Launch\log\agent.log를 확인해 오류가 발생했는지 확인합니다.

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

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

해결 방법
  • %ProgramData%\Amazon\EC2Launch\state\previous-state.json을 확인합니다.
  • boot, network, preReady, postReadyLocalData가 모두 success로 표시됐는지 확인합니다.
  • 단계 중 하나가 실패했다면 %ProgramData%\Amazon\EC2Launch\log\agent.log에서 특정 오류를 확인합니다.

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

해결 방법
  • 태스크의 빈도(frequency)를 확인합니다.
  • Sysprep 후 서비스가 이미 실행됐고 태스크 빈도가 once로 설정돼 있으면 태스크는 다시 실행되지 않습니다.
  • EC2Launch v2가 실행될 때마다 태스크를 실행하려면 빈도를 always로 설정합니다.

서비스가 태스크를 실행하지 못함

해결 방법
  • %ProgramData%\Amazon\EC2Launch\log\agent.log의 최신 항목을 확인합니다.
  • 오류가 없다면 "%ProgramFiles%\Amazon\EC2Launch\EC2Launch.exe" run으로 서비스를 수동으로 실행해 태스크가 성공하는지 확인합니다.

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

해결 방법

사용자 데이터는 EC2Launch v1과 EC2Launch v2에서 다르게 처리돼요. EC2Launch v1은 persist가 true로 설정되면 인스턴스에서 사용자 데이터를 예약 태스크로 실행합니다. persist가 false로 설정되면 태스크가 재부팅으로 종료되거나 실행 중 중단되더라도 예약되지 않습니다.

EC2Launch v2는 사용자 데이터를 에이전트 태스크로 실행하고 실행 상태를 추적합니다. 사용자 데이터가 컴퓨터 재시작을 발행하거나 사용자 데이터가 실행 중 중단되면 실행 상태가 pending으로 유지되고 다음 인스턴스 부팅 시 사용자 데이터가 다시 실행됩니다. 사용자 데이터 스크립트가 두 번 이상 실행되지 않게 하려면 스크립트를 멱등적(idempotent)으로 만드세요.

다음은 컴퓨터 이름을 설정하고 도메인에 조인하는 예시 멱등성 스크립트입니다.

<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 태스크는 각 기존 사용자의 시작 폴더에 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
		}
	}
}

서비스가 running 상태에서 멈춤

설명

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.
해결 방법
  • 구성 파일이 지원되는 스키마 를 따르는지 확인합니다.
  • 처음부터 시작하려면 기본 구성 파일을 agent-config.yml에 복사합니다. Task Configuration 섹션에 제공된 예시 agent-config.yml 을 사용할 수 있습니다.
  • agent-config.yml을 삭제해 처음부터 다시 시작할 수도 있습니다. EC2Launch v2 설정은 빈 구성 파일을 생성합니다.

task:executeScript는 고유해야 하며 한 번만 호출돼야 함

설명

태스크는 같은 단계에서 반복될 수 없습니다.

해결 방법

executeScript와 executeProgram 같은 일부 태스크는 배열로 입력해야 해요. 스크립트를 배열로 작성하는 예시는 executeScript를 참고하세요.

Windows 이벤트 로그

EC2Launch v2는 서비스 시작, Windows 준비 완료, 태스크 성공/실패 같은 중요 이벤트에 대한 Windows 이벤트 로그를 게시합니다. 이벤트 식별자는 특정 이벤트를 고유하게 식별합니다. 각 이벤트에는 단계(stage), 태스크(task), 수준(level) 정보와 설명이 포함됩니다. 이벤트 식별자를 사용해 특정 이벤트에 대한 트리거를 설정할 수 있어요.

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

이벤트 최하위 자릿수
성공(Success) ...0
정보(Informational) ...1
경고(Warning) ...2
오류(Error) ...3

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

이벤트 한 자리 식별자
성공(Success) 0
정보(Informational) 1
경고(Warning) 2
오류(Error) 3

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

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

  • Event ID 형식
  • Event ID 예시
  • Windows 이벤트 로그 스키마

이벤트 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 (태스크) 해당 두 값으로 나타나는 태스크는 각 단계마다 다릅니다. 전체 이벤트 목록은 Windows Event log schema 를 참고하세요.
L (이벤트 수준) 0 - 성공, 1 - 정보, 2 - 경고, 3 - 오류

이벤트 ID 예시

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

  • 5000 — Windows is ready to use
  • 3010 — Activate windows task in PreReady stage was successful
  • 6013 — Set wallpaper task in PostReady Local Data stage encountered an error

Windows 이벤트 로그 스키마

MessageId/Event Id 이벤트 메시지
...0 성공
...1 정보
...2 경고
...3 오류
x EC2Launch 서비스 수준 로그
0 EC2Launch service exited successfully
1 EC2Launch 서비스 정보 로그
2 EC2Launch 서비스 경고 로그
3 EC2Launch 서비스 오류 로그
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의 샘플 콘솔 로그 출력입니다. 이 예시의 일부 값은 중괄호로 둘러싸인 대표 텍스트로 대체됐습니다.

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: Driver: EC2 Windows Utility Device v3.1.0.25
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: <Password>{encrypted password}</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}
Driver: EC2 Windows Utility Device {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 원격 측정(telemetry) 메시지에는 실행 원격 측정 속성 값이 포함됩니다. 버전 2.2.63부터 EC2 에이전트 원격 측정 데이터는 JSON 객체로 형식화됩니다.

EC2LaunchTelemetry: {telemetry property}

{"type":"EC2AgentTelemetry","agentId":"WindowsLaunchAgentV2" ... }

더 알아보기

  • 태스크 정의
  • 버전 기록