# EC2Launch v2 에이전트를 사용하여 EC2 Windows 인스턴스 시작 중 태스크 수행
AWS Windows Server 2022 및 Windows Server 2025 AMI에서 시작되는 Amazon EC2의 지원되는 모든 인스턴스에는 기본적으로 EC2Launch v2 시작 에이전트(`EC2Launch.exe`)가 포함됩니다. 또한 EC2Launch v2를 기본 시작 에이전트로 설치한 Windows Server 2016 및 2019 AMI를 제공합니다. 이러한 AMI는 EC2Launch v1을 포함하는 Windows Server 2016 및 2019 AMI와 함께 제공됩니다. Amazon EC2 콘솔에서 **AMI** 페이지의 검색에 `EC2LaunchV2-Windows_Server-*` 접두사를 입력하여 기본적으로 EC2Launch v2를 포함하는 Windows AMI를 검색할 수 있습니다.
시작 에이전트 버전 기능을 비교하려면 [Amazon EC2 시작 에이전트 비교](configure-launch-agents.md#ec2launch-agent-compare) 섹션을 참조하세요.
EC2Launch v2는 인스턴스 시작 시 태스크를 수행하며 인스턴스가 중지된 후 나중에 시작되거나 재시작된 경우 실행되는 서비스입니다. EC2Launch v2는 태스크를 온디맨드로 수행할 수도 있습니다. 이러한 작업 중 일부는 자동으로 활성화되고, 나머지는 수동으로 활성화해야 합니다. EC2Launch v2 서비스는 모든 EC2Config 및 EC2Launch 기능을 지원합니다.
이 서비스는 구성 파일을 사용하여 작업을 제어합니다. 그래픽 도구를 사용하거나 단일 .yml 파일(`agent-config.yml`)로 직접 편집하여 구성 파일을 업데이트할 수 있습니다. 파일 위치에 대한 자세한 내용은 [EC2Launch v2 디렉터리 구조](#ec2launch-v2-directory) 섹션을 참조하세요.
EC2Launch v2에서는 오류 문제를 해결하고 트리거를 설정하는 데 도움이 되는 Windows 이벤트 로그를 게시합니다. 자세한 내용은 [Windows 이벤트 로그](ec2launchv2-troubleshooting.md#ec2launchv2-windows-event-logs) 섹션을 참조하세요.
**지원되는 OS 버전**
EC2Launch v2 에이전트는 다음 Windows Server 운영 체제(OS) 버전을 지원합니다.
+ Windows Server 2025
+ Windows Server 2022
+ Windows Server 2019(장기 서비스 채널 및 연 2회 채널)
+ Windows Server 2016
**기본적으로 실행되는 태스크**
EC2Launch v2 에이전트는 초기 인스턴스 시작 중에 기본적으로 다음 태스크를 한 번만 실행합니다. 태스크는 시작 단계에서 실행되는 순서에 따라 구성되어 있습니다.
`Boot` 단계
+ extendRootPartition
`PreReady` 단계
+ activateWindows
+ setDnsSuffix
+ setAdminAccount
+ setWallpaper
`PostReady` 단계
+ startSsm
## EC2Launch v2 개념
EC2Launch v2를 고려하는 경우 다음 개념을 이해하는 것이 좋습니다.
**agent-config**
`agent-config`는 EC2Launch v2의 구성 폴더에 있는 파일입니다. 부팅, 네트워크, 사전 준비 및 사후 준비 스테이지에 대한 구성이 포함되어 있습니다. 이 파일은 AMI가 처음 부팅되거나 이후에 부팅될 때 실행되어야 하는 태스크의 인스턴스 구성을 지정하는 데 사용됩니다.
기본적으로 EC2Launch v2 설치 시 표준 Amazon Windows AMI에서 사용되는 권장 구성을 포함한 `agent-config` 파일이 설치됩니다. 구성 파일을 업데이트하여 EC2Launch v2에서 지정되는 AMI의 기본 부팅 환경을 변경할 수 있습니다. 파일 위치에 대한 자세한 내용은 [EC2Launch v2 디렉터리 구조](#ec2launch-v2-directory) 섹션을 참조하세요.
**빈도**
태스크 빈도는 부팅 컨텍스트에 따라 태스크 실행 일정을 결정합니다. 대부분의 태스크에는 허용되는 빈도가 하나만 있습니다. `executeScript` 태스크의 빈도를 지정할 수 있습니다.
[EC2Launch v2 태스크 구성](ec2launch-v2-settings.md#ec2launch-v2-task-configuration)에 다음과 같은 빈도가 표시됩니다.
+ 한 번 – AMI가 처음 부팅될 때 태스크가 한 번 실행됩니다(Sysprep이 완료됨).
+ 항상 – 시작 에이전트가 실행될 때마다 태스크가 실행됩니다. 시작 에이전트가 실행되는 경우:
+ 인스턴스 시작 또는 재시작
+ EC2Launch 서비스 실행
+ `EC2Launch.exe run` 호출
**단계**
단계는 EC2Launch v2 에이전트가 실행하는 태스크를 논리적으로 묶은 것입니다. 일부 작업은 특정 스테이지에서만 실행할 수 있고, 일부 작업은 여러 스테이지로 실행할 수 있습니다. `agent-config.yml`을 사용할 때 단계 목록과 각 단계 내에서 실행할 태스크 목록을 지정해야 합니다.
서비스는 다음 단계로 실행합니다.
1단계: 부팅
2단계: 네트워크
3단계: PreReady
Windows가 준비됨
PreReady 단계가 완료되면 서비스에서 Amazon EC2 콘솔로 `Windows is ready` 메시지를 전송합니다.
4단계: PostReady
사용자 데이터는 *PostReady* 단계에서 실행됩니다. 다음과 같이 일부 스크립트 버전은 `agent-config.yml` 파일 *PostReady* 단계 이전에 실행되고 일부는 해당 단계 이후에 실행됩니다.
`agent-config.yml` 이전
+ YAML 사용자 데이터 버전 1.1
+ XML 사용자 데이터
`agent-config.yml` 이후
+ YAML 사용자 데이터 버전 1.0(이전 버전과의 호환성을 위한 레거시 버전)
예제 단계 및 태스크는 [예: `agent-config.yml`](ec2launch-v2-settings.md#ec2launch-v2-example-agent-config) 섹션을 참조하세요.
사용자 데이터를 사용하는 경우 실행 에이전트가 실행할 태스크 목록을 지정해야 합니다. 단계는 암시됩니다. 예제 태스크는 [예: 사용자 데이터](ec2launch-v2-settings.md#ec2launch-v2-example-user-data) 섹션을 참조하세요.
EC2Launch v2는 `agent-config.yml` 및 사용자 데이터에 지정하는 순서대로 태스크 목록을 실행합니다. 단계는 순차적으로 실행됩니다. 이전 단계가 완료된 후 다음 단계가 시작됩니다. 태스크도 순차적으로 실행됩니다.
**Task**
태스크를 호출하여 인스턴스에 대한 작업을 수행할 수 있습니다. `agent-config.yml` 파일에서 또는 사용자 데이터를 통해 태스크를 구성할 수 있습니다. EC2Launch v2에 사용 가능한 태스크 목록은 [EC2Launch v2 태스크](#ec2launch-v2-tasks)를 참조하세요. 태스크 구성 스키마와 세부 정보는 [EC2Launch v2 태스크 구성](ec2launch-v2-settings.md#ec2launch-v2-task-configuration) 섹션을 참조하세요.
**사용자 데이터**
사용자 데이터는 인스턴스를 시작할 때 구성 가능한 데이터입니다. 사용자 데이터를 업데이트하여 사용자 지정 AMI 또는 퀵 스타트 AMI 구성 방식을 동적으로 변경할 수 있습니다. EC2Launch v2는 60kB의 사용자 데이터 입력 길이를 지원합니다. 사용자 데이터에는 UserData 스테이지만 포함되므로 `agent-config` 파일 이후에 실행됩니다. 인스턴스 시작 마법사를 사용하여 인스턴스를 시작할 때 사용자 데이터를 입력하거나 EC2 콘솔에서 사용자 데이터를 수정할 수 있습니다. 사용자 데이터 작업에 대한 자세한 내용은 [Amazon EC2가 Windows 인스턴스의 사용자 데이터를 처리하는 방법](user-data.md#ec2-windows-user-data) 섹션을 참조하세요.
## EC2Launch v2 태스크 개요
EC2Launch v2는 부팅될 때마다 다음 태스크를 수행할 수 있습니다.
+ 인스턴스에 대한 정보를 렌더링하는 새로운/선택적으로 사용자 지정된 월페이퍼(wallpaper)를 설정합니다.
+ 로컬 시스템에 생성된 관리자 계정의 속성을 설정합니다.
+ 검색 접미사 목록에 DNS 접미사를 추가합니다. 아직 존재하지 않는 접미사만 목록에 추가됩니다.
+ 추가 볼륨에 대해 드라이브 문자를 설정하고 사용 가능한 공간을 사용하도록 확장합니다.
+ 구성의 파일을 디스크에 씁니다.
+ EC2Launch v2 구성 파일 또는 `user-data`에서 지정된 스크립트를 실행합니다. `user-data`의 스크립트는 일반 텍스트로 제공하거나 압축하여 base64 형식으로 제공할 수 있습니다.
+ 주어진 인수를 사용해 프로그램을 실행합니다.
+ 컴퓨터 이름을 설정합니다.
+ 인스턴스 정보를 Amazon EC2 콘솔에 전송합니다.
+ RDP 인증서 지문을 Amazon EC2 콘솔에 전송합니다.
+ 파티션 처리되지 않은 공간을 포함시키기 위한 운영 시스템 파티션을 동적으로 확장.
+ 사용자 데이터를 실행합니다. 사용자 데이터 지정에 대한 자세한 내용은 [EC2Launch v2 태스크 구성](ec2launch-v2-settings.md#ec2launch-v2-task-configuration) 섹션을 참조하세요.
+ 비영구 정적 경로를 설정하여 메타데이터 서비스 및 AWS KMS 서버에 도달합니다.
+ 부팅 파티션이 아닌 파티션을 `mbr` 또는 `gpt`.로 설정합니다.
+ Sysprep 이후에 Systems Manager 서비스를 시작합니다.
+ ENA 설정을 최적화합니다.
+ 최신 Windows 버전을 위해 OpenSSH를 활성화합니다.
+ 점보 프레임을 활성화합니다.
+ EC2Launch v2에서 Sysprep이 실행되도록 설정합니다.
+ Windows 이벤트 로그를 게시합니다.
## EC2Launch v2 디렉터리 구조
EC2Launch v2는 다음 디렉터리에 설치되어야 합니다.
+ 서비스 바이너리: `%ProgramFiles%\Amazon\EC2Launch`
+ 서비스 데이터(설정, 로그 파일 및 상태 파일): `%ProgramData%\Amazon\EC2Launch`
**참고**
기본적으로 Windows는 파일과 폴더를 `C:\ProgramData` 아래에 숨깁니다. EC2Launch v2 디렉터리와 파일을 보려면 Windows 탐색기에 경로를 입력하거나 숨겨진 파일과 폴더를 표시하도록 폴더 속성을 변경해야 합니다.
`%ProgramFiles%\Amazon\EC2Launch` 디렉터리에는 바이너리와 지원 라이브러리가 들어 있습니다. 여기에는 다음과 같은 하위 디렉터리가 포함됩니다.
+ `settings`
+ `EC2LaunchSettingsUI.exe` – `agent-config.yml` 파일을 수정하기 위한 사용자 인터페이스
+ `YamlDotNet.dll` – 사용자 인터페이스에서 일부 작업을 지원하기 위한 DLL
+ `tools`
+ `ebsnvme-id.exe` – 인스턴스에서 EBS 볼륨의 메타데이터를 검사하기 위한 도구
+ `AWSAcpiSpcrReader.exe` – 사용할 올바른 COM 포트를 결정하기 위한 도구
+ `EC2LaunchEventMessage.dll` – EC2 Launch에 대한 Windows 이벤트 로깅을 지원하기 위한 DLL
+ `service`
+ `EC2LaunchService.exe` – 시작 에이전트가 서비스로 실행될 때 시작되는 Windows 서비스 실행 파일
+ `EC2AgentTelemetry.dll` – EC2 에이전트 원격 측정을 지원하기 위한 DLL
+ `EC2Launch.exe` – 주요 EC2 Launch 실행 파일
+ `EC2LaunchAgentAttribution.txt` – EC2 Launch 내에서 사용되는 코드의 저작권 표시
`%ProgramData%\Amazon\EC2Launch` 디렉터리에는 다음 하위 디렉터리가 포함됩니다. 로그, 구성 및 상태를 포함하여 서비스에서 생성된 모든 데이터가 이 디렉터리에 저장됩니다.
+ `config` - 구성
서비스 구성 파일은 이 디렉터리에 `agent-config.yml`로 저장됩니다. 서비스에서 실행되는 기본 태스크를 수정, 추가 또는 제거하도록 이 파일을 업데이트할 수 있습니다. 이 디렉터리에 파일을 생성할 권한은 권한 에스컬레이션을 방지하기 위해 관리자 계정으로 제한됩니다.
+ `log` - 인스턴스 로그
서비스(`agent.log`), 성능(`bench.log`), 텔레메트리(`telemetry.log`) 로그가 이 디렉터리에 저장됩니다. `agent.log` 크기가 1MB에 도달하면 자동으로 교체되고 타임스탬프 형식(예: `agent-2026-03-02T18-56-39.188.log`)으로 백업 파일이 생성됩니다. 백업 로그 파일은 한 번에 하나만 유지됩니다.
+ `state` - 서비스 상태 데이터
서비스가 실행할 작업을 결정하는 데 사용하는 상태가 여기에 저장됩니다. Sysprep 이후에 서비스가 이미 실행되었는지 여부를 나타내는 `.run-once` 파일이 있습니다(따라서 빈도가 한 번인 태스크는 다음 실행 시 건너뜀). 이 하위 디렉터리에는 각 태스크의 상태를 추적하는 `state.json` 및 `previous-state.json`이 포함되어 있습니다.
+ `sysprep` - Sysprep
이 디렉터리에는 재사용할 수 있는 사용자 지정 Windows AMI를 만들 때 Sysprep에서 수행할 작업을 결정하는 데 사용되는 파일이 포함되어 있습니다.
+ `wallpaper` - 월페이퍼
이 월페이퍼 이미지는 이 디렉터리에 저장됩니다.
## 원격 측정
원격 측정 데이터는 AWS가 사용자의 요구 사항을 더 잘 이해하고, 문제를 진단하고, AWS 서비스의 경험을 개선할 기능을 제공하는 데 도움이 되는 추가 정보입니다.
EC2Launchv2 버전 `2.1.592` 이상은 사용량 지표 및 오류와 같은 원격 측정 데이터를 수집합니다. 이 데이터는 EC2Launch v2가 실행되는 Amazon EC2 인스턴스에서 수집됩니다. 여기에는 AWS가 소유한 모든 Windows AMI가 포함됩니다.
EC2Launch v2에서 수집되는 원격 측정 데이터의 유형은 다음과 같습니다.
+ **사용량 정보** - 에이전트 명령, 설치 방법 및 예약된 실행 빈도입니다.
+ **오류 및 진단 정보** - 에이전트 설치 오류 코드, 실행 오류 코드 및 오류 호출 스택입니다.
버전 2.0.592\$12.1.1에서 수집된 데이터의 예:
```
2025/07/18 22:38:52Z: EC2LaunchTelemetry: IsTelemetryEnabled=true
2025/07/18 22:38:52Z: EC2LaunchTelemetry: AgentOsArch=windows_amd64
2025/07/18 22:38:52Z: EC2LaunchTelemetry: IsAgentScheduledPerBoot=true
2025/07/18 22:38:52Z: EC2LaunchTelemetry: AgentCommandErrorCode=0
2025/07/18 22:38:52Z: EC2LaunchTelemetry: AdminPasswordTypeCode=0
2025/07/18 22:38:52Z: EC2LaunchTelemetry: IpConflictDetectionCode=0
2025/07/18 22:38:52Z: EC2LaunchTelemetry: AgentErrorLocation=addroutes.go:49
```
버전 2.2.63부터 EC2 에이전트 원격 측정 데이터는 JSON 객체로 형식이 지정됩니다.
```
{"type":"EC2AgentTelemetry","agentId":"WindowsLaunchAgentV2" ... }
```
원격 측정은 기본적으로 활성화됩니다. 언제든지 원격 측정 데이터 수집을 비활성화할 수 있습니다.
**인스턴스의 원격 측정 비활성화**
단일 인스턴스에 대한 원격 측정을 비활성화하려면 시스템 환경 변수를 설정하거나 MSI를 사용하여 설치 파일을 수정하면 됩니다.
시스템 환경 변수를 설정하여 원격 측정을 비활성화하려면 관리자로 다음 명령을 실행합니다.
```
setx /M EC2LAUNCH_TELEMETRY 0
```
MSI를 사용하여 원격 측정을 비활성화하려면 [MSI를 다운로드](ec2launch-v2-install.md)한 후 다음 명령을 실행합니다.
```
msiexec /i ".\AmazonEC2Launch.msi" Remove="Telemetry" /q
```
**Topics**
+ [EC2Launch v2 개념](#ec2launch-v2-concepts)
+ [EC2Launch v2 태스크 개요](#ec2launch-v2-tasks)
+ [EC2Launch v2 디렉터리 구조](#ec2launch-v2-directory)
+ [원격 측정](#ec2launch-v2-telemetry)
+ [최신 버전의 EC2Launch v2 설치](ec2launch-v2-install.md)
+ [Windows 인스턴스에 대한 EC2Launch v2 설정 구성](ec2launch-v2-settings.md)
+ [EC2Launch v2 시작 태스크에 대한 태스크 정의](ec2launch-v2-task-definitions.md)
+ [EC2Launch v2 에이전트와 관련된 문제 해결](ec2launchv2-troubleshooting.md)
+ [EC2Launch v2 버전 기록](ec2launchv2-versions.md)