Configuring Amazon EBS volumes at deployment - Amazon Elastic Container Service

Configuring Amazon EBS volumes at deployment

To configure an Amazon EBS volume for attachment to your task, you must specify the mount point configuration in your task definition, name the volume, and set configuredAtLaunch to true. The following task definition JSON snippet shows the syntax for the mountPoints and volumes objects in the task definition. For more information about task definition parameters, see Task definition parameters. To use this example, replace the user input placeholders with your own information.

{ "family": "mytaskdef", "containerDefinitions": [ { "name": "container-using-ebs", "image": "amazonlinux:2", "entryPoint": [ "sh", "-c" ], "command": [ "ls -la /mount/ebs" ], "mountPoints": [ { "sourceVolume": "myEbsVolume", "containerPath": "/mount/ebs", "readOnly": true } ] } ], "volumes": [ { "name": "myEBSVolume", "configuredAtLaunch": true } ] }

To register the task definition by using the AWS Command Line Interface (AWS CLI), save the template as a JSON file, and then use the following command. To use this example command, replace the user input placeholders with your own information.

aws ecs register-task-definition \ --cli-input-json file://path_to_json_file/task-definition.json

To create and register a task definition using the AWS Management Console, see Creating a task definition using the console.

After you register the task definition, you can configure the volume at deployment using the AWS Management Console, Amazon ECS APIs, or by passing an input JSON file with the following AWS 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.

Configuring a volume at deployment allows you to create task definitions that aren't constrained to a volume type or specific EBS volume settings. You can then reuse your task definitions across different execution environments. For example, you can provide more throughput for your production workloads then your pre-prod environments.

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: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::iam:1111222333:role/ecsInfrastructureRole", "terminationPolicy": { "deleteOnTermination": true//can't be configured for service-managed tasks, always true }, "filesystemType": "ext4" } } ]
Note

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

For information about how to diagnose and fix issues that you might encounter when you configure an EBS volume for attachment to a task, see Troubleshooting Amazon EBS volume attachment issues. For information about the Amazon ECS infrastructure AWS Identity and Access Management (IAM) role necessary for EBS volume attachment, see Amazon ECS infrastructure IAM role.

Configuring 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. Save the following snippet as a JSON file. To use this example, replace the user input placeholders with your own information.

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

The following command can be used to run a standalone task using a JSON input file. The configuration specified in the JSON file is used to create and attach an EBS volume to the standalone task. To use this example, replace the user input placeholders with your own information.

aws ecs run-task \ --cli-input-json file://path_to_json_file/task.json

To configure a volume for attachment to a standalone task using the AWS Management Console, see Run an application as an Amazon ECS task.

Configuring 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. Save the following snippet as a JSON file. To use this example, replace the user input placeholders with your own information.

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

You can use the following command to create a service by using a JSON input file. The configuration specified in the JSON file is used to create and attach an EBS volume to each task managed by the service. To use this example command, replace the user input placeholders with your own information.

aws ecs create-service \ --cluster mycluster \ --service-name mysvc \ --cli-input-json file://path_to_json_file/create-service.json

To configure a volume for attachment to service-managed tasks during service creation using the AWS Management Console, see Creating a service using the console.

Configuring 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 with configuredAtLaunch set to true. The following JSON snippet shows the syntax for configuring the volumeType, sizeInGiB, throughput, and iops, and filesystemType settings of Amazon EBS volumes configured for attachment to tasks managed by a service. One volume is attached to each task in the service. To use this example, replace the user input placeholders with your own information.

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

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. To use this example, replace the user input placeholders with your own information.

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

You can use the following command to update a service by using a JSON input file. To use this example command, replace the user input placeholders with your own information.

aws ecs update-service \ --cli-input-json file://path_to_json_file/update-service.json

To configure a volume for attachment to service-managed tasks during service update using the AWS Management Console, see Updating a service using the console .

Amazon EBS volume termination policy

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.

Tagging 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. Amazon ECS automatically attaches the AmazonECSCreated and AmazonECSManaged reserved tags to an Amazon EBS volume. An additional 48 user-defined, ECS-managed, and propagated tags can be added to a volume for a total of 50 tags maximum per volume.

If you want to add Amazon ECS-managed tags to your volume, you must set enableECSManagedTags to true in your UpdateService, CreateService,RunTask or StartTaskcall. 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 and ECS-managed tags. 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::iam:1111222333:role/ecsInfrastructureRole", "encrypted": true, "kmsKeyId": "arn:aws:kms:region:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab" } } ] }
Note

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