Use Amazon EBS volumes with Amazon ECS - Amazon Elastic Container Service
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Use Amazon EBS volumes with Amazon ECS

Amazon Elastic Block Store (Amazon EBS) volumes provide highly available, cost-effective, durable, high-performance block storage for data-intensive workloads. Amazon EBS volumes can be used with Amazon ECS tasks for high throughput and transaction-intensive applications.

During standalone task launch, you can provide the configuration that will be used to attach one EBS volume to the task. During service creation or update, you can provide the configuration that will be used to attach one EBS volume per task to each task managed by the ECS service.

By providing volume configuration at launch time rather than in the task definition, you create task definitions that aren't constrained to a specific data volume type or specific EBS volume settings. You can then reuse your task definitions across different runtime environments. For example, you can provide more throughput during deployment for your production workloads then your pre-prod environments.

Amazon EBS volumes that are attached to Amazon ECS tasks are managed by Amazon ECS on your behalf. The volumes can be encrypted with Amazon Key Management Service (Amazon KMS) keys to protect your data. You can either configure new, empty volumes for attachment, or you can use snapshots to load data from existing volumes.

To monitor your volume's performance, you can also use Amazon CloudWatch metrics. For more information about Amazon ECS metrics for Amazon EBS volumes, see Amazon ECS CloudWatch metrics and Amazon ECS Container Insights metrics.

Attaching an Amazon EBS volume to a task is supported in all commercial and China Amazon Web Services Regions that support Amazon ECS.

For more information about Amazon EBS volumes, see Amazon EBS volumes in the Amazon EBS User Guide.

Considerations

Consider the following when using Amazon EBS volumes:

  • You can't configure Amazon EBS volumes for attachment to Fargate launch type Amazon ECS tasks in the use1-az3 Availability Zone.

  • Amazon EBS volumes are supported only for Linux tasks hosted on Fargate, and EC2 launch type tasks hosted on Nitro-based Linux instances with Amazon ECS-optimized Amazon Machine Images (AMIs). For more information about instance types, see Instance types in the Amazon EC2 User Guide. For more information about Amazon ECS launch types, see Amazon ECS launch types.

  • For tasks that are hosted on Fargate, Amazon EBS volumes are supported on platform version 1.4.0 or later (Linux). For more information, see Fargate platform versions for Amazon ECS.

  • For tasks that are hosted on Amazon EC2 Linux instances, Amazon EBS volumes are supported on ECS-optimized AMI 20231219 or later. For more information, see Retrieving Amazon ECS-Optimized AMI metadata.

  • The magnetic (standard) Amazon EBS volume type is not supported for tasks hosted on Fargate. For more information about Amazon EBS volume types, see Amazon EBS volumes in the Amazon EC2 User Guide.

  • An Amazon ECS infrastructure IAM role is required when creating a service or a standalone task that is configuring a volume at deployment. You can attach the Amazon managed AmazonECSInfrastructureRolePolicyForVolumes IAM policy to the role, or you can use the managed policy as a guide to create and attach your own policy with permissions that meet your specific needs. For more information, see Amazon ECS infrastructure IAM role.

  • You can attach at most one Amazon EBS volume to each Amazon ECS task, and it must be a new volume. You can't attach an existing Amazon EBS volume to a task. However, you can configure a new Amazon EBS volume at deployment using the snapshot of an existing volume.

  • You can configure Amazon EBS volumes at deployment only for services that use the rolling update deployment type and the Replica scheduling strategy.

  • For a container in your task to write to the mounted Amazon EBS volume, you must run the container as a root user.

  • Amazon ECS automatically adds the reserved tags AmazonECSCreated and AmazonECSManaged to the attached volume. If you remove these tags from the volume, Amazon ECS won't be able to manage the volume on your behalf. For more information about tagging Amazon EBS volumes, see Tagging Amazon EBS volumes. For more information about tagging Amazon ECS resources, see Tagging your Amazon ECS resources.

  • Provisioning volumes from a snapshot of an Amazon EBS volume that contains partitions isn't supported.

  • Volumes that are attached to tasks that are managed by a service aren't preserved and are always deleted upon task termination.

  • You can't configure Amazon EBS volumes for attachment to Amazon ECS tasks that are running on Amazon Outposts.