EC2Launch v2 시작 작업의 작업 정의(task definitions)

EC2Launch v2가 시작(launch) 또는 부팅(starup) 중 실행하는 각 작업(task)은 고유한 속성과 요구 사항을 가져요. 작업 세부 정보에는 작업이 실행되는 빈도(한 번(once) 또는 항상(always)), 에이전트 부팅 프로세스의 어느 단계에서 실행되는지, 구문, YAML 문서 예제가 포함됩니다. 자세한 내용은 이 참조 자료의 작업 세부 정보를 검토하세요.

출처: 문서

본문

EC2Launch v2 작업 목록

activateWindows
enableJumboFrames
enableOpenSsh
executeProgram
executeScript
extendRootPartition
initializeVolume
optimizeEna
setAdminAccount
setDnsSuffix
setHostName
setWallpaper
startSsm
sysprep
writeFile

activateWindows

AWS KMS 서버 집합에 대해 Windows를 활성화합니다. 인스턴스가 Bring-Your-Own-License(BYOL)로 감지되면 활성화를 건너뜁니다.

빈도(Frequency) — once
허용 단계(AllowedStages) — [PreReady]
입력(Inputs) — activation: (map) — type: (string) 사용할 활성화 유형. amazon으로 설정.

예제

task: activateWindows
  inputs:
    activation:
    type: amazon

enableJumboFrames

네트워크 어댑터의 최대 전송 단위(MTU)를 늘리는 **점보 프레임(Jumbo Frames)**을 활성화합니다. 자세한 내용은 "점보 프레임(9001 MTU)"을 참고하세요.

빈도 — always
허용 단계 — [PostReady, UserData]
입력 — 없음

예제

task: enableJumboFrames

enableOpenSsh

Windows OpenSSH를 활성화하고 인스턴스의 공개 키를 authorized keys 폴더에 추가합니다.

빈도 — once
허용 단계 — [PreReady, UserData]
입력 — 없음

예제 — 다음 예제는 인스턴스에서 OpenSSH를 활성화하고 인스턴스 공개 키를 authorized keys 폴더에 추가하는 방법을 보여줘요. 이 구성은 Windows Server 2019 이상을 실행하는 인스턴스에서만 동작합니다.

task: enableOpenSsh

executeProgram

선택적 인수와 지정된 빈도로 프로그램을 실행합니다.

단계: PreReady, PostReady, UserData 단계에서 실행할 수 있어요.
빈도: 구성 가능. Inputs 참고.

입력

이 실행 프로그램 작업이 실행할(receive inputs) 하나 이상의 프로그램을 포함합니다. 각 입력은 다음 구성 설정을 포함할 수 있어요.

frequency (string, 필수) — 다음 중 정확히 하나를 지정: once 또는 always
path (string, 필수) — 실행할 실행 파일의 파일 경로
arguments (string 목록, 선택) — 프로그램에 입력으로 제공할 쉼표로 구분된 인수 목록
runAs (string, 필수) — localSystem으로 설정해야 함

출력

모든 작업은 로그 파일 항목을 agent.log 파일에 기록해요. executeProgram 작업의 추가 출력은 다음과 같이 동적으로 이름 지어진 폴더에 별도로 저장됩니다.

%LocalAppData%\Temp\ EC2Launch######### \ outputfilename.tmp

출력 파일의 정확한 경로는 agent.log 파일에 포함됩니다. 예:

Program file is created at: C:\Windows\system32\config\systemprofile\AppData\Local\Temp\EC2Launch123456789\ExecuteProgramInputs.tmp
Output file is created at: C:\Windows\system32\config\systemprofile\AppData\Local\Temp\EC2Launch123456789\Output.tmp
Error file is created at: C:\Windows\system32\config\systemprofile\AppData\Local\Temp\EC2Launch123456789\Err.tmp

executeProgram 작업의 출력 파일:

ExecuteProgramInputs.tmp — 실행 파일의 경로와 executeProgram 작업이 실행할 때 전달하는 모든 입력 파라미터를 포함합니다.
Output.tmp — executeProgram 작업이 실행하는 프로그램의 런타임 출력을 포함합니다.
Err.tmp — 실행하는 프로그램의 런타임 오류 메시지를 포함합니다.

예제

다음 예제는 executeProgram 작업으로 인스턴스의 로컬 디렉터리에서 실행 파일을 실행하는 방법을 보여줘요.

예제 1: 하나의 인수로 setup 실행 파일

이 예제는 조용한 모드(quiet mode)로 setup 실행 파일을 실행하는 executeProgram 작업을 보여줘요.

task: executeProgram
  inputs:
    - frequency: always
      path: C:\Users\Administrator\Desktop\setup.exe
      arguments: ['-quiet']

예제 2: 두 인수를 가진 VLC 실행 파일

이 예제는 두 인자를 입력 파라미터로 전달해 VLC 실행 파일을 실행하는 executeProgram 작업을 보여줘요.

task: executeProgram
  inputs:
    - frequency: always
      path: C:\vlc-3.0.11-win64.exe 
      arguments: ['/L=1033','/S']
      runAs: localSystem

executeScript

선택적 인수와 지정된 빈도로 스크립트를 실행합니다. 스크립트 동작은 에이전트가 스크립트를 실행하는 모드(인라인(inline) 또는 분리(detached))에 따라 달라져요.

인라인(Inline, 기본값) — EC2Launch v2 에이전트는 스크립트를 한 번에 하나씩 실행해요(detach: false). 기본 설정입니다.

참고 — 인라인 스크립트가 reset 또는 sysprep 명령을 내리면 즉시 실행되어 에이전트를 리셋합니다. 현재 작업이 끝나면 에이전트는 더 이상 어떤 작업도 실행하지 않고 종료돼요. 예를 들어 그 명령을 내린 작업 뒤에 startSsm 작업(사용자 데이터 실행 후 기본적으로 포함)이 이어졌더라도, 그 작업은 실행되지 않고 Systems Manager 서비스는 시작되지 않습니다.

분리(Detached) — EC2Launch v2 에이전트는 다른 작업과 동시에 스크립트를 실행해요(detach: true).

참고 — 분리 스크립트가 reset 또는 sysprep 명령을 내리면 그 명령은 에이전트가 끝날 때까지 기다렸다가 실행됩니다. executeScript 이후의 작업들은 계속 실행됩니다.

단계: PreReady, PostReady, UserData 단계에서 실행할 수 있어요.
빈도: 구성 가능. Inputs 참고.

입력

frequency (string, 필수) — once 또는 always 중 정확히 하나를 지정
type (string, 필수) — batch 또는 powershell 중 정확히 하나를 지정
arguments (string 목록, 선택) — 셸에 전달할 문자열 인수 목록(정확히 PowerShell 스크립트가 아님). 이 파라미터는 type: batch에선 지원되지 않아요. 인수를 전달하지 않으면 EC2Launch v2가 기본적으로 -ExecutionPolicy Unrestricted 인수를 추가합니다.
content (string, 필수) — 스크립트 내용
runAs (string, 필수) — admin 또는 localSystem 중 정확히 하나를 지정
detach (Boolean, 선택) — 에이전트는 기본적으로 스크립트를 한 번에 하나씩 실행합니다(detach: false). 다른 작업과 동시에 실행하려면 true로 설정합니다(detach: true).

참고 — detach가 true로 설정되면 스크립트 종료 코드(3010 포함)는 아무 효과가 없어요.

출력

모든 작업은 agent.log에 기록하며, executeScript 작업이 실행하는 스크립트의 추가 출력은 다음과 같이 동적으로 이름 지어진 폴더에 별도 저장됩니다.

%LocalAppData%\Temp\ EC2Launch######### \ outputfilename.ext

출력 파일의 정확한 경로는 agent.log에 포함됩니다. 예:

Program file is created at: C:\Windows\system32\config\systemprofile\AppData\Local\Temp\EC2Launch123456789\UserScript.ps1
Output file is created at: C:\Windows\system32\config\systemprofile\AppData\Local\Temp\EC2Launch123456789\Output.tmp
Error file is created at: C:\Windows\system32\config\systemprofile\AppData\Local\Temp\EC2Launch123456789\Err.tmp

실행 스크립트 작업의 출력 파일:

UserScript.ext — executeScript 작업이 실행한 스크립트를 포함합니다. 파일 확장자는 type 파라미터에 지정한 스크립트 유형에 따라 달라져요: type이 batch면 .bat, powershell이면 .ps1.
Output.tmp — 실행하는 스크립트의 런타임 출력.
Err.tmp — 실행하는 스크립트의 런타임 오류 메시지.

예제

예제 1: "Hello world" 출력 텍스트 파일 — C: 드라이브에 "Hello world" 텍스트 파일을 만들도록 PowerShell 스크립트를 실행하는 예제입니다.

task: executeScript
  inputs:
    - frequency: always
      type: powershell
      runAs: admin
      content: |-
        New-Item -Path 'C:\PowerShellTest.txt' -ItemType File
        Set-Content 'C:\PowerShellTest.txt' "Hello world"

예제 2: 두 스크립트 실행 — executeScript 작업이 스크립트를 여럿 실행할 수 있고, 스크립트 유형이 반드시 같을 필요는 없음을 보여줘요. 첫 번째 스크립트(type: powershell)는 인스턴스에서 현재 실행 중인 프로세스 요약을 C: 드라이브의 텍스트 파일에 쓰고, 두 번째 스크립트(batch)는 시스템 정보를 Output.tmp 파일에 씁니다.

task: executeScript
  inputs:
    - frequency: always
      type: powershell
      runAs: localSystem
      content: |
        Get-Process | Out-File -FilePath C:\Process.txt
    - frequency: always
      type: batch
      runAs: localSystem
      content: |
        systeminfo

예제 3: 재부팅이 있는 멱등적 시스템 구성 — 각 단계 사이에 재부팅을 두고 시스템 구성을 수행하는 멱등적(idempotent) 스크립트를 실행하는 예제입니다.

컴퓨터 이름 바꾸기
컴퓨터를 도메인에 조인
Telnet 활성화

각 작업이 한 번만 실행되도록 보장해 재부팅 루프를 방지하고 스크립트를 멱등적으로 만듭니다.

task: executeScript
  inputs:
    - frequency: always
      type: powershell
      runAs: localSystem
      content: |-
        $name = $env:ComputerName
        if ($name -ne $desiredName) {
          Rename-Computer -NewName $desiredName
          exit 3010
        }
        $domain = Get-ADDomain
        if ($domain -ne $desiredDomain) 
        {
          Add-Computer -DomainName $desiredDomain
          exit 3010
        }
        $telnet = Get-WindowsFeature -Name Telnet-Client
        if (-not $telnet.Installed)
        {
          Install-WindowsFeature -Name "Telnet-Client"
          exit 3010 
        }

extendRootPartition

루트 볼륨을 디스크의 사용 가능한 전체 공간으로 확장합니다.

빈도 — once
허용 단계 — [Boot]
입력 — 없음

예제

task: extendRootPartition

initializeVolume

인스턴스에 연결된 빈 볼륨을 초기화해 활성화하고 파티셔닝합니다. 시작 에이전트는 볼륨이 비어 있지 않다고 감지하면 초기화를 건너뜁니다. 볼륨의 첫 4 KiB가 비어 있거나, 볼륨에 Windows가 인식하는 드라이브 레이아웃이 없으면 빈 것으로 간주됩니다. letter 입력 파라미터는 드라이브가 이미 초기화되었는지와 무관하게 이 작업이 실행될 때 항상 적용됩니다.

initializeVolume 작업은 다음 작업을 수행합니다.

디스크 속성 offline과 readonly를 false로 설정합니다.
파티션을 만듭니다. partition 입력 파라미터에 파티션 유형을 지정하지 않으면 다음 기본값이 적용됩니다.
- 디스크 크기가 2 TB보다 작으면 파티션 유형을 mbr로 설정
- 디스크 크기가 2 TB 이상이면 파티션 유형을 gpt로 설정
볼륨을 NTFS로 포맷합니다.
볼륨 레이블을 다음과 같이 설정합니다.
- name 입력 파라미터 값을 지정했다면 그 값 사용
- 볼륨이 임시(ephemeral)이고 이름이 지정되지 않았다면 볼륨 레이블을 Temporary Storage Z로 설정
- 볼륨이 임시(SSD 또는 HDD — Amazon EBS가 아님)이면 볼륨 루트에 다음 내용의 Important.txt 파일 생성:

This is an 'Instance Store' disk and is provided at no additional charge.

*This disk offers increased performance since it is local to the host
*The number of Instance Store disks available to an instance vary by instance type
*DATA ON THIS DRIVE WILL BE LOST IN CASES OF IMPAIRMENT OR STOPPING THE INSTANCE. PLEASE ENSURE THAT ANY IMPORTANT DATA IS BACKED UP FREQUENTLY

For more information, please refer to: Instance store temporary block storage for EC2 instances.

드라이브 문자를 letter 입력 파라미터에 지정된 값으로 설정합니다.

단계: PostReady, UserData 단계에서 실행할 수 있어요.
빈도: always

입력 — 런타임 파라미터를 다음과 같이 구성할 수 있어요.

devices (map 목록, 조건부) — 시작 에이전트가 초기화하는 각 장치의 구성. initialize 입력 파라미터가 devices로 설정된 경우 필수입니다.
- device (string, 필수) — 인스턴스 생성 중 장치를 식별합니다. 예: xvdb, xvdf, \dev\nvme0n1
- letter (string, 선택) — 한 글자. 할당할 드라이브 문자.
- name (string, 선택) — 할당할 볼륨 이름.
- partition (string, 선택) — 만들 파티션 유형 값(mbr 또는 gpt) 중 하나를 지정하거나, 볼륨 크기에 따라 시작 에이전트가 기본값을 정하도록 둡니다.
initialize (string, 필수) — all 또는 devices 중 정확히 하나를 지정

예제

예제 1: 인스턴스에서 두 볼륨 초기화 — 인스턴스에서 두 보조 볼륨을 초기화합니다. 예제의 DataVolume2 장치는 임시(ephemeral)입니다.

task: initializeVolume
inputs:
  initialize: devices
  devices:
  - device: xvdb
    name: DataVolume1
    letter: D
    partition: mbr
  - device: /dev/nvme0n1
    name: DataVolume2
    letter: E
    partition: gpt

예제 2: 인스턴스에 연결된 EBS 볼륨 초기화 — 인스턴스에 연결된 모든 빈 EBS 볼륨을 초기화합니다.

task: initializeVolume
inputs:
  initialize: all

optimizeEna

현재 인스턴스 유형을 기준으로 ENA 설정을 최적화하며, 인스턴스를 재부팅할 수 있어요.

빈도 — always
허용 단계 — [PostReady, UserData]
입력 — 없음

예제

task: optimizeEna

setAdminAccount

로컬 머신에 생성되는 기본 Administrator 계정의 속성을 설정합니다.

빈도 — once
허용 단계 — [PreReady]
입력 — name: (string) Administrator 계정 이름. password: (map) — type: (string) static, random, doNothing 중 하나로 암호 설정 전략. data: (string) type 필드가 static일 때 데이터를 저장.

예제

task: setAdminAccount
inputs:
  name: Administrator
  password:
  type: random

setDnsSuffix

검색 접미사 목록에 DNS 접미사를 추가합니다. 이미 존재하는 접미사만 목록에 추가됩니다. 시작 에이전트가 DNS 접미사를 설정하는 방법은 "EC2 Windows 시작 에이전트용 DNS 접미사 구성"을 참고하세요.

빈도 — always
허용 단계 — [PreReady]
입력 — suffixes: (string 목록) 하나 이상의 유효한 DNS 접미사 목록. 유효한 대체 변수는 $REGION과 $AZ.

예제

task: setDnsSuffix
inputs:
  suffixes:
  - $REGION.ec2-utilities.amazonaws.com

setHostName

컴퓨터의 호스트 이름을 사용자 지정 문자열로 설정하거나, hostName이 지정되지 않으면 사설 IPv4 주소로 설정합니다.

빈도 — always
허용 단계 — [PostReady, UserData]
입력 — hostName: (string, 선택) 다음 형식이어야 하는 호스트 이름:
- 15자 이하
- 영숫자(a-z, A-Z, 0-9)와 하이픈(-) 문자만 포함
- 숫자 문자로만 구성되면 안 됨
- reboot: (boolean) 호스트 이름이 변경될 때 재부팅이 허용되는지 여부를 나타냄

예제

task: setHostName
inputs:
  reboot: true

setWallpaper

Default User를 제외한 각 기존 사용자의 시작 폴더에 setwallpaper.lnk 바로 가기 파일을 만듭니다. 이 바로 가기 파일은 인스턴스 부팅 후 사용자가 처음 로그인할 때 실행되며, 인스턴스 속성을 표시하는 사용자 지정 배경화면으로 인스턴스를 설정합니다.

바로 가기 파일 경로:

$env:SystemDrive/Users/<user>/AppData/Roaming/Microsoft/Windows/Start Menu/Programs/Startup/setwallpaper.lnk

참고 — setWallpaper 작업을 제거해도 이 바로 가기 파일은 삭제되지 않아요. 자세한 내용은 "setWallpaper 작업이 활성화되지 않았는데 배경화면이 재부팅 시 리셋됨"을 참고하세요.

단계: PreReady와 UserData 단계에서 배경화면을 구성할 수 있어요.
빈도: always

입력 — 배경화면을 구성하는 데 제공하는 입력 파라미터와 설정할 수 있는 속성:

path (string, 필수) — 배경화면 이미지로 사용할 로컬 .jpg 이미지 파일의 파일명 경로
attributes (string 목록, 선택) — 배경화면에 다음 속성 중 하나 이상을 추가할 수 있어요: architecture, availabilityZone, hostName, instanceId, instanceSize, privateIpAddress, publicIpAddress, ipv6Address
instanceTags (선택) — 이 설정에는 다음 옵션 중 정확히 하나를 사용할 수 있어요.
- AllTags (string) — 모든 인스턴스 태그를 배경화면에 추가

instanceTags: AllTags

instanceTags (string 목록) — 추가할 인스턴스 태그 이름 목록을 지정. 예:

instanceTags:
  - Tag 1
  - Tag 2

예제 — 다음 예제는 배경화면 배경 이미지의 파일 경로, Tag 1과 Tag 2라는 인스턴스 태그, 그리고 호스트 이름·인스턴스 ID·사설·공개 IP 주소를 포함하는 속성을 설정하는 배경화면 구성 입력을 보여줘요.

task: setWallpaper
inputs:
  path: C:\ProgramData\Amazon\EC2Launch\wallpaper\Ec2Wallpaper.jpg
  attributes:
  - hostName
  - instanceId
  - privateIpAddress
  - publicIpAddress
  instanceTags:
  - Tag 1
  - Tag 2

참고 — 배경화면에 태그를 표시하려면 메타데이터에서 태그를 활성화해야 해요. 인스턴스 태그와 메타데이터에 대한 자세한 내용은 "인스턴스 메타데이터로 EC2 인스턴스 태그 보기"를 참고하세요.

startSsm

Sysprep 후 Systems Manager(SSM) 서비스를 시작합니다.

빈도 — always
허용 단계 — [PostReady, UserData]
입력 — 없음

예제

task: startSsm

sysprep

서비스 상태를 리셋하고, unattend.xml을 업데이트하고, RDP를 비활성화하고, Sysprep을 실행합니다. 이 작업은 다른 모든 작업이 완료된 후에만 실행됩니다.

빈도 — once
허용 단계 — [UserData]
입력 — clean: (boolean) Sysprep 실행 전 인스턴스 로그를 정리. shutdown: (boolean) Sysprep 실행 후 인스턴스를 종료.

예제

task: sysprep
inputs:
clean: true
shutdown: true

writeFile

파일을 대상에 기록합니다.

빈도 — Inputs 참고
허용 단계 — [PostReady, UserData]
입력 — frequency: (string) once 또는 always. destination: (string) 내용을 쓸 경로. content: (string) 대상에 쓸 텍스트.

예제

task: writeFile
inputs:
  - frequency: once
  destination: C:\Users\Administrator\Desktop\booted.txt
  content: Windows Has Booted

더 알아보기 (Learn more)

EC2Launch v2 구성(Configure EC2Launch v2)과 EC2Launch v2 문제 해결(Troubleshoot EC2Launch v2) 문서를 확인하세요.