EC2Launch v2 overview - Amazon Elastic Compute Cloud

EC2Launch v2 overview

EC2Launch v2 is a service that performs tasks during instance startup and runs if an instance is stopped and later started, or restarted.

To compare launch agent version features, see Compare Amazon EC2 launch agents.

EC2Launch v2 concepts

The following concepts are useful to understand when considering EC2Launch v2.

Task

You can invoke a task to perform an action on an instance. You can configure tasks in the agent-config.yml file or through user data. For a list of available tasks for EC2Launch v2, see EC2Launch v2 tasks. For task configuration schema and details, see EC2Launch v2 task configuration.

Stage

A stage is a logical grouping of tasks that the EC2Launch v2 agent runs. Some tasks can run only in a specific stage. Others can run in multiple stages. When using agent-config.yml, you must specify a list of stages, and a list of tasks to run within each stage.

The service runs stages in the following order:

Stage 1: Boot

Stage 2: Network

Stage 3: PreReady

Windows is ready

After the PreReady stage completes, the service sends the Windows is ready message to the Amazon EC2 console.

Stage 4: PostReady

User data runs during the PostReady stage. Some script versions run before the agent-config.yml file PostReady stage, and some run after, as follows:

Before agent-config.yml
  • YAML user data version 1.1

  • XML user data

After agent-config.yml
  • YAML user data version 1.0 (legacy version for backwards compatibility)

For example stages and tasks, see Example: agent-config.yml.

When you use user data, you must specify a list of tasks for the launch agent to run. The stage is implied. For example tasks, see Example: user data.

EC2Launch v2 runs the list of tasks in the order that you specify in agent-config.yml and in user data. Stages run sequentially. The next stage starts after the previous stage completes. Tasks also run sequentially.

Frequency

Task frequency determines when tasks should run, depending on the boot context. Most tasks have only one allowed frequency. You can specify a frequency for executeScript tasks.

You will see the following frequencies in the EC2Launch v2 task configuration.

  • Once – The task runs once, when the AMI has booted for the first time (finished Sysprep).

  • Always – The task runs every time that the launch agent runs. The launch agent runs when:

    • an instance starts or restarts

    • the EC2Launch service runs

    • EC2Launch.exe run is invoked

agent-config

agent-config is a file that is located in the configuration folder for EC2Launch v2. It includes configuration for the boot, network, PreReady, and PostReady stages. This file is used to specify the instance configuration for tasks that should run when the AMI is either booted for the first time or for subsequent times.

By default, the EC2Launch v2 installation installs an agent-config file that includes recommended configurations that are used in standard Amazon Windows AMIs. You can update the configuration file to alter the default boot experience for your AMI that EC2Launch v2 specifies.

User data

User data is data that is configurable when you launch an instance. You can update user data to dynamically change how custom AMIs or quickstart AMIs are configured. EC2Launch v2 supports 60 kB user data input length. User data includes only the UserData stage, and therefore runs after the agent-config file. You can enter user data when you launch an instance using the launch instance wizard, or you can modify user data from the EC2 console. For more information about working with user data, see Run commands on your Windows instance at launch.

EC2Launch v2 tasks

EC2Launch v2 can perform the following tasks at each boot:

  • Set up new and optionally customized wallpaper that renders information about the instance.

  • Set the attributes for the administrator account that is created on the local machine.

  • Add DNS suffixes to the list of search suffixes. Only suffixes that do not already exist are added to the list.

  • Set drive letters for any additional volumes and extend them to use available space.

  • Write files to the disk, either from the internet or from the configuration. If the content is in the configuration, it can be base64 decoded or encoded. If the content is from the internet, it can be unzipped.

  • Run scripts either from the internet or from the configuration. If the script is from the configuration, it can be base64 decoded. If the script is from the internet, it can be unzipped.

  • Run a program with given arguments.

  • Set the computer name.

  • Send instance information to the Amazon EC2 console.

  • Send the RDP certificate thumbprint to the Amazon EC2 console.

  • Dynamically extend the operating system partition to include any unpartitioned space.

  • Run user data. For more information about specifying user data, see EC2Launch v2 task configuration.

  • Set non-persistent static routes to reach the metadata service and AWS KMS servers.

  • Set non-boot partitions to MBR or GPT.

  • Start the Systems Manager service following Sysprep.

  • Optimize ENA settings.

  • Enable OpenSSH for later Windows versions.

  • Enable Jumbo Frames.

  • Set Sysprep to run with EC2Launch v2.

  • Publish Windows event logs.

Telemetry

Telemetry is additional information that helps AWS to better understand your requirements, diagnose issues, and deliver features to improve your experience with AWS services.

EC2Launch v2 version 2.0.592 and later collect telemetry, such as usage metrics and errors. This data is collected from the Amazon EC2 instance on which EC2Launch v2 runs. This includes all Windows AMIs owned by AWS.

The following types of telemetry are collected by EC2Launch v2:

  • Usage information — agent commands, install method, and scheduled run frequency.

  • Errors and diagnostic information — agent installation error codes, run error codes, and error call stacks.

Examples of collected data:

2021/07/15 21:44:12Z: EC2LaunchTelemetry: IsAgentScheduledPerBoot=true 2021/07/15 21:44:12Z: EC2LaunchTelemetry: IsUserDataScheduledPerBoot=true 2021/07/15 21:44:12Z: EC2LaunchTelemetry: AgentCommandCode=1 2021/07/15 21:44:12Z: EC2LaunchTelemetry: AgentCommandErrorCode=5 2021/07/15 21:44:12Z: EC2LaunchTelemetry: AgentInstallCode=2 2021/07/15 21:44:12Z: EC2LaunchTelemetry: AgentInstallErrorCode=0

Telemetry is enabled by default. You can disable telemetry collection at any time. If telemetry is enabled, EC2Launch v2 sends telemetry data without additional customer notifications.

Telemetry visibility

When telemetry is enabled, it appears in the Amazon EC2 console output as follows.

2021/07/15 21:44:12Z: Telemetry: <Data>
Disable telemetry on an instance

To disable telemetry for a single instance, you can either set a system environment variable, or use the MSI to modify the installation.

To disable telemetry by setting a system environment variable, run the following command as an administrator.

setx /M EC2LAUNCH_TELEMETRY 0

To disable telemetry using the MSI, run the following command after you download the MSI.

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