Create an EC2 Fleet - Amazon Elastic Compute Cloud
EC2 Fleet limitationsEC2 Fleet prerequisitesCreate an EC2 FleetCreate an EC2 Fleet that replaces unhealthy Spot InstancesView all the EC2 Fleet configuration options

Create an EC2 Fleet

To create an EC2 Fleet, define the fleet configuration in a JSON file and reference the file with the create-fleet AWS CLI command. In the JSON file, you must specify the total target capacity for the fleet, separate target capacities for Spot Instances and On-Demand Instances, and a launch template that defines the configuration for the instances in the fleet, such as an AMI, instance type, subnet or Availability Zone, and one or more security groups. You can optionally specify additional configurations, such as parameters to override the launch template configuration, allocation strategies for selecting Spot Instances and On-Demand Instances from the EC2 capacity pools, and the maximum amount you're willing to pay for the fleet. For more information, see Configuration options for your EC2 Fleet or Spot Fleet.

The EC2 Fleet launches On-Demand Instances when capacity is available, and launches Spot Instances when your maximum price exceeds the Spot price and capacity is available.

If your fleet includes Spot Instances and is of type maintain, Amazon EC2 will attempt to maintain your fleet target capacity when your Spot Instances are interrupted.

EC2 Fleet limitations

The following limitations apply to EC2 Fleet:

  • Creating an EC2 Fleet is available only through the Amazon EC2 API, AWS CLI, AWS SDKs, and AWS CloudFormation.

  • An EC2 Fleet request can't span AWS Regions. You need to create a separate EC2 Fleet for each Region.

  • An EC2 Fleet request can't span different subnets from the same Availability Zone.

EC2 Fleet prerequisites

Launch template

A launch template specifies the configuration information about the instances to launch, such as the instance type and Availability Zone. For more information about launch templates, see Store instance launch parameters in Amazon EC2 launch templates.

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:

  • ec2:RunInstances – Launch instances.

  • ec2:RequestSpotInstances – Request Spot Instances.

  • ec2:TerminateInstances – Terminate instances.

  • ec2:DescribeImages – Describe Amazon Machine Images (AMIs) for the instances.

  • ec2:DescribeInstanceStatus – Describe the status of the instances.

  • ec2:DescribeSubnets – Describe the subnets for instances.

  • ec2:CreateTags – Add tags to the EC2 Fleet, instances, and volumes.

Ensure that this role exists before you use the AWS CLI or an API to create an EC2 Fleet.

Note

An instant EC2 Fleet does not require this role.

To create the role, use the IAM console as follows.

To create the AWSServiceRoleForEC2Fleet role for EC2 Fleet

  1. Open the IAM console at https://console.aws.amazon.com/iam/.

  2. In the navigation pane, choose Roles.

  3. Choose Create role.

  4. On the Select trusted entity page, do the following:

    1. For Trusted entity type, choose AWS service.

    2. Under Use case, for Service or use case, choose EC2 - Fleet.

      Tip

      Be sure to choose EC2 - Fleet. If you choose EC2, the EC2 - Fleet use case does not appear in the Use case list. The EC2 - Fleet use case will automatically create a policy with the required IAM permissions and will suggest AWSServiceRoleForEC2Fleet as the role name.

    3. Choose Next.

  5. On the Add permissions page, choose Next.

  6. On the Name, review, and create page, choose Create role.

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.

For more information, see Service-linked roles in the IAM User Guide.

Grant access to customer managed keys for use with encrypted AMIs and EBS snapshots

If you specify an encrypted AMI or an encrypted Amazon EBS snapshot in your EC2 Fleet and you use an AWS KMS key for encryption, you must grant the AWSServiceRoleForEC2Fleet role permission to use the customer managed key so that Amazon EC2 can launch instances on your behalf. To do this, you must add a grant to the customer managed key, as shown in the following procedure.

When providing permissions, grants are an alternative to key policies. For more information, see Using grants and Using key policies in AWS KMS in the AWS Key Management Service Developer Guide.

To grant the AWSServiceRoleForEC2Fleet role permissions to use the customer managed key

  • Use the create-grant command to add a grant to the customer managed key and to specify the principal (the AWSServiceRoleForEC2Fleet service-linked role) that is given permission to perform the operations that the grant permits. The customer managed key is specified by the key-id parameter and the ARN of the customer managed key. The principal is specified by the grantee-principal parameter and the ARN of the AWSServiceRoleForEC2Fleet service-linked role.

    aws kms create-grant \
    --region us-east-1 \
    --key-id arn:aws:kms:us-east-1:444455556666:key/1234abcd-12ab-34cd-56ef-1234567890ab \
    --grantee-principal arn:aws:iam::111122223333:role/AWSServiceRoleForEC2Fleet \
    --operations "Decrypt" "Encrypt" "GenerateDataKey" "GenerateDataKeyWithoutPlaintext" "CreateGrant" "DescribeKey" "ReEncryptFrom" "ReEncryptTo"

Permissions for EC2 Fleet users

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

To create a policy for EC2 Fleet

  1. Open the IAM console at https://console.aws.amazon.com/iam/.

  2. In the navigation pane, choose Policies.

  3. Choose Create policy.

  4. On the Create policy page, choose the JSON tab, replace the text with the following, and choose Review policy.

    {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ec2:*"
            ],
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": [
              "iam:ListRoles",
              "iam:PassRole",
              "iam:ListInstanceProfiles"
            ],
            "Resource":"arn:aws:iam::123456789012:role/DevTeam*"
        }
    ]
}

    The ec2:* grants a user permission to call all Amazon EC2 API actions. To limit the user to specific Amazon EC2 API actions, specify those actions instead.

    The 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 a 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

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

  6. To provide access, add permissions to your users, groups, or roles:

Create an EC2 Fleet

To launch a fleet of instances using EC2 Fleet, you need only specify the following parameters in your fleet request, and the fleet will use the default values for the other parameters:

  • LaunchTemplateId or LaunchTemplateName – Specifies the launch template to use (which contains the parameters for the instances to launch, such as the instance type and Availability Zone)

  • TotalTargetCapacity – Specifies the total target capacity for the fleet

  • DefaultTargetCapacityType – Specifies whether the default purchasing option is On-Demand or Spot

To override the parameters specified in the launch template, you can specify one or more overrides. Each override can vary by instance type, Availability Zone, subnet, and maximum price, and can include a different weighted capacity. As an alternative to specifying an instance type, you can specify the attributes that an instance must have, and Amazon EC2 will identify all the instance types with those attributes. For more information, see Specify attributes for instance type selection for EC2 Fleet or Spot Fleet.

For EC2 Fleets of type instant, you can specify a Systems Manager parameter instead of the AMI ID. You can specify the Systems Manager parameter in the override or in the launch template. For more information, see Use a Systems Manager parameter instead of an AMI ID.

You can specify the fleet parameters in a JSON file. For information about all the possible parameters you can specify, see View all the EC2 Fleet configuration options.

For fleet configuration examples, see Example CLI configurations for EC2 Fleet.

There is currently no console support for creating an EC2 Fleet.

To create an EC2 Fleet

  • Use the create-fleet (AWS CLI) command to create the fleet and specify the JSON file that contains the fleet configuration parameters.

aws ec2 create-fleet --cli-input-json file://file_name.json

The following is example output for a fleet of type request or maintain.

{
    "FleetId": "fleet-12a34b55-67cd-8ef9-ba9b-9208dEXAMPLE"
}

The following is example output for a fleet of type instant that launched the target capacity.

{
  "FleetId": "fleet-12a34b55-67cd-8ef9-ba9b-9208dEXAMPLE",
  "Errors": [],
  "Instances": [
    {
      "LaunchTemplateAndOverrides": {
        "LaunchTemplateSpecification": {
          "LaunchTemplateId": "lt-01234a567b8910abcEXAMPLE",
          "Version": "1"
        },
        "Overrides": {
          "InstanceType": "c5.large",
          "AvailabilityZone": "us-east-1a"
        }
      },
      "Lifecycle": "on-demand",
      "InstanceIds": [
        "i-1234567890abcdef0",
        "i-9876543210abcdef9" 
      ],
      "InstanceType": "c5.large",
      "Platform": null
    },
    {
      "LaunchTemplateAndOverrides": {
        "LaunchTemplateSpecification": {
          "LaunchTemplateId": "lt-01234a567b8910abcEXAMPLE",
          "Version": "1"
        },
        "Overrides": {
          "InstanceType": "c4.large",
          "AvailabilityZone": "us-east-1a"
        }
      },
      "Lifecycle": "on-demand",
      "InstanceIds": [
        "i-5678901234abcdef0",
        "i-5432109876abcdef9" 
      ]
  ]
}

The following is example output for a fleet of type instant that launched part of the target capacity with errors for instances that were not launched.

{
  "FleetId": "fleet-12a34b55-67cd-8ef9-ba9b-9208dEXAMPLE",
  "Errors": [
    {
      "LaunchTemplateAndOverrides": {
        "LaunchTemplateSpecification": {
          "LaunchTemplateId": "lt-01234a567b8910abcEXAMPLE",
          "Version": "1"
        },
        "Overrides": {
          "InstanceType": "c4.xlarge",
          "AvailabilityZone": "us-east-1a",
        }
      },
      "Lifecycle": "on-demand",
      "ErrorCode": "InsufficientInstanceCapacity",
      "ErrorMessage": ""
    },
  ],
  "Instances": [
    {
      "LaunchTemplateAndOverrides": {
        "LaunchTemplateSpecification": {
          "LaunchTemplateId": "lt-01234a567b8910abcEXAMPLE",
          "Version": "1"
        },
        "Overrides": {
          "InstanceType": "c5.large",
          "AvailabilityZone": "us-east-1a"
        }
      },
      "Lifecycle": "on-demand",
      "InstanceIds": [
        "i-1234567890abcdef0",
        "i-9876543210abcdef9" 
      ]
  ]
}

The following is example output for a fleet of type instant that launched no instances.

{
  "FleetId": "fleet-12a34b55-67cd-8ef9-ba9b-9208dEXAMPLE",
  "Errors": [
    {
      "LaunchTemplateAndOverrides": {
        "LaunchTemplateSpecification": {
          "LaunchTemplateId": "lt-01234a567b8910abcEXAMPLE",
          "Version": "1"
        },
        "Overrides": {
          "InstanceType": "c4.xlarge",
          "AvailabilityZone": "us-east-1a",
        }
      },
      "Lifecycle": "on-demand",
      "ErrorCode": "InsufficientCapacity",
      "ErrorMessage": ""
    },
    {
      "LaunchTemplateAndOverrides": {
        "LaunchTemplateSpecification": {
          "LaunchTemplateId": "lt-01234a567b8910abcEXAMPLE",
          "Version": "1"
        },
        "Overrides": {
          "InstanceType": "c5.large",
          "AvailabilityZone": "us-east-1a",
        }
      },
      "Lifecycle": "on-demand",
      "ErrorCode": "InsufficientCapacity",
      "ErrorMessage": ""
    },
  ],
  "Instances": []
}

Create an EC2 Fleet that replaces unhealthy Spot Instances

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.

EC2 Fleet determines the health status of an instance by using the status checks provided by Amazon EC2. An instance is determined as unhealthy when the status of either the instance status check or the system status check is impaired for three consecutive health status checks. For more information, see Status checks for Amazon EC2 instances.

You can configure your fleet to replace unhealthy Spot Instances. After setting ReplaceUnhealthyInstances to true, a Spot Instance is replaced when it is reported as unhealthy. The fleet can go below its target capacity for up to a few minutes while an unhealthy Spot Instance is being replaced.

Requirements

  • Health check replacement is supported only for EC2 Fleets that maintain a target capacity (fleets of type maintain), and not for fleets of type request or instant.

  • Health check replacement is supported only for Spot Instances. This feature is not supported for On-Demand Instances.

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

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

To configure an EC2 Fleet to replace unhealthy Spot Instances

  1. Use the information for creating an EC2 Fleet in Create an EC2 Fleet.

  2. To configure the fleet to replace unhealthy Spot Instances, in the JSON file, for ReplaceUnhealthyInstances, specify true.

View all the EC2 Fleet configuration options

To view the full list of EC2 Fleet configuration parameters, you can generate a JSON file. For a description of each parameter, see create-fleet in the AWS CLI Command Reference.

To generate a JSON file with all possible EC2 Fleet parameters

Use the create-fleet (AWS CLI) command and the --generate-cli-skeleton parameter to generate an EC2 Fleet JSON file, and direct the output to a file to save it.

aws ec2 create-fleet \
    --generate-cli-skeleton input > ec2createfleet.json

Example output

{
    "DryRun": true,
    "ClientToken": "",
    "SpotOptions": {
        "AllocationStrategy": "price-capacity-optimized",
        "MaintenanceStrategies": {
            "CapacityRebalance": {
                "ReplacementStrategy": "launch"
            }
        },
        "InstanceInterruptionBehavior": "hibernate",
        "InstancePoolsToUseCount": 0,
        "SingleInstanceType": true,
        "SingleAvailabilityZone": true,
        "MinTargetCapacity": 0,
        "MaxTotalPrice": ""
    },
    "OnDemandOptions": {
        "AllocationStrategy": "prioritized",
        "CapacityReservationOptions": {
            "UsageStrategy": "use-capacity-reservations-first"
        },
        "SingleInstanceType": true,
        "SingleAvailabilityZone": true,
        "MinTargetCapacity": 0,
        "MaxTotalPrice": ""
    },
    "ExcessCapacityTerminationPolicy": "termination",
    "LaunchTemplateConfigs": [
        {
            "LaunchTemplateSpecification": {
                "LaunchTemplateId": "",
                "LaunchTemplateName": "",
                "Version": ""
            },
            "Overrides": [
                {
                    "InstanceType": "r5.metal",
                    "MaxPrice": "",
                    "SubnetId": "",
                    "AvailabilityZone": "",
                    "WeightedCapacity": 0.0,
                    "Priority": 0.0,
                    "Placement": {
                        "AvailabilityZone": "",
                        "Affinity": "",
                        "GroupName": "",
                        "PartitionNumber": 0,
                        "HostId": "",
                        "Tenancy": "dedicated",
                        "SpreadDomain": "",
                        "HostResourceGroupArn": ""
                    },
                    "InstanceRequirements": {
                        "VCpuCount": {
                            "Min": 0,
                            "Max": 0
                        },
                        "MemoryMiB": {
                            "Min": 0,
                            "Max": 0
                        },
                        "CpuManufacturers": [
                            "amd"
                        ],
                        "MemoryGiBPerVCpu": {
                            "Min": 0.0,
                            "Max": 0.0
                        },
                        "ExcludedInstanceTypes": [
                            ""
                        ],
                        "InstanceGenerations": [
                            "previous"
                        ],
                        "SpotMaxPricePercentageOverLowestPrice": 0,
                        "OnDemandMaxPricePercentageOverLowestPrice": 0,
                        "BareMetal": "included",
                        "BurstablePerformance": "required",
                        "RequireHibernateSupport": true,
                        "NetworkInterfaceCount": {
                            "Min": 0,
                            "Max": 0
                        },
                        "LocalStorage": "excluded",
                        "LocalStorageTypes": [
                            "ssd"
                        ],
                        "TotalLocalStorageGB": {
                            "Min": 0.0,
                            "Max": 0.0
                        },
                        "BaselineEbsBandwidthMbps": {
                            "Min": 0,
                            "Max": 0
                        },
                        "AcceleratorTypes": [
                            "inference"
                        ],
                        "AcceleratorCount": {
                            "Min": 0,
                            "Max": 0
                        },
                        "AcceleratorManufacturers": [
                            "amd"
                        ],
                        "AcceleratorNames": [
                            "a100"
                        ],
                        "AcceleratorTotalMemoryMiB": {
                            "Min": 0,
                            "Max": 0
                        }
                    }
                }
            ]
        }
    ],
    "TargetCapacitySpecification": {
        "TotalTargetCapacity": 0,
        "OnDemandTargetCapacity": 0,
        "SpotTargetCapacity": 0,
        "DefaultTargetCapacityType": "on-demand",
        "TargetCapacityUnitType": "memory-mib"
    },
    "TerminateInstancesWithExpiration": true,
    "Type": "instant",
    "ValidFrom": "1970-01-01T00:00:00",
    "ValidUntil": "1970-01-01T00:00:00",
    "ReplaceUnhealthyInstances": true,
    "TagSpecifications": [
        {
            "ResourceType": "fleet",
            "Tags": [
                {
                    "Key": "",
                    "Value": ""
                }
            ]
        }
    ],
    "Context": ""
}