EC2Launch v2 에이전트로 EC2 Windows 인스턴스 시작 시 작업 수행하기

EC2Launch v2 에이전트로 EC2 Windows 인스턴스 시작 시 작업 수행하기 (Use the EC2Launch v2 agent to perform tasks during EC2 Windows instance launch)

AWS Windows Server 2022 및 Windows Server 2025 AMI에서 시작된 지원되는 모든 Amazon EC2 인스턴스에는 EC2Launch v2 시작 에이전트(EC2Launch.exe)가 기본적으로 포함돼 있어요. 또한 EC2Launch v2가 기본 시작 에이전트로 설치된 Windows Server 2016·2019 AMI도 제공해요. EC2 콘솔의 AMIs 페이지에서 EC2LaunchV2-Windows_Server-* 접두사로 검색해 EC2Launch v2가 기본 포함된 Windows AMI를 찾을 수 있어요.

출처: 문서

본문

EC2Launch v2는 인스턴스 시작 시 작업을 수행하고, 인스턴스가 중지 후 재시작되거나 재시작되면 실행돼요. EC2Launch v2는 주문형(on demand)으로도 작업을 수행할 수 있어요. 일부 작업은 자동으로 활성화되고, 다른 작업은 수동으로 활성화해야 해요. EC2Launch v2 서비스는 모든 EC2Config와 EC2Launch 기능을 지원해요.

이 서비스는 구성 파일로 동작을 제어해요. 그래픽 도구를 사용하거나 단일 .yml 파일(agent-config.yml)을 직접 편집해 구성 파일을 업데이트할 수 있어요. EC2Launch v2는 오류 문제 해결과 트리거 설정을 돕도록 Windows 이벤트 로그를 게시해요.

지원되는 OS 버전

  • Windows Server 2025
  • Windows Server 2022
  • Windows Server 2019(장기 서비스 채널 및 반기 채널)
  • Windows Server 2016

기본으로 실행되는 작업

EC2Launch v2 에이전트는 초기 인스턴스 시작 중 기본적으로 다음 작업을 한 번만 실행해요.

Boot 단계:

  • extendRootPartition

PreReady 단계:

  • activateWindows
  • setDnsSuffix
  • setAdminAccount
  • setWallpaper

PostReady 단계:

  • startSsm

EC2Launch v2 개념

agent-config – EC2Launch v2 구성 폴더에 있는 파일이에요. boot, network, PreReady, PostReady 단계의 구성을 포함해요. AMI가 처음 또는 이후에 부팅될 때 실행되어야 하는 작업의 인스턴스 구성을 지정하는 데 사용돼요. 기본적으로 EC2Launch v2 설치 시 표준 Amazon Windows AMI에서 사용되는 권장 구성을 포함한 agent-config 파일이 설치돼요.

Frequency(빈도) – 작업 빈도는 부팅 컨텍스트에 따라 작업이 언제 실행될지 결정해요. 대부분의 작업은 허용된 빈도가 하나만이에요. executeScript 작업에는 빈도를 지정할 수 있어요.

  • Once – AMI가 처음 부팅(Sysprep 완료)됐을 때 작업이 한 번 실행돼요.
  • Always – 시작 에이전트가 실행될 때마다 작업이 실행돼요. 시작 에이전트는 인스턴스가 시작·재시작될 때, EC2Launch 서비스가 실행될 때, EC2Launch.exe run이 호출될 때 실행돼요.

Stage(단계) – EC2Launch v2 에이전트가 실행하는 작업의 논리적 그룹이에요. 일부 작업은 특정 단계에서만 실행될 수 있고, 다른 작업은 여러 단계에서 실행될 수 있어요. agent-config.yml을 쓸 때는 단계 목록과 각 단계에서 실행할 작업 목록을 지정해야 해요.

서비스는 다음 순서로 단계를 실행해요.

  • 1단계: Boot
  • 2단계: Network
  • 3단계: PreReady → PreReady 단계 완료 후 서비스가 Windows is ready 메시지를 Amazon EC2 콘솔로 보내요.
  • 4단계: PostReady → 사용자 데이터(user data)가 PostReady 단계에서 실행돼요. 일부 스크립트 버전은 agent-config.yml 파일의 PostReady 단계보다 먼저, 일부는 이후에 실행돼요.
    • agent-config.yml 전: YAML 사용자 데이터 v1.1, XML 사용자 데이터
    • agent-config.yml 후: YAML 사용자 데이터 v1.0(하위 호환용 레거시 버전)

사용자 데이터를 사용할 때는 시작 에이전트가 실행할 작업 목록을 지정해야 해요. 단계는 생략돼요. EC2Launch v2는 agent-config.yml과 사용자 데이터에서 지정한 순서대로 작업 목록을 실행해요. 단계는 순차적으로 실행돼요. 이전 단계가 완료된 후 다음 단계가 시작돼요. 작업도 순차적으로 실행돼요.

Task(작업) – 인스턴스에서 작업을 수행하도록 작업을 호출할 수 있어요. agent-config.yml 파일이나 사용자 데이터를 통해 작업을 구성할 수 있어요.

User data(사용자 데이터) – 인스턴스를 시작할 때 구성할 수 있는 데이터예요. 커스텀 AMI나 퀵스타트 AMI가 구성되는 방식을 동적으로 바꾸도록 사용자 데이터를 업데이트할 수 있어요. EC2Launch v2는 60kB 사용자 데이터 입력 길이를 지원해요. 사용자 데이터는 UserData 단계만 포함하므로 agent-config 파일 이후에 실행돼요.

EC2Launch v2 작업 개요

EC2Launch v2는 각 부팅에서 다음 작업을 수행할 수 있어요.

  • 인스턴스 정보를 렌더링하는 새 (선택적으로 커스터마이즈된) 배경 화면 설정
  • 로컬 컴퓨터에 생성되는 관리자 계정의 속성 설정
  • DNS 접미사를 검색 접미사 목록에 추가(기존에 없는 것만)
  • 추가 볼륨에 드라이브 문자 설정 및 사용 가능한 공간까지 확장
  • 구성에서 디스크로 파일 쓰기
  • EC2Launch v2 구성 파일 또는 user-data에 지정된 스크립트 실행(user-data 스크립트는 일반 텍스트 또는 압축되어 base64 형식으로 제공 가능)
  • 주어진 인자로 프로그램 실행
  • 컴퓨터 이름 설정
  • 인스턴스 정보를 Amazon EC2 콘솔로 전송
  • RDP 인증서 지문을 Amazon EC2 콘솔로 전송
  • 파티션되지 않은 공간을 포함하도록 OS 파티션 동적으로 확장
  • 사용자 데이터 실행
  • 메타데이터 서비스와 AWS KMS 서버에 도달하는 비영구적 정적 라우트 설정
  • 비부팅 파티션을 mbr 또는 gpt로 설정
  • Sysprep 후 Systems Manager 서비스 시작
  • ENA 설정 최적화
  • 이후 Windows 버전용 OpenSSH 활성화
  • Jumbo Frames 활성화
  • Sysprep이 EC2Launch v2로 실행되도록 설정
  • Windows 이벤트 로그 게시

EC2Launch v2 디렉터리 구조

  • 서비스 바이너리: %ProgramFiles%\Amazon\EC2Launch
  • 서비스 데이터(설정, 로그, 상태 파일): %ProgramData%\Amazon\EC2Launch
    • 참고: Windows는 기본적으로 C:\ProgramData 아래의 파일과 폴더를 숨겨요. 경로를 Windows 탐색기에 입력하거나 폴더 속성에서 숨김 파일 표시를 변경해야 해요.

%ProgramFiles%\Amazon\EC2Launch 디렉터리는 바이너리와 지원 라이브러리를 포함하며 다음 하위 디렉터리가 있어요.

  • settings – EC2LaunchSettingsUI.exe(파일 수정용 UI), YamlDotNet.dll
  • tools – ebsnvme-id.exe(인스턴스의 EBS 볼륨 메타데이터 검사 도구), AWSAcpiSpcrReader.exe(올바른 COM 포트 결정 도구), EC2LaunchEventMessage.dll
  • service – EC2LaunchService.exe(Windows 서비스 실행 파일), EC2AgentTelemetry.dll, EC2Launch.exe(메인 실행 파일), EC2LaunchAgentAttribution.txt

%ProgramData%\Amazon\EC2Launch 디렉터리는 다음 하위 디렉터리를 포함하고, 서비스가 만든 모든 데이터(로그, 구성, 상태)가 여기 저장돼요.

  • config – 서비스 구성 파일이 agent-config.yml로 저장돼요. 이 파일을 업데이트해 서비스가 실행하는 기본 작업을 수정·추가·제거할 수 있어요. 권한 상승을 막기 위해 이 디렉터리에 파일을 만들 권한은 관리자 계정으로 제한돼요.
  • log – 서비스 로그(agent.log)와 텔레메트리(telemetry.log)가 저장돼요. agent.log가 1MB에 도달하면 자동으로 로테이션되고 타임스탬프 형식의 백업 파일(예: agent-2026-03-02T18-56-39.188.log)이 만들어져요. 백업 로그 파일은 한 번에 하나만 유지돼요.
  • state – 서비스가 어떤 작업을 실행할지 결정하는 상태가 저장돼요. Sysprep 후 서비스가 이미 실행됐는지 나타내는 .run-once 파일이 있어요(그래서 빈도가 once인 작업은 다음 실행에서 건너뛰어요). state.json과 previous-state.json이 각 작업의 상태를 추적해요.
  • sysprep – Sysprep이 재사용 가능한 커스텀 Windows AMI를 만들 때 수행할 작업을 결정하는 파일이 저장돼요.
  • wallpaper – 배경 화면 이미지가 저장돼요.

텔레메트리 (Telemetry)

텔레메트리는 AWS가 요구사항을 더 잘 이해하고, 문제를 진단하고, AWS 서비스 경험을 개선하는 기능을 제공하는 데 도움이 되는 추가 정보예요. EC2Launch v2 2.1.592 이상 버전은 사용량 지표와 오류 같은 텔레메트리를 수집해요. 이 데이터는 EC2Launch v2가 실행되는 Amazon EC2 인스턴스에서 수집되며, AWS가 소유한 모든 Windows AMI를 포함해요.

수집되는 텔레메트리 유형:

  • 사용 정보 – 에이전트 명령, 설치 방법, 예약된 실행 빈도.
  • 오류 및 진단 정보 – 에이전트 설치 오류 코드, 실행 오류 코드, 오류 콜 스택.

버전 2.0.592~2.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
...

버전 2.2.63부터 EC2 Agent 텔레메트리 데이터는 JSON 객체로 형식화돼요.

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

텔레메트리는 기본적으로 활성화돼 있어요. 언제든 수집을 비활성화할 수 있어요.

인스턴스에서 텔레메트리 비활성화 – 시스템 환경 변수를 설정하거나 MSI로 설치를 수정할 수 있어요.

환경 변수로 비활성화(관리자로 실행):

setx /M EC2LAUNCH_TELEMETRY 0

MSI로 비활성화:

msiexec /i ".\AmazonEC2Launch.msi" Remove="Telemetry" /q

EC2Launch v2 관련 주제

  • 최신 EC2Launch v2 버전 설치
  • Windows 인스턴스용 EC2Launch v2 설정 구성
  • EC2Launch v2 시작 작업의 작업 정의
  • EC2Launch v2 에이전트 문제 해결
  • EC2Launch v2 버전 이력

더 알아보기