EC2Launch v2 시작 태스크에 대한 태스크 정의 - Amazon Elastic Compute Cloud
activateWindows enableJumboFrames enableOpenSsh executeProgramexecuteScriptextendRootPartition initializeVolumeoptimizeEna setAdminAccountsetDnsSuffix setHostName setWallpaper startSsmsysprepwriteFile

EC2Launch v2 시작 태스크에 대한 태스크 정의

EC2Launch v2가 시작 중 실행하는 태스크마다 자체 속성과 요구 사항 세트가 있습니다. 태스크 세부 정보에는 태스크가 실행되는 빈도(한 번 또는 항상), 에이전트 부팅 프로세스의 어느 단계에서 태스크가 실행되는지, 구문 및 YAML 문서 예에 대한 설정이 포함됩니다. 자세한 내용은 이 참조에 표시된 태스크 세부 정보를 검토하세요.

activateWindows

AWS KMS 서버 집합에 대해 Windows를 활성화합니다. 인스턴스가 기존 보유 라이선스 사용(BYOL)으로 감지되면 활성화를 건너뜁니다.

Frequency - once

AllowedStages - [PreReady]

Inputs -

activation: (맵)

type: (문자열) 사용할 활성화 유형, 으로 설정amazon

예

task: activateWindows
  inputs:
    activation:
    type: amazon

enableJumboFrames

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

Frequency — always

AllowedStages - [PostReady, UserData]

Inputs - none

예

task: enableJumboFrames

enableOpenSsh

Windows OpenSSH를 활성화하고 인스턴스의 퍼블릭 키를 인증된 키 폴더에 추가합니다.

Frequency - once

AllowedStages - [PreReady, UserData]

Inputs - none

예

다음 예에서는 인스턴스에서 OpenSSH를 활성화하고 인스턴스의 퍼블릭 키를 인증된 키 폴더에 추가하는 방법을 보여줍니다. 이 구성은 Windows Server 2019 이상 버전을 실행하는 인스턴스에서만 작동합니다.

task: enableOpenSsh

executeProgram

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

단계: PreReady, PostReady, UserData 단계에서 executeProgram 작업을 실행할 수 있습니다.

주파수: 구성 가능, 입력 참조.

입력

이 섹션에는 executeProgram 태스크가 실행할 하나 이상의 프로그램이 들어 있습니다(입력). 각 입력에는 다음과 같은 구성 가능한 속성이 포함될 수 있습니다.

주파수(문자열)

(필수) 다음 값 중 정확히 하나를 지정할 수 있습니다.

  • once

  • always

경로(문자열)

(필수) 실행할 실행 파일 경로입니다.

인수(문자열 목록)

(선택 사항) 프로그램에 입력으로 제공할 쉼표로 구분된 인수 목록입니다.

runAs(문자열)

(필수) 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 작업이 실행되는 프로그램의 런타임 오류 메시지를 포함합니다.

예시

다음 예는 executeProgram 작업이 있는 인스턴스의 로컬 디렉터리에서 실행 파일을 실행하는 방법을 보여줍니다.

예 1: 한 인수로 실행 파일 설정

이 예에서는 설치 실행 파일을 자동 모드로 실행하는 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

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

인라인(기본값)

EC2Launch v2 에이전트는 한 번에 하나씩(detach: false) 스크립트를 실행합니다. 이것이 기본 설정입니다.

참고

인라인 스크립트가 reset 또는 sysprep 명령을 내리면 해당 명령이 즉시 실행되고 에이전트가 재설정됩니다. 현재 태스크가 끝나면 에이전트가 추가 태스크를 실행하지 않고 종료됩니다.

예를 들어 명령을 실행하는 태스크 뒤에 startSsm 태스크(사용자 데이터 실행 후 기본적으로 포함됨)가 뒤따르는 경우 해당 태스크가 실행되지 않고 Systems Manager 서비스도 시작되지 않습니다.

분리됨

EC2Launch v2 에이전트는 다른 태스크(detach: true)와 동시에 스크립트를 실행합니다.

참고

분리된 스크립트가 reset 또는 sysprep 명령을 내리면 해당 명령은 실행되기 전에 에이전트가 완료될 때까지 기다립니다. ExecuteScript 이후의 태스크는 계속 실행됩니다.

단계: PreReady, PostReady, UserData 단계에서 executeScript 작업을 실행할 수 있습니다.

주파수: 구성 가능, 입력 참조.

입력

이 섹션에는 executeScript 태스크가 실행할 하나 이상의 스크립트가 들어 있습니다(입력). 각 입력에는 다음과 같은 구성 가능한 속성이 포함될 수 있습니다.

주파수(문자열)

(필수) 다음 값 중 정확히 하나를 지정할 수 있습니다.

  • once

  • always

유형(문자열)

(필수) 다음 값 중 정확히 하나를 지정할 수 있습니다.

  • batch

  • powershell

인수(문자열 목록)

(선택 사항) 쉘에 전달할 문자열 인수 목록입니다(PowerShell 스크립트에 전달하지 않음). type: batch에는 이 매개변수가 지원되지 않습니다. 인수가 전달되지 않은 경우 EC2Launch v2는 기본적으로 -ExecutionPolicy Unrestricted 인수를 추가합니다.

내용(문자열)

(필수) 스크립트 콘텐츠.

runAs(문자열)

(필수) 다음 값 중 정확히 하나를 지정할 수 있습니다.

  • admin

  • localSystem

분리(부울)

(선택 사항) EC2Launch v2 에이전트는 기본적으로 스크립트를 한 번에 하나씩(detach: false) 실행합니다. 스크립트를 다른 작업과 동시에 실행하려면 값을 true(detach: true)로 설정합니다.

참고

스크립트 종료 코드(3010 포함)는 detach가 true로 설정되면 아무런 효과가 없습니다.

출력

모든 작업은 로그 파일 항목을 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
executeScript 작업의 출력 파일
UserScript.ext

executeScript 작업이 실행한 스크립트를 포함합니다. 파일 확장자는 다음과 같이 executeScript 태스크의 type 파라미터에 지정한 스크립트 유형에 따라 달라집니다.

  • 유형이 batch인 경우 파일 확장자는 .bat입니다.

  • 유형이 powershell인 경우 파일 확장자는 .ps1입니다.

Output.tmp

executeScript 작업이 실행하는 스크립트의 런타임 출력을 포함합니다.

Err.tmp

executeScript 작업이 실행하는 스크립트의 런타임 오류 메시지를 포함합니다.

예시

다음 예에서는 executeScript 작업에서 인라인 스크립트를 실행하는 방법을 보여줍니다.

예 1: Hello world 출력 텍스트 파일

이 예에서는 PowerShell 스크립트를 실행하여 C: 드라이브에 “Hello world” 텍스트 파일을 만드는 executeScript 작업을 보여줍니다.

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
      content: |
        Get-Process | Out-File -FilePath C:\Process.txt
      runAs: localSystem
    - frequency: always
      type: batch
        content: |
        systeminfo
예 3: 재부팅을 통한 멱등성 시스템 구성

이 예에서는 멱등성 스크립트 실행을 통해 각 단계 사이에 재부팅하여 다음 시스템 구성을 수행하는 executeScript 작업을 보여 줍니다.

  • 컴퓨터 이름을 변경합니다.

  • 도메인에 컴퓨터를 결합합니다.

  • 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

루트 볼륨을 확장하여 디스크에서 사용 가능한 공간을 모두 사용합니다.

Frequency - once

AllowedStages - [Boot]

Inputs - none

예 

task: extendRootPartition

initializeVolume

인스턴스에 연결된 빈 볼륨을 활성화 및 분할되도록 초기화합니다. 시작 에이전트에서는 볼륨이 비어 있지 않은 것이 감지되면 초기화를 건너뜁니다. 볼륨의 처음 4KiB가 비어 있거나 볼륨에 Windows에서 인식 가능한 드라이브 레이아웃이 없으면 볼륨이 비어 있는 것으로 간주합니다.

letter 입력 파라미터는 드라이브가 이미 초기화되었는지 여부와 관계없이 이 태스크를 실행할 때 항상 적용됩니다.

initializeVolume에서는 다음과 같은 작업을 수행합니다.

  • 디스크의 offline 및 readonly 속성을 false로 설정합니다.

  • 파티션을 생성합니다. partition 입력 파라미터에 파티션 유형이 지정되지 않으면 다음과 같은 기본값이 적용됩니다.

    • 디스크 크기가 2TB 미만이면 파티션 유형을 mbr로 설정합니다.

    • 디스크 크기가 2TB 이상이면 파티션 유형을 gpt로 설정합니다.

  • 볼륨 형식을 NTFS로 지정합니다.

  • 볼륨 레이블을 다음과 같이 설정합니다.

    • name 입력 파라미터의 값을 사용합니다(지정된 경우).

    • 임시 볼륨이고 지정된 이름이 없으면 볼륨 레이블을 Temporary Storage Z로 설정합니다.

  • 임시 볼륨(Amazon EBS가 아닌 SSD 또는 HDD)이면 다음과 같은 내용으로 볼륨 루트에 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: EC2 인스턴스용 인스턴스 스토어 임시 블록 스토리지.

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

스테이지: PostReady 및 UserData 스테이지 동안 initializeVolume 태스크를 실행할 수 있습니다.

빈도: 항상입니다.

입력

다음과 같이 런타임 매개변수를 구성할 수 있습니다.

디바이스(맵 목록)

(조건부) 시작 에이전트에서 초기화하는 각 디바이스의 구성입니다. initialize 입력 파라미터가 devices로 설정되는 경우에 필요합니다.

  • 디바이스(문자열, 필수 사항) – 인스턴스 생성 중 디바이스를 식별합니다. 예: xvdb, xvdf 또는 \dev\nvme0n1.

  • 문자(문자열, 선택 사항) – 1자입니다. 할당할 드라이브 문자입니다.

  • 이름(문자열, 선택 사항) - 할당할 볼륨 이름입니다.

  • 파티션(문자열, 선택 사항) - 생성할 파티션 유형에 다음과 같은 값 중 하나를 지정하거나 볼륨 크기에 따라 시작 에이전트에서 기본값을 설정하도록 합니다.

    • mbr

    • gpt

초기화(문자열)

(필수) 다음 값 중 정확히 하나를 지정할 수 있습니다.

  • all

  • devices

예시

다음 예에서는 initializeVolume 태스크의 샘플 입력 구성을 보여줍니다.

예 1: 인스턴스에 대한 2개 볼륨 초기화

이 예에서는 인스턴스에 대한 2개의 보조 볼륨을 초기화하는 initializeVolume 태스크를 보여줍니다. 예에서 이름이 DataVolume2인 디바이스는 임시 디바이스입니다.

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 볼륨을 초기화하는 initializeVolume 태스크를 보여줍니다.

task: initializeVolume
inputs:
  initialize: all

optimizeEna

현재 인스턴스 유형에 따라 ENA 설정을 최적화합니다. 인스턴스를 재부팅할 수 있습니다.

Frequency — always

AllowedStages - [PostReady, UserData]

Inputs - none

예 

task: optimizeEna

setAdminAccount

로컬 시스템에 생성된 기본 관리자 계정의 속성을 설정합니다.

Frequency - once

AllowedStages - [PreReady]

Inputs -

name: (문자열) 관리자 계정의 이름

password: (맵)

type: (문자열) 암호 설정 전략. static, random 또는 doNothing

data: (문자열) type 필드가 정적인 경우 데이터 저장

예

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

setDnsSuffix

검색 접미사 목록에 DNS 접미사를 추가합니다. 아직 존재하지 않는 접미사만 목록에 추가됩니다. 시작 에이전트가 DNS 접미사를 설정하는 방법에 대한 자세한 내용은 EC2 Windows 시작 에이전트용 DNS 접미사 구성 섹션을 참조하세요.

Frequency — always

AllowedStages - [PreReady]

Inputs -

suffixes: (문자열 목록) 하나 이상의 유효한 DNS 접미사 목록. 유효한 대체 변수는 $REGION 및 $AZ

예

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

setHostName

컴퓨터의 호스트 이름을 사용자 지정 문자열, 또는 hostName이 지정되지 않은 경우 프라이빗 IPv4 주소로 설정합니다.

Frequency — always

AllowedStages - [PostReady, UserData]

Inputs -

hostName: (문자열) 선택적 호스트 이름입니다. 이 이름은 다음과 같은 형식이어야 합니다.

  • 15자 이하여야 합니다.

  • 영숫자(a-z, A-Z, 0-9) 및 하이픈(-) 문자만 포함해야 합니다.

  • 전체가 숫자 문자로 구성되어서는 안 됩니다.

reboot: (부울) 호스트 이름이 변경될 때 재부팅이 허용되는지 여부를 나타냅니다.

예

task: setHostName
inputs:
  reboot: true

setWallpaper

setwallpaper.lnk를 제외한 각 기존 사용자의 시작 폴더에 Default User 바로 가기 파일을 생성합니다. 이 바로 가기 파일은 사용자가 인스턴스를 부팅한 후 처음으로 로그인할 때 실행됩니다. 이 파일은 인스턴스 속성을 표시하는 사용자 지정 월페이퍼를 사용해 인스턴스를 설정합니다.

바로 가기 파일 경로는 다음과 같습니다.

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

setWallpaper 태스크를 제거해도 이 바로 가기 파일은 삭제되지 않습니다. 자세한 내용은 setWallpaper 태스크를 사용하지 않지만 재부팅 시 월페이퍼 재설정 단원을 참조하십시오.

스테이지: PreReady 및 UserData 스테이지 중에 배경화면을 구성할 수 있습니다.

빈도: always

월페이퍼 구성

다음 설정을 사용하여 월페이퍼를 구성할 수 있습니다.

입력

제공하는 입력 파라미터와 월페이퍼를 구성하기 위해 설정할 수 있는 속성:

속성(문자열 목록)

(선택 사항) 월페이퍼에 다음 속성 중 하나 이상을 추가할 수 있습니다.

  • architecture

  • availabilityZone

  • hostName

  • instanceId

  • instanceSize

  • memory

  • network

  • privateIpAddress

  • publicIpAddress

instanceTags

(선택 사항) 이 설정에 대해 다음 옵션 중 정확히 하나를 사용할 수 있습니다.

  • AllTags(문자열) - 월페이퍼에 모든 인스턴스 태그를 추가합니다.

    instanceTags: AllTags

  • instanceTags(문자열 목록) – 월페이퍼에 추가할 인스턴스 태그 이름의 목록을 지정합니다. 예:

    instanceTags:
  - Tag 1
  - Tag 2
경로(문자열)

(필수) 월페이퍼 이미지에 사용할 로컬.jpg 형식 이미지 파일의 파일 이름 경로입니다.

예

다음 예제에서는 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) 서비스를 시작합니다.

Frequency — always

AllowedStages - [PostReady, UserData]

Inputs - none

예

task: startSsm

sysprep

서비스 상태를 재설정하고, unattend.xml을 업데이트하고, RDP를 비활성화하고, Sysprep을 실행합니다. 이 태스크는 다른 모든 태스크가 완료된 후에만 실행됩니다.

Frequency - once

AllowedStages - [UserData]

Inputs -

clean: (부울) Sysprep을 실행하기 전에 인스턴스 로그 정리

shutdown: (부울) Sysprep을 실행 한 후 인스턴스 종료

예

task: sysprep
inputs:
clean: true
shutdown: true

writeFile

대상에 파일을 씁니다.

Frequency - Inputs 참조

AllowedStages - [PostReady, UserData]

Inputs -

frequency: (문자열) once 또는 always 중 하나

destination: (문자열) 콘텐츠를 쓸 경로

content: (문자열) 대상에 쓸 텍스트

예

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