Managing an EC2 Fleet

To use an EC2 Fleet, you create a request that includes the total target capacity,
On-Demand
capacity, Spot capacity, one or more launch specifications for the instances, and
the
maximum price that you are willing to pay. The fleet request must include a launch
template that defines the information that the fleet needs to launch an instance,
such
as an AMI, instance type, subnet or Availability Zone, and one or more security
groups.
You can specify launch specification overrides for the instance type, subnet,
Availability Zone, and maximum price you're willing to pay, and you can assign
weighted
capacity to each launch specification override.

EC2 Fleet Request States

submitted – The EC2 Fleet request is being evaluated and
Amazon EC2 is preparing to launch the target number of instances, which can
include On-Demand Instances, Spot Instances, or both.

active – The EC2 Fleet request has been validated and Amazon EC2
is attempting to maintain the target number of running instances. The
request remains in this state until it is modified or deleted.

modifying – The EC2 Fleet request is being modified. The request remains in
this state until the modification is fully processed or the request is
deleted. Only a maintain request type can be modified. This
state does not apply to other request types.

deleted_running – The EC2 Fleet request is deleted and does
not launch additional instances. Its existing instances continue to run
until they are interrupted or terminated. The request remains in this state
until all instances are interrupted or terminated.

deleted_terminating – The EC2 Fleet request is deleted and
its instances are terminating. The request remains in this state until all
instances are terminated.

deleted – The EC2 Fleet is deleted and has no running
instances. The request is deleted two days after its instances are
terminated.

The following illustration represents the transitions between the EC2 Fleet request
states. If you exceed your fleet limits, the request is deleted immediately.

EC2 Fleet Prerequisites

To create an EC2 Fleet, the following prerequisites must be in place.

Launch
Template

A launch template includes information about the instances to launch, such as
the instance type, Availability Zone, and the maximum price that you are willing
to pay. For more information, see Launching an Instance from a Launch Template.

Service-Linked Role for EC2 Fleet

The AWSServiceRoleForEC2Fleet role grants the EC2 Fleet permission to request,
launch, terminate, and tag instances on your behalf.
Amazon EC2 uses this service-linked role to complete the following actions:

If you no longer need to use EC2 Fleet, we recommend that you delete the
AWSServiceRoleForEC2Fleet role. After this role is deleted
from your account, you can create the role again if you create another fleet.

EC2 Fleet and IAM Users

If your IAM users will create or manage an EC2 Fleet, be sure to grant them the
required permissions as follows.

An IAM user must have permission to call the
iam:ListRoles action to enumerate existing IAM roles,
the iam:PassRole action to specify the EC2 Fleet role, and the
iam:ListInstanceProfiles action to enumerate existing
instance profiles.

(Optional) To enable an IAM user to create roles or instance
profiles using the IAM console, you must also add the following
actions to the policy:

iam:AddRoleToInstanceProfile

iam:AttachRolePolicy

iam:CreateInstanceProfile

iam:CreateRole

iam:GetRole

iam:ListPolicies

On the Review policy page, enter a policy name and description, and
choose Create policy.

In the navigation pane, choose Users and select
the user.

On the Permissions tab, choose Add
permissions.

Choose Attach existing policies directly. Select
the policy that you created earlier and choose Next:
Review.

Choose Add permissions.

EC2 Fleet Health Checks

EC2 Fleet checks the health status of the instances in the fleet every two minutes.
The
health status of an instance is either healthy or
unhealthy. The fleet determines the health status of an instance
using the status checks provided by Amazon EC2. If the status of either the instance
status check or the system status check is impaired for three
consecutive health checks, the health status of the instance is
unhealthy. Otherwise, the health status is healthy.
For more information, see Status Checks for Your Instances.

You can configure your EC2 Fleet to replace unhealthy instances. After enabling health
check replacement, an instance is replaced after its health status is reported
as
unhealthy. The fleet could go below its target capacity for up to a
few minutes while an unhealthy instance is being replaced.

Requirements

Health check replacement is supported only with EC2 Fleets that maintain a target
capacity,
not with one-time fleets.

You can configure your EC2 Fleet to replace unhealthy instances only when you
create it.

IAM users can use health check replacement only if they have permission
to call the ec2:DescribeInstanceStatus action.

Generating an EC2 Fleet JSON Configuration
File

To create an EC2 Fleet, you need only specify the launch template, total target capacity,
and
whether the default purchasing option is On-Demand or Spot. If you do not specify
a
parameter, the fleet uses the default value. To view the full list of fleet
configuration parameters, you can generate a JSON file as follows.

To generate a JSON file with all possible EC2 Fleet parameters using the command
line

Use the create-fleet (AWS CLI) command and the
--generate-cli-skeleton parameter to generate an EC2 Fleet JSON
file:

EC2 Fleet JSON Configuration File
Reference

Note

Use lowercase for all parameter values; otherwise, you get an error when Amazon EC2
uses the
JSON file to launch the EC2 Fleet.

AllocationStrategy (for SpotOptions)

(Optional) Indicates how to allocate the Spot Instance target capacity across the
Spot Instance pools
specified by the EC2 Fleet. Valid values are lowestPrice and
diversified. The default is
lowestPrice. Specify the allocation strategy that
meets your needs. For more information, see Allocation Strategies for Spot Instances.

InstanceInterruptionBehavior

(Optional) The behavior when a Spot Instance is interrupted. Valid values
are hibernate, stop, and
terminate. By default, the Spot service terminates
Spot Instances when they are interrupted. If the fleet type is
maintain, you can specify that the Spot service
hibernates or stops Spot Instances when they are interrupted.

InstancePoolsToUseCount

The number of Spot pools across which to allocate your target Spot capacity. Valid
only
when Spot AllocationStrategy is set
to lowestPrice. EC2 Fleet selects the cheapest Spot pools
and evenly allocates your target Spot capacity across the number of
Spot pools that you specify.

AllocationStrategy (for OnDemandOptions)

The order of the launch template overrides to use in fulfilling On-Demand capacity.
If
you specify lowestPrice, EC2 Fleet uses price to determine
the order, launching the lowest price first. If you specify
prioritized, EC2 Fleet uses the priority that you assigned to each launch
template override, launching the highest priority first. If you do
not specify a value, EC2 Fleet defaults to
lowestPrice.

ExcessCapacityTerminationPolicy

(Optional) Indicates whether running instances should be
terminated if the total target capacity of the EC2 Fleet is decreased
below the current size of the EC2 Fleet. Valid values are
no-termination and termination.

LaunchTemplateId

The ID of the launch template to use. You must specify either the
launch template ID or launch template name. The launch template must
specify an Amazon Machine Image (AMI). For more information about
creating launch templates, see Launching an Instance from a Launch Template.

LaunchTemplateName

The name of the launch template to use. You must specify either the launch template
ID
or launch template name. The launch template must specify an Amazon
Machine Image (AMI). For more information, see Launching an Instance from a Launch Template.

Version

The version number of the launch template.

InstanceType

(Optional) The instance type. If entered, this value overrides the launch template.
The
instance types must have the minimum hardware specifications that
you need (vCPUs, memory, or storage).

MaxPrice

(Optional) The maximum price per unit hour that you are willing to pay for a Spot
Instance. If
entered, this value overrides the launch template. You can use the
default maximum price (the On-Demand price) or specify the maximum
price that you are willing to pay. Your Spot Instances are not launched if
your maximum price is lower than the Spot price for the instance
types that you specified.

SubnetId

(Optional) The ID of the subnet in which to launch the instances.
If entered, this value overrides the launch template.

To create a new VPC, go the Amazon VPC console. When you are done, return to the
JSON file and enter the new subnet ID.

AvailabilityZone

(Optional) The Availability Zone in which to launch the instances. The default is
to
let AWS choose the zones for your instances. If you prefer, you can
specify specific zones. If entered, this value overrides the launch
template.

Specify one or more Availability Zones. If you have more than one subnet in a
zone, specify the appropriate subnet. To add subnets, go to the
Amazon VPC console. When you are done, return to the JSON file and enter
the new subnet ID.

WeightedCapacity

(Optional) The number of units provided by the specified instance
type. If entered, this value overrides the launch template.

Priority

The priority for the launch template override. If AllocationStrategy is set to
prioritized, EC2 Fleet uses priority to determine which
launch template override to use first in fulfilling On-Demand
capacity. The highest priority is launched first. Valid values are
whole numbers starting at 0. The lower the number, the
higher the priority. If no number is set, the override has the
lowest priority.

TotalTargetCapacity

The number of instances to launch. You can choose instances or performance
characteristics that are important to your application workload,
such as vCPUs, memory, or storage. If the request type is
maintain, you can specify a target capacity of 0
and add capacity later.

OnDemandTargetCapacity

(Optional) The number of On-Demand Instances to launch. This number must be
less than the TotalTargetCapacity.

SpotTargetCapacity

(Optional) The number of Spot Instances to launch. This number must be less
than the TotalTargetCapacity.

DefaultTargetCapacityType

If the value for TotalTargetCapacity is higher than the combined values
for OnDemandTargetCapacity and
SpotTargetCapacity, the difference is launched as
the instance purchasing option specified here. Valid values are
on-demand or spot.

TerminateInstancesWithExpiration

(Optional) By default, Amazon EC2 terminates your instances when the EC2 Fleet request
expires.
The default value is true. To keep them running after
your request expires, do not enter a value for this
parameter.

Type

(Optional) Indicates whether the EC2 Fleet submits a synchronous one-time request
for your
desired capacity (instant), or an asynchronous one-time
request for your desired capacity, but with no attempt maintain the
capacity or to submit requests in alternative capacity pools if
capacity is unavailable (request), or submits an
asynchronous request for your desired capacity and continues to
maintain your desired capacity by replenishing interrupted Spot Instances
(maintain). Valid values are instant,
request, and maintain. The default
value is maintain. For more information, see EC2 Fleet Request Types.

ValidFrom

(Optional) To create a request that is valid only during a
specific time period, enter a start date.

ValidUntil

(Optional) To create a request that is valid only during a
specific time period, enter an end date.

ReplaceUnhealthyInstances

(Optional) To replace unhealthy instances in an EC2 Fleet that is
configured to maintain the fleet, enter
true. Otherwise, leave this parameter empty.

TagSpecifications

(Optional) The key-value pair for tagging the EC2 Fleet request on creation. The value
for
ResourceType must be fleet, otherwise
the fleet request fails. To tag instances at launch, specify the
tags in the launch template. For information about tagging after launch, see Tagging Your Resources.

Creating an EC2 Fleet

When you create an EC2 Fleet, you must specify a launch template that includes
information about the instances to launch, such as the instance type, Availability
Zone, and the maximum price you are willing to pay.

You can create an EC2 Fleet that includes multiple launch specifications that override
the launch template. The launch specifications can vary by instance type,
Availability Zone, subnet, and maximum price, and can include a different weighted
capacity.

Tagging an EC2 Fleet

You can assign a tag to an EC2 Fleet request when you create it, or afterward. Tags
assigned to
the fleet request are not assigned to the instances launched by the fleet.

To tag a new EC2 Fleet request

To tag an EC2 Fleet request when you create it, specify the key-value pair in the
JSON file used to create the fleet.
The value for ResourceType must be fleet. If you specify
another value, the fleet request fails.

To tag instances launched by an EC2 Fleet

To tag instances when they are launched by the fleet, specify the tags in the
launch template referenced in the
EC2 Fleet request.

Monitoring Your EC2 Fleet

The EC2 Fleet launches On-Demand Instances when there is available capacity, and launches
Spot Instances when
your maximum price exceeds the Spot price and capacity is available. The On-Demand
Instances run
until you terminate them, and the Spot Instances run until they are interrupted
or you
terminate them.

The returned list of running instances is refreshed periodically and might be out
of date.

Modifying an EC2 Fleet

You can modify an EC2 Fleet that is in the submitted or active state.
When you modify a fleet, it enters the modifying state.

You can modify the following parameters of an EC2 Fleet:

target-capacity-specification – Increase or decrease the target
capacity for TotalTargetCapacity,
OnDemandTargetCapacity, and
SpotTargetCapacity.

excess-capacity-termination-policy – Whether running instances should
be terminated if the total target capacity of the EC2 Fleet is decreased below
the current size of the fleet. Valid values are no-termination
and termination.

Note

You can only modify an EC2 Fleet that has
Type=maintain.

When you increase the target capacity, the EC2 Fleet launches the additional instances
according
to the instance purchasing option specified for
DefaultTargetCapacityType, which are either On-Demand Instances or Spot Instances.

If the DefaultTargetCapacityType is spot, the EC2 Fleet launches the
additional Spot Instances according to its allocation strategy. If the allocation
strategy is
lowestPrice, the fleet launches the instances from the
lowest-priced Spot Instance pool in the request. If the allocation strategy is
diversified, the fleet distributes the instances across the pools
in the request.

When you decrease the target capacity, the EC2 Fleet deletes any open requests that
exceed the
new target capacity. You can request that the fleet terminate instances until
the
size of the fleet reaches the new target capacity. If the allocation strategy
is
lowestPrice, the fleet terminates the instances with the highest
price per unit. If the allocation strategy is diversified, the fleet
terminates instances across the pools. Alternatively, you can request that EC2
Fleet keep
the fleet at its current size, but not replace any Spot Instances that are interrupted
or any
instances that you terminate manually.

When an EC2 Fleet terminates a Spot Instance because the target capacity was decreased,
the
instance receives a Spot Instance interruption notice.

To modify an EC2 Fleet (AWS CLI)

Use the following modify-fleet command to update the target capacity of the specified
EC2 Fleet:

Deleting an EC2 Fleet

If you no longer require an EC2 Fleet, you can delete it. After you delete a fleet,
it launches
no new instances.

You must specify whether the EC2 Fleet must terminate its instances. If you specify
that the
instances must be terminated when the fleet is deleted, it enters the
deleted_terminating state. Otherwise, it enters the
deleted_running state, and the instances continue to run until they
are interrupted or you terminate them manually.

To delete an EC2 Fleet (AWS CLI)

Use the delete-fleets command and the --terminate-instances parameter to
delete the specified EC2 Fleet and terminate the instances: