AWS Spot Fleet Provider¶
AWS discourages Spot Fleet for new work. In Work with Spot Fleet, AWS states: "We strongly discourage using Spot Fleet because it uses a legacy API with no planned investment. If you want to manage your instance lifecycle, use EC2 Fleet instead. If you don't want to manage your instance lifecycle, use an Auto Scaling group instead. Use Spot Fleet only if you need console support for a use case where you would use EC2 Fleet."
ORB continues to support Spot Fleet for existing deployments, and this handler is maintained. For new templates, prefer EC2 Fleet — it covers spot provisioning with the same allocation strategies plus
instantsynchronous fulfilment — or Auto Scaling Groups if you want AWS to maintain capacity for you. See Migrating to EC2 Fleet below.
The Spot Fleet handler provisions capacity through the EC2 Spot Fleet API. A Spot Fleet request asks EC2 for a target capacity and lets it choose instance types and availability zones according to an allocation strategy, which is how you get spot pricing without pinning yourself to a single capacity pool.
Use it for interruption-tolerant work: batch processing, CI, and simulation. Spot Fleet's one remaining advantage over EC2 Fleet is its per-override Priority and SpotPrice semantics, which have no direct EC2 Fleet equivalent.
Quick start¶
1. Create the service-linked role¶
Spot Fleet needs a service-linked role so EC2 can launch and terminate instances on your behalf. Create it once per account:
2. Create a template¶
{
"template_id": "batch-spot",
"name": "Batch Spot Fleet",
"description": "Diversified spot capacity for batch work",
"provider_api": "SpotFleet",
"image_id": "/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-6.1-x86_64",
"machine_types": {"t3.medium": 2, "t3.large": 2, "t3.xlarge": 4},
"subnet_ids": ["subnet-0f984e48e6e899311", "subnet-1a2b3c4d5e6f7a8b9"],
"security_group_ids": ["sg-0528dfedb6d763b16"],
"price_type": "spot",
"allocation_strategy": "capacityOptimized",
"fleet_type": "request",
"fleet_role": "arn:aws:iam::123456789012:role/aws-service-role/spotfleet.amazonaws.com/AWSServiceRoleForEC2SpotFleet",
"max_price": 0.10,
"max_machines": 100,
"tags": {"Environment": "dev"}
}
3. Request capacity¶
4. Check status¶
5. Return capacity¶
Template configuration¶
The handler uses provider_api: "SpotFleet". Each request creates a launch template, then calls request_spot_fleet with a SpotFleetRequestConfig.
Top-level fields¶
| Field | Required | Type | Description |
|---|---|---|---|
provider_api |
Yes | string |
Must be "SpotFleet" |
fleet_role |
Yes | string |
IAM fleet role ARN. Validated before the fleet is created — see Fleet role. |
image_id |
Yes | string |
AMI id or SSM parameter path. |
fleet_type |
No | string |
"request" (default) or "maintain". See Fleet types. |
machine_types |
No | object |
Instance type → weighted capacity. Expanded across subnets into overrides. |
subnet_ids |
No | list[string] |
Target subnets. Each is combined with each instance type. |
security_group_ids |
No | list[string] |
Security groups. |
price_type |
No | string |
"spot", "ondemand", or "heterogeneous". Validated — any other value is rejected. |
percent_on_demand |
No | integer |
On-demand share. Required when price_type is "heterogeneous". |
allocation_strategy |
No | string |
Spot allocation strategy, camelCase on the wire. |
max_price |
No | float |
Maximum spot price per hour. Must be greater than zero. |
spot_fleet_request_expiry |
No | integer |
Minutes until the request expires, converted to ValidUntil. |
abis_instance_requirements |
No | object |
Attribute-based instance selection, replacing instance-type overrides. |
max_machines |
No | integer |
Maximum capacity this template may provision. |
context |
No | string |
Passed through as the fleet Context field. |
tags |
No | object |
Tags applied to the spot-fleet-request resource. |
provider_api_spec |
No | object |
Native RequestSpotFleet config. See Native spec. |
Fleet role¶
Unlike the other AWS handlers, Spot Fleet will not provision without a fleet role, and the role is validated up front. fleet_role may be set on the template or inherited from the provider's config.fleet_role. In a multi-provider setup the role is read from the provider instance serving the request; with a single unnamed provider, ORB uses that provider's role.
Accepted forms:
| Value | Handling |
|---|---|
arn:aws:iam::<account>:role/aws-service-role/spotfleet.amazonaws.com/AWSServiceRoleForEC2SpotFleet |
Used as-is. |
arn:aws:iam::<account>:role/aws-ec2-spot-fleet-tagging-role |
Used as-is. |
AWSServiceRoleForEC2SpotFleet or AmazonEC2SpotFleetTaggingRole |
Expanded to the full service-linked role ARN using sts:GetCallerIdentity for the account id. |
An EC2 Fleet service-linked role ARN (ec2fleet.amazonaws.com/AWSServiceRoleForEC2Fleet) |
Converted to the equivalent Spot Fleet role. |
| Any other ARN | Treated as a custom role and verified with iam:GetRole. A lookup failure fails the request. |
An ARN that mentions AWSServiceRoleForEC2SpotFleet but does not match the expected pattern is rejected with an explicit error rather than being passed to AWS.
Fleet types¶
fleet_type |
Behaviour |
|---|---|
request (default) |
One-time request. EC2 fills the target capacity and does not replace interrupted instances. |
maintain |
EC2 keeps the fleet at target capacity, replacing interrupted or unhealthy instances. Sets ReplaceUnhealthyInstances and TerminateInstancesWithExpiration. |
Spot Fleet has no instant type — that is EC2 Fleet only. Both Spot Fleet types return only a request id from the create call; instances arrive later.
Allocation strategies¶
Spot Fleet uses camelCase on the wire, so template values pass through nearly unchanged. ORB still normalises hyphenated and snake_case input:
| Template value | Sent to AWS |
|---|---|
lowestPrice |
lowestPrice |
capacityOptimized |
capacityOptimized |
capacityOptimizedPrioritized |
capacityOptimizedPrioritized |
priceCapacityOptimized |
priceCapacityOptimized |
diversified |
diversified |
When no strategy is set, spot and heterogeneous templates default to priceCapacityOptimized and on-demand templates default to lowestPrice. prioritized is not a Spot Fleet spot strategy and falls back to lowestPrice.
Overrides, priority, and per-override price¶
machine_types and subnet_ids are expanded into the cartesian product of instance type and subnet. Spot Fleet overrides additionally carry:
Priority— a 1-based index inmachine_typesorder, used by thecapacityOptimizedPrioritizedstrategy.SpotPrice—max_pricerepeated per override, when set.
So {"t3.medium": 2, "t3.large": 2} across two subnets yields four overrides, with t3.medium at priority 1 and t3.large at priority 2 in each subnet.
Pricing mix¶
TargetCapacity is always the requested count. The on-demand portion is derived:
| Configuration | OnDemandTargetCapacity |
|---|---|
price_type: "spot" |
Not set — all capacity is spot. |
price_type: "ondemand" |
The full requested count. |
price_type: "heterogeneous" with percent_on_demand: N |
max(1, requested * N / 100) — at least one instance when a non-zero percentage is requested. |
percent_on_demand is required for heterogeneous and the request is rejected without it. If machine_types_ondemand is set, machine_types must be set too, and every on-demand weight must be a positive integer.
Request expiry¶
spot_fleet_request_expiry is in minutes, not seconds. It becomes ValidUntil at now + N minutes:
The shipped provider default is 30 minutes. Combined with maintain and TerminateInstancesWithExpiration, instances are terminated when the request expires — so set this deliberately for long-running work.
Attribute-based instance selection¶
abis_instance_requirements replaces the instance-type overrides with InstanceRequirements, one override per subnet:
{
"provider_api": "SpotFleet",
"abis_instance_requirements": {
"vcpu_count": {"min": 2, "max": 8},
"memory_mib": {"min": 4096, "max": 32768},
"local_storage": "required"
}
}
When ABIS is present, machine_types is ignored and no Priority is emitted. See Attribute-Based Instance Selection.
Native spec¶
A provider_api_spec is rendered and used as the SpotFleetRequestConfig. ORB patches the launch template id and version into every entry of LaunchSpecifications, and injects ABIS InstanceRequirements into LaunchTemplateConfigs[0].Overrides when the spec does not already carry them. See the Native Spec Reference.
Machine data¶
Instances carry the Spot Fleet request id as resource_id:
{
"instance_id": "i-0abc1234def567890",
"resource_id": "sfr-73fbd2ce-aa30-494c-8788-1cee4ffcbc12",
"status": "running",
"private_ip": "10.0.1.42",
"instance_type": "t3.large",
"provider_api": "SpotFleet",
"provider_data": {
"cloud_host_id": "i-0abc1234def567890",
"vcpus": 2,
"availability_zone": "us-east-1a",
"region": "us-east-1"
}
}
Fulfilment semantics¶
Spot Fleet uses capacity-unit semantics, identical to EC2 Fleet's maintain and request types: FulfilledCapacity >= TargetCapacity with nothing pending and nothing failed.
| Condition | State |
|---|---|
| Fulfilled capacity meets target, nothing pending, nothing failed | fulfilled |
| Instances failed, none running, none pending | failed |
| Anything else | in_progress |
Two intermediate cases are reported distinctly while no instances are visible yet: capacity allocated but instances not yet enumerable, and the fleet still waiting for capacity. Both are in_progress.
Because capacity is measured in weighted units, a fleet with {"t3.xlarge": 4} can fulfil a 4-unit request with a single instance.
For multi-fleet requests, all fleets must be fulfilled for the request to be fulfilled; any failure makes it failed; any partial makes it partial, and that aggregate is only terminal when every partial contributor is itself terminal.
Release behaviour¶
Releases follow the shared fleet release flow, with the branch determined by fleet type:
- Fetch fleet details with
describe_spot_fleet_requestswhen the caller did not supply them. - Compute the decision from fleet type, current target capacity, and the summed
WeightedCapacityof the instances being returned. Using weighted units rather than a count prevents AWS from refilling capacity that was decremented by the wrong amount. - Reduce capacity first for
maintainfleets, so EC2 does not launch replacements for instances about to be terminated.requestfleets skip this — they never replace. - Terminate the instances.
- Cancel the fleet when empty. For
requestfleets ORB re-checks that no instances remain outside the batch before cancelling, guarding against eventual-consistency lag. Formaintainfleets a full return cancels directly; a weighted-capacity edge case where arithmetic says partial but the fleet is physically empty triggers a capacity-zero call before cancellation. - Clean up the launch template ORB created for the request.
Cancelling a request with no instances named cancels the whole fleet and terminates whatever it holds.
When a maintain fleet shrinks, ORB passes ExcessCapacityTerminationPolicy: NoTermination to modify_spot_fleet_request, and reads the current target again immediately before lowering it. The returned instances are terminated explicitly, and only those, so the fleet does not terminate an extra instance and then launch a replacement. As for EC2 Fleet, this narrows rather than closes the window in which two returns on one fleet overwrite each other. A fleet that is already cancelled is not modified or cancelled again by a later return.
Cancelling a request¶
Cancelling a request that is still being fulfilled calls cancel_spot_fleet_requests with TerminateInstances: true, which cancels pending requests and terminates the instances already launched (cancelled_terminating). A request AWS reports as not cancellable counts as stopped only when a describe confirms it is cancelled. Instances still attached afterwards are found with the aws:ec2spot:fleet-request-id tag and returned with the recorded machines.
IAM permissions¶
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:RequestSpotFleet",
"ec2:CancelSpotFleetRequests",
"ec2:ModifySpotFleetRequest",
"ec2:DescribeSpotFleetRequests",
"ec2:DescribeSpotFleetInstances",
"ec2:DescribeInstances",
"ec2:TerminateInstances",
"sts:GetCallerIdentity"
],
"Resource": "*"
}
]
}
sts:GetCallerIdentity resolves short role names to full ARNs. iam:GetRole is additionally needed when fleet_role is a custom role, since validation calls it. iam:PassRole on the fleet role is required for EC2 to assume it. Launch template, tagging, and SSM permissions are shared across handlers — see the IAM Permissions Guide.
Limitations¶
- Fleet role is mandatory and validated before provisioning; a bad role fails the request rather than the AWS call.
- No
instantfleet type — provisioning is always asynchronous, so the create call never returns instance ids. - Expiry is in minutes and defaults to 30 in the shipped config; combined with
maintain, expiry terminates instances. - Spot interruptions are not surfaced as a distinct state — an interrupted instance appears as a capacity shortfall.
prioritizedallocation is unsupported and silently falls back tolowestPrice.- AWS considers the underlying API legacy with no planned investment — see the note at the top of this page.
Migrating to EC2 Fleet¶
Most Spot Fleet templates convert to EC2 Fleet by changing provider_api and adjusting four fields. ORB's template model is shared across both handlers, so image_id, machine_types, subnet_ids, security_group_ids, tags, and abis_instance_requirements carry over unchanged.
| Spot Fleet | EC2 Fleet | Notes |
|---|---|---|
provider_api: "SpotFleet" |
provider_api: "EC2Fleet" |
|
fleet_role (required) |
Not used | EC2 Fleet uses the EC2 Spot service-linked role in the account rather than a per-template role. Drop the field. |
fleet_type: "request" / "maintain" |
Same, plus "instant" |
Behaviour is equivalent for the two shared types. instant is new and returns instance ids synchronously. |
allocation_strategy: "capacityOptimized" |
allocation_strategy: "capacityOptimized" |
Keep the camelCase value; ORB converts it to the hyphenated form EC2 Fleet expects. |
max_price (per-override SpotPrice) |
max_price (MaxTotalPrice) |
Semantics change. A per-instance price cap becomes a total fleet spend cap. Recheck the value. |
spot_fleet_request_expiry |
Not supported | EC2 Fleet has no ORB-exposed expiry field. Use a native spec ValidUntil if you need one. |
Per-override Priority |
Not supported | Only relevant with capacityOptimizedPrioritized. Keep Spot Fleet if you depend on it. |
The max_price change is the one to look at closely: 0.10 as a per-instance cap is not the same constraint as 0.10 as a total fleet cap, and a total cap set too low will throttle the whole fleet.
Worked example — the Spot Fleet template from Quick start as an EC2 Fleet template:
{
"template_id": "batch-spot",
"name": "Batch Spot Fleet",
"description": "Diversified spot capacity for batch work",
"provider_api": "EC2Fleet",
"image_id": "/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-6.1-x86_64",
"machine_types": {"t3.medium": 2, "t3.large": 2, "t3.xlarge": 4},
"subnet_ids": ["subnet-0f984e48e6e899311", "subnet-1a2b3c4d5e6f7a8b9"],
"security_group_ids": ["sg-0528dfedb6d763b16"],
"price_type": "spot",
"allocation_strategy": "capacityOptimized",
"max_machines": 100,
"metadata": {"fleet_type": "request"},
"tags": {"Environment": "dev"}
}
fleet_role and spot_fleet_request_expiry are gone, and max_price is omitted rather than carried over at its old value. Validate the new template before switching traffic to it:
Existing Spot Fleet requests are unaffected by adding an EC2 Fleet template — the two can run side by side while you migrate.
Related¶
- EC2 Fleet — newer fleet API with instant provisioning and richer pricing mixes
- Auto Scaling Groups — health-checked, self-replacing capacity
- EC2 Instances (RunInstances) — synchronous single-type launches
- IAM Permissions Guide — service-linked role setup