How do I use Fargate Spot capacity providers for Amazon ECS?

Resolution

Prerequisites:

• Fargate and Fargate Spot capacity providers are available to all AWS accounts, and you aren't required to create them. Associate Fargate and Fargate Spot capacity providers with a cluster to make them available for use.
• Use the PutClusterCapacityProviders API or the put-cluster-capacity-providers AWS Command Line Interface (AWS CLI) command to associate a Fargate Spot capacity provider. Use the AWS Management Console to add a Fargate Spot capacity provider to an existing cluster.
• Fargate and Fargate Spot capacity providers are reserved and can't be deleted. To disassociate them from a cluster, use the PutClusterCapacityProviders API.
• Confirm that your task uses platform version 1.3.0 or later for Linux. Fargate Spot capacity provider isn't supported for Windows containers on Fargate.

Note: If you receive errors when you run AWS CLI commands, then see Troubleshoot AWS CLI errors. Also, make sure that you're using the most recent AWS CLI version.

Associate and disassociate Fargate Spot capacity providers

If you use the Networking only cluster template to create a Fargate Spot capacity provider, then the provider is automatically associated with the cluster. For more information, see Create an Amazon ECS cluster for Fargate workloads.

Associate a Fargate Spot capacity provider with your cluster

To associate a Fargate Spot capacity provider with your cluster, use the PutClusterCapacityProviders API. Or, run the following put-cluster-capacity-providers AWS CLI command:

aws ecs put-cluster-capacity-providers \
  --cluster YOUR_CLUSTER_NAME \
  --capacity-providers FARGATE FARGATE_SPOT \
  --default-capacity-provider-strategy capacityProvider=FARGATE,weight=1 capacityProvider=FARGATE_SPOT,weight=1 \
  --region YOUR_REGION

Note: Replace YOUR_CLUSTER_NAME with your cluster name and YOUR_REGION with your AWS Region.

Important: Include all your existing capacity providers and the capacity provider strategy in the command. If you don't include a provider, then the command disassociates it from the cluster and can overwrite your existing configuration.

Disassociate a Fargate Spot capacity provider from your cluster

If you omit a capacity provider from the PutClusterCapacityProviders API call, then the call disassociates that provider from the cluster.

To disassociate the Fargate Spot capacity provider from your Amazon ECS cluster, run the following put-cluster-capacity-providers AWS CLI command:

aws ecs put-cluster-capacity-providers \
  --cluster YOUR_CLUSTER_NAME \
  --capacity-providers FARGATE \
  --default-capacity-provider-strategy capacityProvider=FARGATE,weight=1 \
  --region YOUR_REGION

Note: Replace YOUR_CLUSTER_NAME with your cluster name and YOUR_REGION with your Region.

Confirm that your Fargate Spot capacity provider is associated with your Amazon ECS cluster

To confirm that the Fargate Spot capacity provider is associated with your Amazon ECS cluster, run the following describe-clusters AWS CLI command:

aws ecs describe-clusters \
  --cluster YOUR_CLUSTER_NAME \
  --region YOUR_REGION

Note: Replace YOUR_CLUSTER_NAME with your cluster name and YOUR_REGION with your Region.

Example output:

"capacityProviders": [
    "FARGATE",
    "FARGATE_SPOT"
]

Note: The output of the command includes the capacity providers that are associated with your Amazon ECS cluster.

Use a Fargate Spot capacity provider to run a task or create a service

To use a Fargate Spot capacity provider to run a task, run the following run-task AWS CLI command:

aws ecs run-task \
  --cluster YOUR_CLUSTER_NAME \
  --capacity-provider-strategy capacityProvider=FARGATE_SPOT,weight=1 \
  --task-definition YOUR_TASK_DEFINITION:YOUR_REVISION \
  --network-configuration "awsvpcConfiguration={subnets=[string,string],securityGroups=[string,string],assignPublicIp=string}" \
  --count YOUR_COUNT \
  --region YOUR_REGION

Note: Replace YOUR_CLUSTER_NAME with your cluster name and YOUR_TASK_DEFINITION with your task definition family name. Replace YOUR_REVISION with your task definition revision number, YOUR_COUNT with the number of tasks to run, and YOUR_REGION with your Region.

To create an Amazon ECS service that uses Fargate Spot capacity providers, run the following create-service AWS CLI command:

aws ecs create-service \
  --cluster YOUR_CLUSTER_NAME \
  --service-name YOUR_SERVICE_NAME \
  --capacity-provider-strategy capacityProvider=FARGATE,weight=1 capacityProvider=FARGATE_SPOT,weight=1 \
  --task-definition YOUR_TASK_DEFINITION:YOUR_REVISION \
  --network-configuration "awsvpcConfiguration={subnets=[string,string],securityGroups=[string,string],assignPublicIp=string}" \
  --desired-count YOUR_COUNT \
  --region YOUR_REGION

Note: Replace YOUR_CLUSTER_NAME with your cluster name and YOUR_SERVICE_NAME with your service name. Replace YOUR_TASK_DEFINITION with your task definition family name, YOUR_REVISION with your task definition revision number, YOUR_COUNT with the number of tasks to run, and YOUR_REGION with your Region.

Confirm that your tasks run on the Fargate Spot capacity provider

To confirm that your tasks use Fargate capacity providers, run the following describe-tasks AWS CLI command:

aws ecs describe-tasks \
  --cluster YOUR_CLUSTER_NAME \
  --tasks YOUR_TASK_ARN \
  --region YOUR_REGION

Note: Replace YOUR_CLUSTER_NAME with your cluster name, YOUR_TASK_ARN with your task Amazon Resource Name (ARN), and YOUR_REGION with your Region.

You can't use Amazon CloudWatch to track Fargate On-Demand and Fargate Spot usage per service, but you can use CloudWatch to see the metric for total Fargate On-Demand and Spot usage. For more information, see AWS Fargate usage metrics.

Review Fargate Spot best practices

• Use Fargate Spot for stateless, fault-tolerant workloads, but don't rely on Spot tasks for critical workloads. Instead, configure a mix of On-Demand Fargate tasks.
• To gracefully handle interruptions, use SIGTERM signals. When you receive a SIGTERM signal, set StopTimeout to 120 seconds. For more information, see Graceful shutdowns with Amazon ECS.
• Applications that run on Fargate Spot must be fault-tolerant.

Understand Fargate Spot capacity unavailability behavior

When the Amazon ECS scheduler can't launch a task because there's no capacity, Amazon ECS emits the SERVICE_TASK_PLACEMENT_FAILURE event. The task doesn't reach the first stage PROVISIONING, and no notice is displayed in the Amazon ECS Events. The Amazon ECS scheduler continues to try to launch the task. If capacity becomes available, then Amazon ECS emits the SERVICE_STEADY_STATE event.

Important: AWS doesn't expose metrics, APIs, or signals to predict or detect Fargate Spot capacity exhaustion before it occurs. AWS doesn't disclose Fargate Spot capacity availability data to customers.

To reduce the impact of Fargate Spot capacity unavailability, use the following mitigations:

• Specify multiple subnets across Availability Zones to reduce the chance of capacity exhaustion in all zones at the same time.
• Configure a fallback capacity provider strategy that includes both FARGATE and FARGATE_SPOT with appropriate weights. If Spot capacity is unavailable, then the Amazon ECS scheduler can fall back to On-Demand Fargate capacity.

Note: To detect Spot capacity unavailability, monitor for the SERVICE_TASK_PLACEMENT_FAILURE event. Amazon ECS doesn't provide other indicators of Spot capacity exhaustion. You can create an Amazon EventBridge rule to monitor for this event and automate responses. For example, alert your operations team or scale your On-Demand capacity.

If FARGATE_SPOT capacity is unavailable, then Amazon ECS doesn't automatically fail over to Fargate On-Demand