Configure EC2Launch v2 settings for Windows instances

This section contains information about how to configure settings for EC2Launch v2.

Change settings using the EC2Launch v2 settings dialog box

The following is an example configuration YAML file created from the settings entered in the EC2Launch dialog.

version: 1.0
config:
  - stage: boot
	tasks:
      - task: extendRootPartition
  - stage: preReady
    tasks:
      - task: activateWindows
        inputs:
          activation:
            type: amazon
      - task: setDnsSuffix
        inputs:
          suffixes:
            - $REGION.ec2-utilities.amazonaws.com
      - task: setAdminAccount
        inputs:
          password:
            type: random
      - task: setWallpaper
        inputs:
          path: C:\ProgramData\Amazon\EC2Launch\wallpaper\Ec2Wallpaper.jpg
          attributes:
            - hostName
            - instanceId
            - privateIpAddress
            - publicIpAddress
            - instanceSize
            - availabilityZone
            - architecture
            - memory
            - network
  - stage: postReady
    tasks:
      - task: startSsm

Configure EC2Launch v2 using the CLI

You can use the Command Line Interface (CLI) to configure your EC2Launch settings and manage the service. The following section contains descriptions and usage information for the CLI commands that you can use to manage EC2Launch v2.

collect-logs

Collects log files for EC2Launch, zips the files, and places them in a specified directory.

Example

ec2launch collect-logs -o C:\Mylogs.zip

Usage

ec2launch collect-logs [flags]

Flags

-h, --help

help for collect-logs

-o, --output string

path to zipped output log files

get-agent-config

Prints agent-config.yml in the format specified (JSON or YAML). If no format is specified, agent-config.yml is printed in the format previously specified.

Example

ec2launch get-agent-config -f json

Example 2

The following PowerShell commands show how to edit and save the agent-config file in JSON format.

$config = & "$env:ProgramFiles/Amazon/EC2Launch/EC2Launch.exe" --format json | ConvertFrom-Json
$jumboFrame =@"
{
   "task": "enableJumboFrames"
}
"@
$config.config | %{if($_.stage -eq 'postReady'){$_.tasks += (ConvertFrom-Json -InputObject $jumboFrame)}}
$config | ConvertTo-Json -Depth 6 | Out-File -encoding UTF8
$env:ProgramData/Amazon/EC2Launch/config/agent-config.yml

Usage

ec2launch get-agent-config [flags]

Flags

-h, --help

help for get-agent-config

-f, --format string

output format of agent-config file: json, yaml

list-volumes

Lists all of the storage volumes attached to the instance, including ephemeral and EBS volumes.

Example

ec2launch list-volumes

Usage

ec2launch list-volumes

Flags

-h, --help

help for list-volumes

reset

The main goal of this task is to reset the agent for the next time that it runs. To do that, the reset command deletes all of the agent state data for EC2Launch v2 from the local EC2Launch directory (see EC2Launch v2 directory structure). Reset optionally deletes the service and Sysprep logs.

Script behavior depends on what mode the agent runs the scripts in – inline, or detached.

Example

ec2launch reset -c

Usage

ec2launch reset [flags]

Flags

-c, --clean

cleans instance logs before reset

-h, --help

help for reset

run

Runs EC2Launch v2.

Example

ec2launch run

Usage

ec2launch run [flags]

Flags

-h, --help

help for run

status

Gets the status of the EC2Launch v2 agent. Optionally blocks the process until the agent is finished. The process exit code determines the agent state:

Example:

ec2launch status -b

Usage

ec2launch status [flags]

Flags

-b,--block

blocks the process until the agent finishes running

-h,--help

help for status

sysprep

The main goal of this task is to reset the agent for the next time that it runs. To do that, the sysprep command resets the agent state, updates the unattend.xml file, disables RDP, and runs Sysprep.

Script behavior depends on what mode the agent runs the scripts in – inline, or detached.

Example:

ec2launch sysprep

Usage

ec2launch sysprep [flags]

Flags

-c,--clean

cleans instance logs before sysprep

-h,--help

help for Sysprep

-s,--shutdown

shuts down the instance after sysprep

validate

Validates the agent-config file C:\ProgramData\Amazon\EC2Launch\config\agent-config.yml.

Example

ec2launch validate

Usage

ec2launch validate [flags]

Flags

-h , --help

help for validate

version

Gets the executable version.

Example

ec2launch version

Usage

ec2launch version [flags]

Flags

-h, --help

help for version

wallpaper

Sets new wallpaper to the wallpaper path that is provided (.jpg file), and displays the selected instance details.

Syntax

ec2launch wallpaper ^
--path="C:\ProgramData\Amazon\EC2Launch\wallpaper\Ec2Wallpaper.jpg" ^
--all-tags ^
--attributes=hostName,instanceId,privateIpAddress,publicIpAddress,instanceSize,availabilityZone,architecture,memory,network

Inputs

EC2Launch v2 task configuration

This section includes the configuration schema, tasks, details, and examples for agent-config.yml and user data.

Schema: agent-config.yml

The structure of the agent-config.yml file is shown below. Note that a task cannot be repeated in the same stage. For task properties, see the task descriptions that follow.

Document structure: agent-config.yml

JSON

{
	"version": "1.0",
	"config": [
		{
			"stage": "string",
			"tasks": [
				{
					"task": "string",
					"inputs": {
						...
					}
				},
				...
			]
		},
		...
	]
}

YAML

version: 1.0
config:
- stage: string
  tasks:
  - task: string
	inputs:
	  ...
  ...
...

Example: agent-config.yml

The following example shows settings for the agent-config.yml configuration file.

version: 1.0
config:
- stage: boot
  tasks:
  - task: extendRootPartition
- stage: preReady
  tasks:
  - task: activateWindows
    inputs:
      activation:
        type: amazon
  - task: setDnsSuffix
    inputs:
      suffixes:
      - $REGION.ec2-utilities.amazonaws.com
  - task: setAdminAccount
    inputs:
      password:
        type: random
  - task: setWallpaper
    inputs:
      path: C:\ProgramData\Amazon\EC2Launch\wallpaper\Ec2Wallpaper.jpg
      attributes:
      - hostName
      - instanceId
      - privateIpAddress
      - publicIpAddress
      - instanceSize
      - availabilityZone
      - architecture
      - memory
      - network
- stage: postReady
  tasks:
  - task: startSsm

Configure EC2Launch v2 user data scripts that run during launch or reboot

The following JSON and YAML examples show the document structure for user data. Amazon EC2 parses each task named in the tasks array that you specify in the document. Each task has its own set of properties and requirements. For details, see the Task definitions for EC2Launch v2 startup tasks.

Document structure: user data

JSON

{
	"version": "1.1",
	"tasks": [
		{
			"task": "string",
			"inputs": {
				...
			},
		},
		...
	]
}

YAML

version: 1.1
tasks:
- task: string
  inputs:
    ...
...

Example: user data

For more information about user data, see How Amazon EC2 handles user data for Windows instances.

The following YAML document example shows a PowerShell script that EC2Launch v2 runs as user data to create a file.

version: 1.1
tasks:
- task: executeScript
  inputs:
  - frequency: always
    type: powershell
    runAs: localSystem
    content: |-
      New-Item -Path 'C:\PowerShellTest.txt' -ItemType File

You can use an XML format for the user data that's compatible with previous versions of the launch agent. EC2Launch v2 runs the script as an executeScript task in the UserData stage. To conform with EC2Launch v1 and EC2Config behavior, the user data script runs as an attached/inline process by default.

You can add optional tags to customize how your script runs. For example, to run the user data script when the instance reboots in addition to one time when the instance launches, you can use the following tag:

<persist>true</persist>

Example:

<powershell>
  $file = $env:SystemRoot + "\Temp" + (Get-Date).ToString("MM-dd-yy-hh-mm")
  New-Item $file -ItemType file
</powershell>
<persist>true</persist>

You can specify one or more PowerShell arguments with the <powershellArguments> tag. If no arguments are passed, EC2Launch v2 adds the following argument by default: -ExecutionPolicy Unrestricted.

Example:

<powershell>
  $file = $env:SystemRoot + "\Temp" + (Get-Date).ToString("MM-dd-yy-hh-mm")
  New-Item $file -ItemType file
</powershell>
<powershellArguments>-ExecutionPolicy Unrestricted -NoProfile -NonInteractive</powershellArguments>

To run an XML user data script as a detached process, add the following tag to your user data.

<detach>true</detach>

Example:

<powershell>
  $file = $env:SystemRoot + "\Temp" + (Get-Date).ToString("MM-dd-yy-hh-mm")
  New-Item $file -ItemType file
</powershell>
<detach>true</detach>

Change log: user data

The following table lists changes for user data, and cross-references them to the EC2Launch v2 agent version that applies.

* When used with the default agent-config.yml file.

EC2Launch v2 exit codes and reboots

You can use EC2Launch v2 to define how exit codes are handled by your scripts. By default, the exit code of the last command that is run in a script is reported as the exit code for the entire script. For example, if a script includes three commands and the first command fails but the following ones succeed, the run status is reported as success because the final command succeeded.

If you want a script to reboot an instance, then you must specify exit 3010 in your script, even when the reboot is the last step in your script. exit 3010 instructs EC2Launch v2 to reboot the instance and call the script again until it returns an exit code that is not 3010, or until the maximum reboot count has been reached. EC2Launch v2 permits a maximum of 5 reboots per task. If you attempt to reboot an instance from a script by using a different mechanism, such as Restart-Computer, then the script run status will be inconsistent. For example, it may get stuck in a restart loop or not perform the restart.

If you are using an XML user data format that is compatible with older agents, the user data may run more times than you intend it to. For more information, see Service runs user data more than once in the Troubleshooting section.

EC2Launch v2 and Sysprep

The EC2Launch v2 service runs Sysprep, a Microsoft tool that enables you to create a customized Windows AMI that can be reused. When EC2Launch v2 calls Sysprep, it uses the files in %ProgramData%\Amazon\EC2Launch to determine which operations to perform. You can edit these files indirectly using the EC2Launch settings dialog box, or directly using a YAML editor or a text editor. However, there are some advanced settings that aren't available in the EC2Launch settings dialog box, so you must edit those entries directly.

If you create an AMI from an instance after updating its settings, the new settings are applied to any instance that's launched from the new AMI. For information about creating an AMI, see Create an Amazon EBS-backed AMI.