Configure a volume for a standalone task Configure a volume at service creation Configure a volume at service update Termination policy for Amazon EBS volumes Tag Amazon EBS volumes

Specify Amazon EBS volume configuration at Amazon ECS deployment

After you register a task definition with the configuredAtLaunch parameter set to true, you can configure an Amazon EBS volume at deployment when you run a standalone task, or when you create or update a service.

To confgure a volume, you can use the Amazon ECS APIs, or you pass a JSON file as input for the following Amazon CLI commands:

run-task to run a standalone ECS task.
start-task to run a standalone ECS task in a specific container instance. This command is not applicable for Fargate launch type tasks.
create-service to create a new ECS service.
update-service to update an existing service.

Note

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

You can also configure an Amazon EBS volume by using the Amazon Web Services Management Console. For more information, see Running an application as an Amazon ECS task, Creating an Amazon ECS service using the console, and Updating an Amazon ECS service using the console.

The following JSON snippet shows all the parameters of an Amazon EBS volume that can be configured at deployment. To use these parameters for volume configuration, replace the user input placeholders with your own information. For more information about these parameters, see Volume configurations.


"volumeConfigurations": [
        {
            "name": "ebs-volume", 
            "managedEBSVolume": {
                "encrypted": true, 
                "kmsKeyId": "arn:aws-cn:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab", 
                "volumeType": "gp3", 
                "sizeInGiB": 10, 
                "snapshotId": "snap-12345", 
                "iops": 3000, 
                "throughput": 125, 
                "tagSpecifications": [
                    {
                        "resourceType": "volume", 
                        "tags": [
                            {
                                "key": "key1", 
                                "value": "value1"
                            }
                        ], 
                        "propagateTags": "NONE"
                    }
                ], 
                "roleArn": "arn:aws-cn::iam:1111222333:role/ecsInfrastructureRole", 
                 "terminationPolicy": {
                    "deleteOnTermination": true//can't be configured for service-managed tasks, always true 
                },
                "filesystemType": "ext4"
            }
        }
    ]

Important

Ensure that the volumeName you specify in the configuration is the same as the volumeName you specify in your task definition.

For information about checking the status of volume attachment, see Troubleshooting Amazon EBS volume attachments to Amazon ECS tasks . For information about the Amazon ECS infrastructure Amazon Identity and Access Management (IAM) role necessary for EBS volume attachment, see Amazon ECS infrastructure IAM role.

The following are JSON snippet examples that show the configuration of Amazon EBS volumes. These examples can be used by saving the snippets in JSON files and passing the files as parameters (using the --cli-input-json file://filename parameter) for Amazon CLI commands. Replace the user input placeholders with your own information.

Configure a volume for a standalone task

The following snippet shows the syntax for configuring Amazon EBS volumes for attachment to a standalone task. The following JSON snippet shows the syntax for configuring the volumeType, sizeInGiB, encrypted, and kmsKeyId settings. The configuration specified in the JSON file is used to create and attach an EBS volume to the standalone task.


{
   "cluster": "mycluster",
   "taskDefinition": "mytaskdef",
   "volumeConfigurations": [
        {
            "name": "datadir",
            "managedEBSVolume": {
                "volumeType": "gp3",
                "sizeInGiB": 100,
                "roleArn":"arn:aws-cn:iam:1111222333:role/ecsInfrastructureRole",
                "encrypted": true,
                "kmsKeyId": "arn:aws-cn:kms:region:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
            }
        }
   ]
}

Configure a volume at service creation

The following snippet shows the syntax for configuring Amazon EBS volumes for attachment to tasks managed by a service. The volumes are sourced from the snapshot by using the snapshotId. The configuration specified in the JSON file is used to create and attach an EBS volume to each task managed by the service.


{
   "cluster": "mycluster",
   "taskDefinition": "mytaskdef",
   "serviceName": "mysvc",
   "desiredCount": 2,
   "volumeConfigurations": [
        {
            "name": "myEbsVolume",
            "managedEBSVolume": {
              "roleArn":"arn:aws-cn:iam:1111222333:role/ecsInfrastructureRole",
              "snapshotId": "snap-12345"
            }
        }
   ]
}

Configure a volume at service update

The following JSON snippet shows the syntax for updating a service that previously did not have Amazon EBS volumes configured for attachment to tasks. You must provide the ARN of a task definition revision with configuredAtLaunch set to true. The following JSON snippet shows the syntax for configuring the volumeType, sizeInGiB, throughput, and iops, and filesystemType settings. This configuration is used to create and attach an EBS volume to each task managed by the service.


{
   "cluster": "mycluster",
   "taskDefinition": "mytaskdef",
   "serviceName": "mysvc",
   "desiredCount": 2,
  "volumeConfigurations": [
        {
            "name": "myEbsVolume",
            "managedEBSVolume": {
              "roleArn":"arn:aws-cn:iam:1111222333:role/ecsInfrastructureRole",
               "volumeType": "gp3",
                "sizeInGiB": 100,
                 "iops": 3000, 
                "throughput": 125, 
                "filesystemType": "ext4"
            }
        }
   ]
}

Configure a service to no longer utilize Amazon EBS volumes

The following JSON snippet shows the syntax for updating a service to no longer utilize Amazon EBS volumes. You must provide the ARN of a task definition with configuredAtLaunch set to false, or a task definition without the configuredAtLaunch parameter. You must also provide an empty volumeConfigurations object.


{
   "cluster": "mycluster",
   "taskDefinition": "mytaskdef",
   "serviceName": "mysvc",
   "desiredCount": 2,
   "volumeConfigurations": []
}

Termination policy for Amazon EBS volumes

When an Amazon ECS task terminates, Amazon ECS uses the deleteOnTermination value to determine whether the Amazon EBS volume that's associated with the terminated task should be deleted. By default, EBS volumes that are attached to tasks are deleted when the task is terminated. For standalone tasks, you can change this setting to instead preserve the volume upon task termination.

Note

Volumes that are attached to tasks that are managed by a service are not preserved and are always deleted upon task termination.

Tag Amazon EBS volumes

You can tag Amazon EBS volumes by using the tagSpecifications object. Using the object, you can provide your own tags and set propagation of tags from the task definition or the service, depending on whether the volume is attached to a standalone task or a task in a service. The maximum number of tags that can be attached to a volume is 50.

Important

Amazon ECS automatically attaches the AmazonECSCreated and AmazonECSManaged reserved tags to an Amazon EBS volume. This means you can control the attachment of a maximum of 48 additional tags to a volume. These additional tags can be user-defined, ECS-managed, or propagated tags.

If you want to add Amazon ECS-managed tags to your volume, you must set enableECSManagedTags to true in your UpdateService, CreateService,RunTask or StartTask call. If you turn on Amazon ECS-managed tags, Amazon ECS will tag the volume automatically with cluster and service information (aws:ecs:clusterName and aws:ecs:serviceName). For more information about tagging Amazon ECS resources, see Tagging your Amazon ECS resources.

The following JSON snippet shows the syntax for tagging each Amazon EBS volume that is attached to each task in a service with a user-defined tag. To use this example for creating a service, replace the user input placeholders with your own information.


{
   "cluster": "mycluster",
   "taskDefinition": "mytaskdef",
   "serviceName": "mysvc",
   "desiredCount": 2,
   "enableECSManagedTags": true,
   "volumeConfigurations": [
        {
            "name": "datadir",
            "managedEBSVolume": {
                "volumeType": "gp3",
                "sizeInGiB": 100,
                 "tagSpecifications": [
                    {
                        "resourceType": "volume", 
                        "tags": [
                            {
                                "key": "key1", 
                                "value": "value1"
                            }
                        ], 
                        "propagateTags": "NONE"
                    }
                ]
                "roleArn":"arn:aws-cn:iam:1111222333:role/ecsInfrastructureRole",
                "encrypted": true,
                "kmsKeyId": "arn:aws-cn:kms:region:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
            }
        }
   ]
}

Important

You must specify a volume resource type to tag Amazon EBS volumes.

Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Encrypt data stored in Amazon EBS volumes

Performance of Amazon EBS volumes for Fargate on-demand tasks