Your application is now running on a container in Amazon ECS.
'; C:\\ServiceMonitor.exe w3svc"], "entryPoint": [ "powershell", "-Command" ], "essential": true, "cpu": 2048, "memory": 4096, "image": "mcr.microsoft.com/windows/servercore/iis:windowsservercore-ltsc2019", "name": "sample_windows_app", "portMappings": [ { "hostPort": 443, "containerPort": 80, "protocol": "tcp" } ], "mountPoints": [ { "sourceVolume": "myEBSVolume", "containerPath": "drive:\ebs", "readOnly": true } ] } ], "volumes": [ { "name": "myEBSVolume", "configuredAtLaunch": true } ], "requiresCompatibilities": [ "FARGATE", "EC2" ], "cpu": "1024", "memory": "3072", "networkMode": "awsvpc" } ``` `mountPoints` Type: Object array Required: No The mount points for the data volumes in your container. This parameter maps to `Volumes` in the create-container Docker API and the `--volume` option to docker run. Windows containers can mount whole directories on the same drive as `$env:ProgramData`. Windows containers cannot mount directories on a different drive, and mount points cannot be used across drives. You must specify mount points to attach an Amazon EBS volume directly to an Amazon ECS task. `sourceVolume` Type: String Required: Yes, when `mountPoints` are used The name of the volume to mount. `containerPath` Type: String Required: Yes, when `mountPoints` are used The path in the container where the volume will be mounted. `readOnly` Type: Boolean Required: No If this value is `true`, the container has read-only access to the volume. If this value is `false`, then the container can write to the volume. The default value is `false`. For tasks that run on EC2 instances running the Windows operating system, leave the value as the default of `false`. `name` Type: String Required: No The name of the volume. Up to 255 letters (uppercase and lowercase), numbers, hyphens (`-`), and underscores (`_`) are allowed. This name is referenced in the `sourceVolume` parameter of the container definition `mountPoints` object. `configuredAtLaunch` Type: Boolean Required: Yes, when you want to use attach an EBS volume directly to a task. Specifies whether a volume is configurable at launch. When set to `true`, you can configure the volume when you run a standalone task, or when you create or update a service. When set to `false`, you won't be able to provide another volume configuration in the task definition. This parameter must be provided and set to `true` to configure an Amazon EBS volume for attachment to a task. # Encrypt data stored in Amazon EBS volumes attached to Amazon ECS tasks Encrypt data stored in Amazon EBS volumes You can use AWS Key Management Service (AWS KMS) to make and manage cryptographic keys that protect your data. Amazon EBS volumes are encrypted at rest by using AWS KMS keys. The following types of data are encrypted: + Data stored at rest on the volume + Disk I/O + Snapshots created from the volume + New volumes created from encrypted snapshots Amazon EBS volumes that are attached to tasks can be encrypted by using either a default AWS managed key with the alias `alias/aws/ebs`, or a symmetric customer managed key specified in the volume configuration. Default AWS managed keys are unique to each AWS account per AWS Region and are created automatically. To create a symmetric customer managed key, follow the steps in [Creating symmetric encryption KMS keys](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html#create-symmetric-cmk) in the *AWS KMS Developer Guide*. You can configure Amazon EBS encryption by default so that all new volumes created and attached to a task in a specific AWS Region are encrypted by using the KMS key that you specify for your account. For more information about Amazon EBS encryption and encryption by default, see [Amazon EBS encryption](https://docs.aws.amazon.com/ebs/latest/userguide/ebs-encryption.html) in the *Amazon EBS User Guide*. ## Amazon ECS Managed Instances behavior You encrypt Amazon EBS volumes by enabling encryption, either using encryption by default or by enabling encryption when you create a volume that you want to encrypt. For information about how to enable encryption by default (at the account-level, see [Encryption by default](https://docs.aws.amazon.com/ebs/latest/userguide/encryption-by-default.html) in the *Amazon EBS User Guide*. You can configure any combination of these keys. The order of precedence of KMS keys is as follows: 1. The KMS key specified in the volume configuration. When you specify a KMS key in the volume configuration, it overrides the Amazon EBS default and any KMS key that is specified at the account level. 1. The KMS key specified at the account level. When you specify a KMS key for cluster-level encryption of Amazon ECS managed storage, it overrides Amazon EBS default encryption but does not override any KMS key that is specified in the volume configuration. 1. Amazon EBS default encryption. Default encryption applies when you don't specify either a account-level KMS key or a key in the volume configuration. If you enable Amazon EBS encryption by default, the default is the KMS key you specify for encryption by default. Otherwise, the default is the AWS managed key with the alias `alias/aws/ebs`. **Note** If you set `encrypted` to `false` in your volume configuration, specify no account-level KMS key, and enable Amazon EBS encryption by default, the volume will still be encrypted with the key specified for Amazon EBS encryption by default. ## Non-Amazon ECS Managed Instances behavior You can also set up Amazon ECS cluster-level encryption for Amazon ECS managed storage when you create or update a cluster. Cluster-level encryption takes effect at the task level and can be used to encrypt the Amazon EBS volumes attached to each task running in a specific cluster by using the specified KMS key. For more information about configuring encryption at the cluster level for each task, see [ManagedStorageConfiguration](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ManagedStorageConfiguration.html) in the *Amazon ECS API reference*. You can configure any combination of these keys. The order of precedence of KMS keys is as follows: 1. The KMS key specified in the volume configuration. When you specify a KMS key in the volume configuration, it overrides the Amazon EBS default and any KMS key that is specified at the cluster level. 1. The KMS key specified at the cluster level. When you specify a KMS key for cluster-level encryption of Amazon ECS managed storage, it overrides Amazon EBS default encryption but does not override any KMS key that is specified in the volume configuration. 1. Amazon EBS default encryption. Default encryption applies when you don't specify either a cluster-level KMS key or a key in the volume configuration. If you enable Amazon EBS encryption by default, the default is the KMS key you specify for encryption by default. Otherwise, the default is the AWS managed key with the alias `alias/aws/ebs`. **Note** If you set `encrypted` to `false` in your volume configuration, specify no cluster-level KMS key, and enable Amazon EBS encryption by default, the volume will still be encrypted with the key specified for Amazon EBS encryption by default. ## Customer managed KMS key policy To encrypt an EBS volume that's attached to your task by using a customer managed key, you must configure your KMS key policy to ensure that the IAM role that you use for volume configuration has the necessary permissions to use the key. The key policy must include the `kms:CreateGrant` and `kms:GenerateDataKey*` permissions. The `kms:ReEncryptTo` and `kms:ReEncryptFrom` permissions are necessary for encrypting volumes that are created using snapshots. If you want to configure and encrypt only new, empty volumes for attachment, you can exclude the `kms:ReEncryptTo` and `kms:ReEncryptFrom` permissions. The following JSON snippet shows key policy statements that you can attach to your KMS key policy. Using these statements will provide access for Amazon ECS to use the key for encrypting the EBS volume. To use the example policy statements, replace the `user input placeholders` with your own information. As always, only configure the permissions that you need. ``` { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/ecsInfrastructureRole" }, "Action": "kms:DescribeKey", "Resource":"*" }, { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/ecsInfrastructureRole" }, "Action": [ "kms:GenerateDataKey*", "kms:ReEncryptTo", "kms:ReEncryptFrom" ], "Resource":"*", "Condition": { "StringEquals": { "kms:CallerAccount": "aws_account_id", "kms:ViaService": "ec2.region.amazonaws.com" }, "ForAnyValue:StringEquals": { "kms:EncryptionContextKeys": "aws:ebs:id" } } }, { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/ecsInfrastructureRole" }, "Action": "kms:CreateGrant", "Resource":"*", "Condition": { "StringEquals": { "kms:CallerAccount": "aws_account_id", "kms:ViaService": "ec2.region.amazonaws.com" }, "ForAnyValue:StringEquals": { "kms:EncryptionContextKeys": "aws:ebs:id" }, "Bool": { "kms:GrantIsForAWSResource": true } } } ``` For more information about key policies and permissions, see [Key policies in AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html) and [AWS KMS permissions](https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html) in the *AWS KMS Developer Guide*. For troubleshooting EBS volume attachment issues related to key permissions, see [Troubleshooting Amazon EBS volume attachments to Amazon ECS tasks](troubleshoot-ebs-volumes.md). # Specify Amazon EBS volume configuration at Amazon ECS deployment Specify Amazon EBS volume configuration at 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. For more information about deferring volume configuration to launch time using the `configuredAtLaunch` parameter, see [Defer volume configuration to launch time in an Amazon ECS task definition](specify-ebs-config.md). To configure a volume, you can use the Amazon ECS APIs, or you can pass a JSON file as input for the following AWS CLI commands: + `[run-task](https://docs.aws.amazon.com/cli/latest/reference/ecs/run-task.html)` to run a standalone ECS task. + `[start-task](https://docs.aws.amazon.com/cli/latest/reference/ecs/start-task.html)` to run a standalone ECS task in a specific container instance. This command is not applicable for Fargate tasks. + `[create-service](https://docs.aws.amazon.com/cli/latest/reference/ecs/create-service.html)` to create a new ECS service. + `[update-service](https://docs.aws.amazon.com/cli/latest/reference/ecs/update-service.html)` to update an existing service. **Note** For a container in your task to write to the mounted Amazon EBS volume, the container must have appropriate file system permissions. When you specify a non-root user in your container definition, Amazon ECS automatically configures the volume with group-based permissions that allow the specified user to read and write to the volume. If no user is specified, the container runs as root and has full access to the volume. You can also configure an Amazon EBS volume by using the AWS Management Console. For more information, see [Running an application as an Amazon ECS task](standalone-task-create.md), [Creating an Amazon ECS rolling update deployment](create-service-console-v2.md), and [Updating an Amazon ECS service](update-service-console-v2.md). 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](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/service_definition_parameters.html#sd-volumeConfigurations). ``` "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", "volumeInitializationRate":100, "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" } } ] ``` **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](troubleshoot-ebs-volumes.md). 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](infrastructure_IAM_role.md). 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 AWS 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:iam::1111222333:role/ecsInfrastructureRole", "encrypted": true, "kmsKeyId": "arn:aws: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 specified using the `snapshotId` parameter at a rate of 200 MiB/s. 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:iam::1111222333:role/ecsInfrastructureRole", "snapshotId": "snap-12345", "volumeInitializationRate": 200 } } ] } ``` ## 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", "service": "mysvc", "desiredCount": 2, "volumeConfigurations": [ { "name": "myEbsVolume", "managedEBSVolume": { "roleArn":"arn:aws: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", "service": "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](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-using-tags.html). 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:iam:1111222333:role/ecsInfrastructureRole", "encrypted": true, "kmsKeyId": "arn:aws:kms:region:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab" } } ] } ``` **Important** You must specify a `volume` resource type to tag Amazon EBS volumes. # Performance of Amazon EBS volumes for Fargate on-demand tasks The baseline Amazon EBS volume IOPS and throughput available for a Fargate on-demand task depends on the total CPU units you request for the task. If you request 0.25, 0.5, or 1 virtual CPU unit (vCPU) for your Fargate task, we recommend that you configure a General Purpose SSD volume (`gp2` or `gp3`) or a Hard Disk Drive (HDD) volume (`st1` or `sc1`). If you request more than 1 vCPU for your Fargate task, the following baseline performance limits apply to an Amazon EBS volume attached to the task. You may temporarily get higher EBS performance than the following limits. However, we recommend that you plan your workload based on these limits. | CPU units requested (in vCPUs) | Baseline Amazon EBS IOPS(16 KiB I/O) | Baseline Amazon EBS Throughput (in MiBps, 128 KiB I/O) | Baseline bandwidth (in Mbps) | | --- | --- | --- | --- | | 2 | 3,000 | 75 | 360 | | 4 | 5,000 | 120 | 1,150 | | 8 | 10,000 | 250 | 2,300 | | 16 | 15,000 | 500 | 4,500 | **Note** When you configure an Amazon EBS volume for attachment to a Fargate task, the Amazon EBS performance limit for Fargate task is shared between the task's ephemeral storage and the attached volume. # Performance of Amazon EBS volumes for EC2 tasks Amazon EBS provides volume types, which differ in performance characteristics and price, so that you can tailor your storage performance and cost to the needs of your applications. For information about performance, including IOPS per volume and throughput per volume, see [Amazon EBS volume types](https://docs.aws.amazon.com/ebs/latest/userguide/ebs-volume-types.html) in the *Amazon Elastic Block Store User Guide*. # Performance of Amazon EBS volumes for Amazon ECS Managed Instances tasks Amazon EBS provides volume types, which differ in performance characteristics and price, so that you can tailor your storage performance and cost to the needs of your applications. For information about performance, including IOPS per volume and throughput per volume, see [Amazon EBS volume types](https://docs.aws.amazon.com/ebs/latest/userguide/ebs-volume-types.html) in the *Amazon Elastic Block Store User Guide*. # Troubleshooting Amazon EBS volume attachments to Amazon ECS tasks Troubleshooting Amazon EBS volume attachment You might need to troubleshoot or verify the attachment of Amazon EBS volumes to Amazon ECS tasks. ## Check volume attachment status You can use the AWS Management Console to view the status of an Amazon EBS volume's attachment to an Amazon ECS task. If the task starts and the attachment fails, you'll also see a status reason that you can use to troubleshoot. The created volume will be deleted and the task will be stopped. For more information about status reasons, see [Status reasons for Amazon EBS volume attachment to Amazon ECS tasks](troubleshoot-ebs-volumes-scenarios.md). **To view a volume's attachment status and status reason using the console** 1. Open the console at [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2). 1. On the **Clusters** page, choose the cluster that your task is running in. The cluster's details page appears. 1. On the cluster's details page, choose the **Tasks** tab. 1. Choose the task that you want to view the volume attachment status for. You might need to use **Filter desired status** and choose **Stopped** if the task you want to examine has stopped. 1. On the task's details page, choose the **Volumes** tab. You will be able to see the attachment status of the Amazon EBS volume under **Attachment status**. If the volume fails to attach to the task, you can choose the status under **Attachment status** to display the cause of the failure. You can also view a task's volume attachment status and associated status reason by using the [DescribeTasks](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_DescribeTasks.html) API. ## Service and task failures You might encounter service or task failures that aren't specific to Amazon EBS volumes that can affect volume attachment. For more information, see + [Service event messages](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/service-event-messages.html) + [Stopped task error codes](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/stopped-task-error-codes.html) + [API failure reasons](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/api_failures_messages.html) # Container can't write to Amazon EBS volume Non-root user without proper permissions When you specify a non-root user in your container definition, Amazon ECS automatically configures the volume with group-based permissions to allow write access. However, if you're still experiencing permission issues: + Verify that the `user` parameter is correctly specified in your container definition using the format `uid:gid` (for example, `1001:1001`). + Ensure your container image doesn't override the user permissions after the volume is mounted. + Check that your application is running with the expected user ID by examining the container logs or using Amazon ECS Exec to inspect the running container. Root user with permission issues If no user is specified in your container definition, the container runs as root and should have full access to the volume. If you're experiencing issues: + Verify that the volume is properly mounted by checking the mount points inside the container. + Ensure the volume isn't configured as read-only in your mount point configuration. Multi-container tasks with different users In tasks with multiple containers running as different users, Amazon ECS automatically manages group permissions to allow all specified users to write to the volume. If containers can't write: + Verify that all containers requiring write access have the `user` parameter properly configured. + Check that the volume is mounted in all containers that need access to it. For more information about configuring users in container definitions, see [ Amazon ECS task definition parameters for Fargate ](https://docs.aws.amazon.com/./task_definition_parameters.html). # Status reasons for Amazon EBS volume attachment to Amazon ECS tasks Status reasons for Amazon EBS volume attachment Use the following reference to fix issues that you might encounter in the form of status reasons in the AWS Management Console when you configure Amazon EBS volumes for attachment to Amazon ECS tasks. For more information on locating these status reasons in the console, see [Check volume attachment status](troubleshoot-ebs-volumes.md#troubleshoot-ebs-volumes-location). ECS was unable to assume the configured ECS Infrastructure Role 'arn:aws:iam::*111122223333*:role/*ecsInfrastructureRole*'. Please verify that the role being passed has the proper trust relationship with Amazon ECS This status reason appears in the following scenarios. + You provide an IAM role without the necessary trust policy attached. Amazon ECS can't access the Amazon ECS infrastructure IAM role that you provide if the role doesn't have the necessary trust policy. The task can get stuck in the `DEPROVISIONING` state. For more information about the necessary trust policy, see [Amazon ECS infrastructure IAM role](infrastructure_IAM_role.md). + Your IAM user doesn't have permission to pass the Amazon ECS infrastructure role to Amazon ECS. The task can get stuck in the `DEPROVISIONING` state. To avoid this problem, you can attach the `PassRole` permission to your user. For more information, see [Amazon ECS infrastructure IAM role](infrastructure_IAM_role.md). + Your IAM role doesn't have the necessary permissions for Amazon EBS volume attachment. The task can get stuck in the `DEPROVISIONING` state. For more information about the specific permissions necessary for attaching Amazon EBS volumes to tasks, see [Amazon ECS infrastructure IAM role](infrastructure_IAM_role.md). You may also see this error message due to a delay in role propagation. If retrying to use the role after waiting for a few minutes doesn't fix the issue, you might have misconfigured the trust policy for the role. ECS failed to set up the EBS volume. Encountered IdempotentParameterMismatch"; "The client token you have provided is associated with a resource that is already deleted. Please use a different client token." The following AWS KMS key scenarios can lead to an `IdempotentParameterMismatch` message appearing: + You specify a KMS key ARN, ID, or alias that isn't valid. In this scenario, the task might appear to launch successfully, but the task eventually fails because AWS authenticates the KMS key asynchronously. For more information, see [Amazon EBS encryption](https://docs.aws.amazon.com/ebs/latest/userguide/ebs-encryption.html) in the *Amazon EC2 User Guide*. + You provide a customer managed key that lacks the permissions that allow the Amazon ECS infrastructure IAM role to use the key for encryption. To avoid key-policy permission issues, see the example AWS KMS key policy in [Data encryption for Amazon EBS volumes](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ebs-volumes.html#ebs-kms-encryption). You can set up Amazon EventBridge to send Amazon EBS volume events and Amazon ECS task state change events to a target, such as Amazon CloudWatch groups. You can then use these events to identify the specific customer managed key related issue that affected volume attachment. For more information, see + [How can I create a CloudWatch log group to use as a target for an EventBridge rule?](https://repost.aws/knowledge-center/cloudwatch-log-group-eventbridge) on AWS re:Post. + [Task state change events](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs_cwe_events.html#ecs_task_events). + [Amazon EventBridge events for Amazon EBS](https://docs.aws.amazon.com/ebs/latest/userguide/ebs-cloud-watch-events.html) in the *Amazon EBS User Guide*. ECS timed out while configuring the EBS volume attachment to your Task. The following file system format scenarios result in this message. + The file system format that you specify during configuration isn't compatible with the [task's operating system](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_RuntimePlatform.html). + You configure an Amazon EBS volume to be created from a snapshot, and the snapshot's file system format isn't compatible with the task's operating system. For volumes created from a snapshot, you must specify the same filesystem type that the volume was using when the snapshot was created. You can utilize the Amazon ECS container agent logs to troubleshoot this message for EC2 tasks. For more information, see [Amazon ECS log file locations](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/logs.html) and [Amazon ECS log collector](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-logs-collector.html). # Use Amazon EFS volumes with Amazon ECS Amazon EFS Amazon Elastic File System (Amazon EFS) provides simple, scalable file storage for use with your Amazon ECS tasks. With Amazon EFS, storage capacity is elastic. It grows and shrinks automatically as you add and remove files. Your applications can have the storage they need and when they need it. You can use Amazon EFS file systems with Amazon ECS to export file system data across your fleet of container instances. That way, your tasks have access to the same persistent storage, no matter the instance on which they land. Your task definitions must reference volume mounts on the container instance to use the file system. For a tutorial, see [Configuring Amazon EFS file systems for Amazon ECS using the console](tutorial-efs-volumes.md). ## Considerations Consider the following when using Amazon EFS volumes: + For tasks that run on EC2, Amazon EFS file system support was added as a public preview with Amazon ECS-optimized AMI version `20191212` with container agent version 1.35.0. However, Amazon EFS file system support entered general availability with Amazon ECS-optimized AMI version `20200319` with container agent version 1.38.0, which contained the Amazon EFS access point and IAM authorization features. We recommend that you use Amazon ECS-optimized AMI version `20200319` or later to use these features. For more information, see [Amazon ECS-optimized Linux AMIs](ecs-optimized_AMI.md). **Note** If you create your own AMI, you must use container agent 1.38.0 or later, `ecs-init` version 1.38.0-1 or later, and run the following commands on your Amazon EC2 instance to enable the Amazon ECS volume plugin. The commands are dependent on whether you're using Amazon Linux 2 or Amazon Linux as your base image. Amazon Linux 2 ``` yum install amazon-efs-utils systemctl enable --now amazon-ecs-volume-plugin ``` Amazon Linux ``` yum install amazon-efs-utils sudo shutdown -r now ``` + For tasks that are hosted on Fargate, Amazon EFS file systems are supported on platform version 1.4.0 or later (Linux). For more information, see [Fargate platform versions for Amazon ECS](platform-fargate.md). + When using Amazon EFS volumes for tasks that are hosted on Fargate, Fargate creates a supervisor container that's responsible for managing the Amazon EFS volume. The supervisor container uses a small amount of the task's memory and CPU. The supervisor container is visible when querying the task metadata version 4 endpoint. Additionally, it is visible in CloudWatch Container Insights as the container name `aws-fargate-supervisor`. For more information when using the EC2, see [Amazon ECS task metadata endpoint version 4](task-metadata-endpoint-v4.md). For more information when using the Fargate, see [Amazon ECS task metadata endpoint version 4 for tasks on Fargate](task-metadata-endpoint-v4-fargate.md). + Using Amazon EFS volumes or specifying an `EFSVolumeConfiguration` isn't supported on external instances. + Using Amazon EFS volumes is supported for tasks that run on Amazon ECS Managed Instances. + We recommend that you set the `ECS_ENGINE_TASK_CLEANUP_WAIT_DURATION` parameter in the agent configuration file to a value that is less than the default (about 1 hour). This change helps prevent EFS mount credential expiration and allows for cleanup of mounts that are not in use. For more information, see [Amazon ECS container agent configuration](ecs-agent-config.md). ## Use Amazon EFS access points Amazon EFS access points are application-specific entry points into an EFS file system for managing application access to shared datasets. For more information about Amazon EFS access points and how to control access to them, see [Working with Amazon EFS Access Points](https://docs.aws.amazon.com/efs/latest/ug/efs-access-points.html) in the *Amazon Elastic File System User Guide*. Access points can enforce a user identity, including the user's POSIX groups, for all file system requests that are made through the access point. Access points can also enforce a different root directory for the file system. This is so that clients can only access data in the specified directory or its subdirectories. **Note** When creating an EFS access point, specify a path on the file system to serve as the root directory. When referencing the EFS file system with an access point ID in your Amazon ECS task definition, the root directory must either be omitted or set to `/`, which enforces the path set on the EFS access point. You can use an Amazon ECS task IAM role to enforce that specific applications use a specific access point. By combining IAM policies with access points, you can provide secure access to specific datasets for your applications. For more information about how to use task IAM roles, see [Amazon ECS task IAM role](task-iam-roles.md). # Best practices for using Amazon EFS volumes with Amazon ECS Best practices for using Amazon EFS Make note of the following best practice recommendations when you use Amazon EFS with Amazon ECS. ## Security and access controls for Amazon EFS volumes Amazon EFS offers access control features that you can use to ensure that the data stored in an Amazon EFS file system is secure and accessible only from applications that need it. You can secure data by enabling encryption at rest and in-transit. For more information, see [Data encryption in Amazon EFS](https://docs.aws.amazon.com/efs/latest/ug/encryption.html) in the *Amazon Elastic File System User Guide*. In addition to data encryption, you can also use Amazon EFS to restrict access to a file system. There are three ways to implement access control in EFS. + **Security groups**—With Amazon EFS mount targets, you can configure a security group that's used to permit and deny network traffic. You can configure the security group attached to Amazon EFS to permit NFS traffic (port 2049) from the security group that's attached to your Amazon ECS instances or, when using the `awsvpc` network mode, the Amazon ECS task. + **IAM**—You can restrict access to an Amazon EFS file system using IAM. When configured, Amazon ECS tasks require an IAM role for file system access to mount an EFS file system. For more information, see [Using IAM to control file system data access](https://docs.aws.amazon.com/efs/latest/ug/iam-access-control-nfs-efs.html) in the *Amazon Elastic File System User Guide*. IAM policies can also enforce predefined conditions such as requiring a client to use TLS when connecting to an Amazon EFS file system. For more information, see [Amazon EFS condition keys for clients](https://docs.aws.amazon.com/efs/latest/ug/iam-access-control-nfs-efs.html#efs-condition-keys-for-nfs) in the *Amazon Elastic File System User Guide*. + **Amazon EFS access points**—Amazon EFS access points are application-specific entry points into an Amazon EFS file system. You can use access points to enforce a user identity, including the user's POSIX groups, for all file system requests that are made through the access point. Access points can also enforce a different root directory for the file system. This is so that clients can only access data in the specified directory or its sub-directories. ### IAM policies You can use IAM policies to control the access to the Amazon EFS file system. You can specify the following actions for clients accessing a file system using a file system policy. | Action | Description | | --- | --- | | `elasticfilesystem:ClientMount` | Provides read-only access to a file system. | | `elasticfilesystem:ClientWrite` | Provides write permissions on a file system. | | `elasticfilesystem:ClientRootAccess` | Provides use of the root user when accessing a file system. | You need to specify each action in a policy. The policies can be defined in the following ways: + Client-based - Attach the policy to the task role Set the **IAM authorization** option when you create the task definition. + Resource-based - Attach the policy to Amazon EFS file system If the resource-based policy does not exist, by default at file system creation access is granted to all principals (\$1). When you set the **IAM authorization** option, we merge the the policy associated with the task role and the Amazon EFS resource-based. The **IAM authorization** option passes the task identity (the task role) with the policy to Amazon EFS. This allows the Amazon EFS resource-based policy to have context for the IAM user or role specified in the policy. If you do not set the option, the Amazon EFS resource-level policy identifies the IAM user as ”anonymous". Consider implementing all three access controls on an Amazon EFS file system for maximum security. For example, you can configure the security group attached to an Amazon EFS mount point to only permit ingress NFS traffic from a security group that's associated with your container instance or Amazon ECS task. Additionally, you can configure Amazon EFS to require an IAM role to access the file system, even if the connection originates from a permitted security group. Last, you can use Amazon EFS access points to enforce POSIX user permissions and specify root directories for applications. The following task definition snippet shows how to mount an Amazon EFS file system using an access point. ``` "volumes": [ { "efsVolumeConfiguration": { "fileSystemId": "fs-1234", "authorizationConfig": { "accessPointId": "fsap-1234", "iam": "ENABLED" }, "transitEncryption": "ENABLED", "rootDirectory": "" }, "name": "my-filesystem" } ] ``` ## Amazon EFS volume performance Amazon EFS offers two performance modes: General Purpose and Max I/O. General Purpose is suitable for latency-sensitive applications such as content management systems and CI/CD tools. In contrast, Max I/O file systems are suitable for workloads such as data analytics, media processing, and machine learning. These workloads need to perform parallel operations from hundreds or even thousands of containers and require the highest possible aggregate throughput and IOPS. For more information, see [Amazon EFS performance modes](https://docs.aws.amazon.com/efs/latest/ug/performance.html#performancemodes) in the *Amazon Elastic File System User Guide*. Some latency sensitive workloads require both the higher I/O levels that are provided by Max I/O performance mode and the lower latency that are provided by General Purpose performance mode. For this type of workload, we recommend creating multiple General Purpose performance mode file systems. That way, you can spread your application workload across all these file systems, as long as the workload and applications can support it. ## Amazon EFS volume throughput All Amazon EFS file systems have an associated metered throughput that's determined by either the amount of provisioned throughput for file systems using *Provisioned Throughput* or the amount of data stored in the EFS Standard or One Zone storage class for file systems using *Bursting Throughput*. For more information, see [Understanding metered throughput](https://docs.aws.amazon.com/efs/latest/ug/performance.html#read-write-throughput) in the *Amazon Elastic File System User Guide*. The default throughput mode for Amazon EFS file systems is bursting mode. With bursting mode, the throughput that's available to a file system scales in or out as a file system grows. Because file-based workloads typically spike, requiring high levels of throughput for periods of time and lower levels of throughput the rest of the time, Amazon EFS is designed to burst to allow high throughput levels for periods of time. Additionally, because many workloads are read-heavy, read operations are metered at a 1:3 ratio to other NFS operations (like write). All Amazon EFS file systems deliver a consistent baseline performance of 50 MB/s for each TB of Amazon EFS Standard or Amazon EFS One Zone storage. All file systems (regardless of size) can burst to 100 MB/s. File systems with more than 1TB of EFS Standard or EFS One Zone storage can burst to 100 MB/s for each TB. Because read operations are metered at a 1:3 ratio, you can drive up to 300 MiBs/s for each TiB of read throughput. As you add data to your file system, the maximum throughput that's available to the file system scales linearly and automatically with your storage in the Amazon EFS Standard storage class. If you need more throughput than you can achieve with your amount of data stored, you can configure Provisioned Throughput to the specific amount your workload requires. File system throughput is shared across all Amazon EC2 instances connected to a file system. For example, a 1TB file system that can burst to 100 MB/s of throughput can drive 100 MB/s from a single Amazon EC2 instance can each drive 10 MB/s. For more information, see [Amazon EFS performance](https://docs.aws.amazon.com/efs/latest/ug/performance.html) in the *Amazon Elastic File System User Guide*. ## Optimizing cost for Amazon EFS volumes Amazon EFS simplifies scaling storage for you. Amazon EFS file systems grow automatically as you add more data. Especially with Amazon EFS *Bursting Throughput* mode, throughput on Amazon EFS scales as the size of your file system in the standard storage class grows. To improve the throughput without paying an additional cost for provisioned throughput on an EFS file system, you can share an Amazon EFS file system with multiple applications. Using Amazon EFS access points, you can implement storage isolation in shared Amazon EFS file systems. By doing so, even though the applications still share the same file system, they can't access data unless you authorize it. As your data grows, Amazon EFS helps you automatically move infrequently accessed files to a lower storage class. The Amazon EFS Standard-Infrequent Access (IA) storage class reduces storage costs for files that aren't accessed every day. It does this without sacrificing the high availability, high durability, elasticity, and the POSIX file system access that Amazon EFS provides. For more information, see [EFS storage classes](https://docs.aws.amazon.com/efs/latest/ug/features.html) in the *Amazon Elastic File System User Guide*. Consider using Amazon EFS lifecycle policies to automatically save money by moving infrequently accessed files to Amazon EFS IA storage. For more information, see [Amazon EFS lifecycle management](https://docs.aws.amazon.com/efs/latest/ug/lifecycle-management-efs.html) in the *Amazon Elastic File System User Guide*. When creating an Amazon EFS file system, you can choose if Amazon EFS replicates your data across multiple Availability Zones (Standard) or stores your data redundantly within a single Availability Zone. The Amazon EFS One Zone storage class can reduce storage costs by a significant margin compared to Amazon EFS Standard storage classes. Consider using Amazon EFS One Zone storage class for workloads that don't require multi-AZ resilience. You can further reduce the cost of Amazon EFS One Zone storage by moving infrequently accessed files to Amazon EFS One Zone-Infrequent Access. For more information, see [Amazon EFS Infrequent Access](https://aws.amazon.com/efs/features/infrequent-access/). ## Amazon EFS volume data protection Amazon EFS stores your data redundantly across multiple Availability Zones for file systems using Standard storage classes. If you select Amazon EFS One Zone storage classes, your data is redundantly stored within a single Availability Zone. Additionally, Amazon EFS is designed to provide 99.999999999% (11 9’s) of durability over a given year. As with any environment, it's a best practice to have a backup and to build safeguards against accidental deletion. For Amazon EFS data, that best practice includes a functioning, regularly tested backup using AWS Backup. File systems using Amazon EFS One Zone storage classes are configured to automatically back up files by default at file system creation unless you choose to disable this functionality. For more information, see [Backing up EFS file systems](https://docs.aws.amazon.com/efs/latest/ug/awsbackup.html) in the *Amazon Elastic File System User Guide*. # Specify an Amazon EFS file system in an Amazon ECS task definition Specify an Amazon EFS file system in a task definition To use Amazon EFS file system volumes for your containers, you must specify the volume and mount point configurations in your task definition. The following task definition JSON snippet shows the syntax for the `volumes` and `mountPoints` objects for a container. ``` { "containerDefinitions": [ { "name": "container-using-efs", "image": "public.ecr.aws/amazonlinux/amazonlinux:latest", "entryPoint": [ "sh", "-c" ], "command": [ "ls -la /mount/efs" ], "mountPoints": [ { "sourceVolume": "myEfsVolume", "containerPath": "/mount/efs", "readOnly": true } ] } ], "volumes": [ { "name": "myEfsVolume", "efsVolumeConfiguration": { "fileSystemId": "fs-1234", "rootDirectory": "/path/to/my/data", "transitEncryption": "ENABLED", "transitEncryptionPort": integer, "authorizationConfig": { "accessPointId": "fsap-1234", "iam": "ENABLED" } } } ] } ``` `efsVolumeConfiguration` Type: Object Required: No This parameter is specified when using Amazon EFS volumes. `fileSystemId` Type: String Required: Yes The Amazon EFS file system ID to use. `rootDirectory` Type: String Required: No The directory within the Amazon EFS file system to mount as the root directory inside the host. If this parameter is omitted, the root of the Amazon EFS volume is used. Specifying `/` has the same effect as omitting this parameter. If an EFS access point is specified in the `authorizationConfig`, the root directory parameter must either be omitted or set to `/`, which enforces the path set on the EFS access point. `transitEncryption` Type: String Valid values: `ENABLED` \$1 `DISABLED` Required: No Specifies whether to enable encryption for Amazon EFS data in transit between the Amazon ECS host and the Amazon EFS server. If Amazon EFS IAM authorization is used, transit encryption must be enabled. If this parameter is omitted, the default value of `DISABLED` is used. For more information, see [Encrypting Data in Transit](https://docs.aws.amazon.com/efs/latest/ug/encryption-in-transit.html) in the *Amazon Elastic File System User Guide*. `transitEncryptionPort` Type: Integer Required: No The port to use when sending encrypted data between the Amazon ECS host and the Amazon EFS server. If you don't specify a transit encryption port, it uses the port selection strategy that the Amazon EFS mount helper uses. For more information, see [EFS Mount Helper](https://docs.aws.amazon.com/efs/latest/ug/efs-mount-helper.html) in the *Amazon Elastic File System User Guide*. `authorizationConfig` Type: Object Required: No The authorization configuration details for the Amazon EFS file system. `accessPointId` Type: String Required: No The access point ID to use. If an access point is specified, the root directory value in the `efsVolumeConfiguration` must either be omitted or set to `/`, which enforces the path set on the EFS access point. If an access point is used, transit encryption must be enabled in the `EFSVolumeConfiguration`. For more information, see [Working with Amazon EFS Access Points](https://docs.aws.amazon.com/efs/latest/ug/efs-access-points.html) in the *Amazon Elastic File System User Guide*. `iam` Type: String Valid values: `ENABLED` \$1 `DISABLED` Required: No Specifies whether to use the Amazon ECS task IAM role defined in a task definition when mounting the Amazon EFS file system. If enabled, transit encryption must be enabled in the `EFSVolumeConfiguration`. If this parameter is omitted, the default value of `DISABLED` is used. For more information, see [IAM Roles for Tasks](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html). # Configuring Amazon EFS file systems for Amazon ECS using the console Configuring Amazon EFS file systems Learn how to use Amazon Elastic File System (Amazon EFS) file systems with Amazon ECS. ## Step 1: Create an Amazon ECS cluster Use the following steps to create an Amazon ECS cluster. **To create a new cluster (Amazon ECS console)** Before you begin, assign the appropriate IAM permission. For more information, see [Amazon ECS cluster examples](security_iam_id-based-policy-examples.md#IAM_cluster_policies). 1. Open the console at [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2). 1. From the navigation bar, select the Region to use. 1. In the navigation pane, choose **Clusters**. 1. On the **Clusters** page, choose **Create cluster**. 1. Under **Cluster configuration**, for **Cluster name**, enter `EFS-tutorial` for the cluster name. 1. (Optional) To change the VPC and subnets where your tasks and services launch, under **Networking**, perform any of the following operations: + To remove a subnet, under **Subnets**, choose **X** for each subnet that you want to remove. + To change to a VPC other than the **default** VPC, under **VPC**, choose an existing **VPC**, and then under **Subnets**, select each subnet. 1. To add Amazon EC2 instances to your cluster, expand **Infrastructure**, and then select **Amazon EC2 instances**. Next, configure the Auto Scaling group which acts as the capacity provider: 1. To create a Auto Scaling group, from **Auto Scaling group (ASG)**, select **Create new group**, and then provide the following details about the group: + For **Operating system/Architecture**, choose Amazon Linux 2. + For **EC2 instance type**, choose `t2.micro`. For **SSH key pair**, choose the pair that proves your identity when you connect to the instance. + For **Capacity**, enter `1`. 1. Choose **Create**. ## Step 2: Create a security group for Amazon EC2 instances and the Amazon EFS file system In this step, you create a security group for your Amazon EC2 instances that allows inbound network traffic on port 80 and your Amazon EFS file system that allows inbound access from your container instances. Create a security group for your Amazon EC2 instances with the following options: + **Security group name** - a unique name for your security group. + **VPC** - the VPC that you identified earlier for your cluster. + **Inbound rule** + **Type** - **HTTP** + **Source** - **0.0.0.0/0**. Create a security group for your Amazon EFS file system with the following options: + **Security group name** - a unique name for your security group. For example, `EFS-access-for-sg-dc025fa2`. + **VPC** - the VPC that you identified earlier for your cluster. + **Inbound rule** + **Type** - **NFS** + **Source** - **Custom** with the ID of the security group you created for your instances. For information about how to create a security group, see [Create a security group for your Amazon EC2 instance](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/creating-security-group.html) in the *Amazon EC2 User Guide*. ## Step 3: Create an Amazon EFS file system In this step, you create an Amazon EFS file system. **To create an Amazon EFS file system for Amazon ECS tasks.** 1. Open the Amazon Elastic File System console at [https://console.aws.amazon.com/efs/](https://console.aws.amazon.com/efs/). 1. Choose **Create file system**. 1. Enter a name for your file system and then choose the VPC that your container instances are hosted in. By default, each subnet in the specified VPC receives a mount target that uses the default security group for that VPC. Then, choose ** Customize**. **Note** This tutorial assumes that your Amazon EFS file system, Amazon ECS cluster, container instances, and tasks are in the same VPC. For more information about mounting a file system from a different VPC, see [Walkthrough: Mount a file system from a different VPC](https://docs.aws.amazon.com/efs/latest/ug/efs-different-vpc.html) in the *Amazon EFS User Guide*. 1. On the **File system settings** page, configure optional settings and then under **Performance settings**, choose the **Bursting** throughput mode for your file system. After you have configured settings, select **Next**. 1. (Optional) Add tags for your file system. For example, you could specify a unique name for the file system by entering that name in the **Value** column next to the **Name** key. 1. (Optional) Enable lifecycle management to save money on infrequently accessed storage. For more information, see [EFS Lifecycle Management](https://docs.aws.amazon.com/efs/latest/ug/lifecycle-management-efs.html) in the *Amazon Elastic File System User Guide*. 1. (Optional) Enable encryption. Select the check box to enable encryption of your Amazon EFS file system at rest. 1. On the **Network access** page, under **Mount targets**, replace the existing security group configuration for every availability zone with the security group you created for the file system in [Step 2: Create a security group for Amazon EC2 instances and the Amazon EFS file system](#efs-security-group) and then choose **Next**. 1. You do not need to configure **File system policy** for this tutorial, so you can skip the section by choosing **Next**. 1. Review your file system options and choose **Create** to complete the process. 1. From the **File systems** screen, record the **File system ID**. In the next step, you will reference this value in your Amazon ECS task definition. ## Step 4: Add content to the Amazon EFS file system In this step, you mount the Amazon EFS file system to an Amazon EC2 instance and add content to it. This is for testing purposes in this tutorial, to illustrate the persistent nature of the data. When using this feature you would normally have your application or another method of writing data to your Amazon EFS file system. **To create an Amazon EC2 instance and mount the Amazon EFS file system** 1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/). 1. Choose **Launch Instance**. 1. Under **Application and OS Images (Amazon Machine Image)**, select the **Amazon Linux 2 AMI (HVM)**. 1. Under **Instance type**, keep the default instance type, `t2.micro`. 1. Under **Key pair (login)**, select a key pair for SSH access to the instance. 1. Under **Network settings**, select the VPC that you specified for your Amazon EFS file system and Amazon ECS cluster. Select a subnet and the instance security group created in [Step 2: Create a security group for Amazon EC2 instances and the Amazon EFS file system](#efs-security-group). Configure the instance's security group. Ensure that **Auto-assign public IP** is enabled. 1. Under **Configure storage**, choose the **Edit** button for file systems and then choose **EFS**. Select the file system you created in [Step 3: Create an Amazon EFS file system](#efs-create-filesystem). You can optionally change the mount point or leave the default value. **Important** Your must select a subnet before you can add a file system to the instance. 1. Clear the **Automatically create and attach security groups**. Leave the other check box selected. Choose **Add shared file system**. 1. Under **Advanced Details**, ensure that the user data script is populated automatically with the Amazon EFS file system mounting steps. 1. Under **Summary**, ensure the **Number of instances** is **1**. Choose **Launch instance**. 1. On the **Launch an instance** page, choose **View all instances** to see the status of your instances. Initially, the **Instance state** status is `PENDING`. After the state changes to `RUNNING` and the instance passes all status checks, the instance is ready for use. Now, you connect to the Amazon EC2 instance and add content to the Amazon EFS file system. **To connect to the Amazon EC2 instance and add content to the Amazon EFS file system** 1. SSH to the Amazon EC2 instance you created. For more information, see [Connect to your Linux instance using SSH](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/connect-to-linux-instance.html) in the *Amazon EC2 User Guide*. 1. From the terminal window, run the **df -T** command to verify that the Amazon EFS file system is mounted. In the following output, we have highlighted the Amazon EFS file system mount. ``` $ df -T Filesystem Type 1K-blocks Used Available Use% Mounted on devtmpfs devtmpfs 485468 0 485468 0% /dev tmpfs tmpfs 503480 0 503480 0% /dev/shm tmpfs tmpfs 503480 424 503056 1% /run tmpfs tmpfs 503480 0 503480 0% /sys/fs/cgroup /dev/xvda1 xfs 8376300 1310952 7065348 16% / 127.0.0.1:/ nfs4 9007199254739968 0 9007199254739968 0% /mnt/efs/fs1 tmpfs tmpfs 100700 0 100700 0% /run/user/1000 ``` 1. Navigate to the directory that the Amazon EFS file system is mounted at. In the example above, that is `/mnt/efs/fs1`. 1. Create a file named `index.html` with the following content: ```You are using an Amazon EFS file system for persistent container storage.
``` ## Step 5: Create a task definition The following task definition creates a data volume named `efs-html`. The `nginx` container mounts the host data volume at the NGINX root, `/usr/share/nginx/html`. **To create a new task definition using the Amazon ECS console** 1. Open the console at [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2). 1. In the navigation pane, choose **Task definitions**. 1. Choose **Create new task definition**, **Create new task definition with JSON**. 1. In the JSON editor box, copy and paste the following JSON text, replacing the `fileSystemId` with the ID of your Amazon EFS file system. ``` { "containerDefinitions": [ { "memory": 128, "portMappings": [ { "hostPort": 80, "containerPort": 80, "protocol": "tcp" } ], "essential": true, "mountPoints": [ { "containerPath": "/usr/share/nginx/html", "sourceVolume": "efs-html" } ], "name": "nginx", "image": "public.ecr.aws/docker/library/nginx:latest" } ], "volumes": [ { "name": "efs-html", "efsVolumeConfiguration": { "fileSystemId": "fs-1324abcd", "transitEncryption": "ENABLED" } } ], "family": "efs-tutorial", "executionRoleArn":"arn:aws:iam::111122223333:role/ecsTaskExecutionRole" } ``` **Note** The Amazon ECS task execution IAM role does not require any specific Amazon EFS-related permissions to mount an Amazon EFS file system. By default, if no Amazon EFS resource-based policy exists, access is granted to all principals (\$1) at file system creation. The Amazon ECS task role is only required if "EFS IAM authorization" is enabled in the Amazon ECS task definition. When enabled, the task role identity must be allowed access to the Amazon EFS file system in the Amazon EFS resource-based policy, and anonymous access should be disabled. 1. Choose **Create**. ## Step 6: Run a task and view the results Now that your Amazon EFS file system is created and there is web content for the NGINX container to serve, you can run a task using the task definition that you created. The NGINX web server serves your simple HTML page. If you update the content in your Amazon EFS file system, those changes are propagated to any containers that have also mounted that file system. The task runs in the subnet that you defined for the cluster. **To run a task and view the results using the console** 1. Open the console at [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2). 1. On the **Clusters** page, select the cluster to run the standalone task in. Determine the resource from where you launch the service. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonECS/latest/developerguide/tutorial-efs-volumes.html) 1. (Optional) Choose how your scheduled task is distributed across your cluster infrastructure. Expand **Compute configuration**, and then do the following: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonECS/latest/developerguide/tutorial-efs-volumes.html) 1. For **Application type**, choose **Task**. 1. For **Task definition**, choose the `efs-tutorial` task definition that you created earlier. 1. For **Desired tasks**, enter `1`. 1. Choose **Create**. 1. On the **Cluster** page, choose **Infrastructure**. 1. Under **Container Instances**, choose the container instance to connect to. 1. On the **Container Instance** page, under **Networking**, record the **Public IP** for your instance. 1. Open a browser and enter the public IP address. You should see the following message: ``` It works! You are using an Amazon EFS file system for persistent container storage. ``` **Note** If you do not see the message, make sure that the security group for your container instance allows inbound network traffic on port 80 and the security group for your file system allows inbound access from the container instance. # Use FSx for Windows File Server volumes with Amazon ECS FSx for Windows File Server FSx for Windows File Server provides fully managed Windows file servers, that are backed by a Windows file system. When using FSx for Windows File Server together with ECS, you can provision your Windows tasks with persistent, distributed, shared, static file storage. For more information, see [What Is FSx for Windows File Server?](https://docs.aws.amazon.com/fsx/latest/WindowsGuide/what-is.html). **Note** EC2 instances that use the Amazon ECS-Optimized Windows Server 2016 Full AMI do not support FSx for Windows File Server ECS task volumes. You can't use FSx for Windows File Server volumes in a Windows containers on Fargate configuration. Instead, you can [modify containers to mount them on startup](https://aws.amazon.com/blogs/containers/use-smb-storage-with-windows-containers-on-aws-fargate/). You can use FSx for Windows File Server to deploy Windows workloads that require access to shared external storage, highly-available Regional storage, or high-throughput storage. You can mount one or more FSx for Windows File Server file system volumes to an Amazon ECS container that runs on an Amazon ECS Windows instance. You can share FSx for Windows File Server file system volumes between multiple Amazon ECS containers within a single Amazon ECS task. To enable the use of FSx for Windows File Server with ECS, include the FSx for Windows File Server file system ID and the related information in a task definition. This is in the following example task definition JSON snippet. Before you create and run a task definition, you need the following. + An ECS Windows EC2 instance that's joined to a valid domain. It can be hosted by an [AWS Directory Service for Microsoft Active Directory](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/directory_microsoft_ad.html), on-premises Active Directory or self-hosted Active Directory on Amazon EC2. + An AWS Secrets Manager secret or Systems Manager parameter that contains the credentials that are used to join the Active Directory domain and attach the FSx for Windows File Server file system. The credential values are the name and password credentials that you entered when creating the Active Directory. For a related tutorial, see [Learn how to configure FSx for Windows File Server file systems for Amazon ECS](tutorial-wfsx-volumes.md). ## Considerations Consider the following when using FSx for Windows File Server volumes: + FSx for Windows File Server volumes are natively supported with Amazon ECS on Windows Amazon EC2 instances — Amazon ECS automatically manages the mount through task definition configuration. On Linux Amazon EC2 instances, Amazon ECS can't automatically mount FSx for Windows File Server volumes through task definitions. However, you can manually mount an FSx for Windows File Server file share on a Linux EC2 instance at the host level and then bind-mount that path into your Amazon ECS containers. For more information, see [Mounting Amazon FSx file shares from Linux](https://docs.aws.amazon.com/fsx/latest/WindowsGuide/map-shares-linux.html). **Important** This is a self-managed configuration. For guidance on mounting and maintaining FSx for Windows File Server file shares on Linux, refer to the [FSx for Windows File Server documentation](https://docs.aws.amazon.com/fsx/latest/WindowsGuide/). **Important** When using a manually mounted FSx for Windows File Server share on Linux EC2 instances, Amazon ECS and FSx for Windows File Server operate independently — Amazon ECS does not monitor the Amazon FSx mount, and FSx for Windows File Server does not track Amazon ECS task placement or lifecycle events. You are responsible for ensuring network reachability between your Amazon ECS container instances and the Amazon FSx file system, implementing mount health checks, and handling reconnection logic to tolerate failover events. + FSx for Windows File Server with Amazon ECS doesn't support AWS Fargate. + FSx for Windows File Server with Amazon ECS isn't supported on Amazon ECS Managed Instances. + FSx for Windows File Server with Amazon ECS with `awsvpc` network mode requires version `1.54.0` or later of the container agent. + The maximum number of drive letters that can be used for an Amazon ECS task is 23. Each task with an FSx for Windows File Server volume gets a drive letter assigned to it. + By default, task resource cleanup time is three hours after the task ended. Even if no tasks use it, a file mapping that's created by a task persists for three hours. The default cleanup time can be configured by using the Amazon ECS environment variable `ECS_ENGINE_TASK_CLEANUP_WAIT_DURATION`. For more information, see [Amazon ECS container agent configuration](ecs-agent-config.md). + Tasks typically only run in the same VPC as the FSx for Windows File Server file system. However, it's possible to have cross-VPC support if there's an established network connectivity between the Amazon ECS cluster VPC and the FSx for Windows File Server file-system through VPC peering. + You control access to an FSx for Windows File Server file system at the network level by configuring the VPC security groups. Only tasks that are hosted on EC2 instances joined to the Active Directory domain with correctly configured Active Directory security groups can access the FSx for Windows File Server file-share. If the security groups are misconfigured, Amazon ECS fails to launch the task with the following error message: `unable to mount file system fs-id`.” + FSx for Windows File Server is integrated with AWS Identity and Access Management (IAM) to control the actions that your IAM users and groups can take on specific FSx for Windows File Server resources. With client authorization, customers can define IAM roles that allow or deny access to specific FSx for Windows File Server file systems, optionally require read-only access, and optionally allow or disallow root access to the file system from the client. For more information, see [Security](https://docs.aws.amazon.com/fsx/latest/WindowsGuide/security.html) in the Amazon FSx Windows User Guide. # Best practices for using FSx for Windows File Server with Amazon ECS Best practices for using FSx for Windows File Server Make note of the following best practice recommendations when you use FSx for Windows File Server with Amazon ECS. ## Security and access controls for FSx for Windows File Server FSx for Windows File Server offers the following access control features that you can use to ensure that the data stored in an FSx for Windows File Server file system is secure and accessible only from applications that need it. ### Data encryption for FSx for Windows File Server volumes FSx for Windows File Server supports two forms of encryption for file systems. They are encryption of data in transit and encryption at rest. Encryption of data in transit is supported on file shares that are mapped on a container instance that supports SMB protocol 3.0 or newer. Encryption of data at rest is automatically enabled when creating an Amazon FSx file system. Amazon FSx automatically encrypts data in transit using SMB encryption as you access your file system without the need for you to modify your applications. For more information, see [Data encryption in Amazon FSx](https://docs.aws.amazon.com/fsx/latest/WindowsGuide/encryption.html) in the *Amazon FSx for Windows File Server User Guide*. ### Use Windows ACLs for folder level access control The Windows Amazon EC2 instance access Amazon FSx file shares using Active Directory credentials. It uses standard Windows access control lists (ACLs) for fine-grained file-level and folder-level access control. You can create multiple credentials, each one for a specific folder within the share which maps to a specific task. In the following example, the task has access to the folder `App01` using a credential saved in Secrets Manager. Its Amazon Resource Name (ARN) is `1234`. ``` "rootDirectory": "\\path\\to\\my\\data\App01", "credentialsParameter": "arn-1234", "domain": "corp.fullyqualified.com", ``` In another example, a task has access to the folder `App02` using a credential saved in the Secrets Manager. Its ARN is `6789`. ``` "rootDirectory": "\\path\\to\\my\\data\App02", "credentialsParameter": "arn-6789", "domain": "corp.fullyqualified.com", ``` # Specify an FSx for Windows File Server file system in an Amazon ECS task definition Specify an FSx for Windows File Server file system in a task definition To use FSx for Windows File Server file system volumes for your containers, specify the volume and mount point configurations in your task definition. The following task definition JSON snippet shows the syntax for the `volumes` and `mountPoints` objects for a container. ``` { "containerDefinitions": [ { "entryPoint": [ "powershell", "-Command" ], "portMappings": [], "command": ["New-Item -Path C:\\fsx-windows-dir\\index.html -ItemType file -Value 'You are using Amazon FSx for Windows File Server file system for persistent container storage.
' -Force"], "cpu": 512, "memory": 256, "image": "mcr.microsoft.com/windows/servercore/iis:windowsservercore-ltsc2019", "essential": false, "name": "container1", "mountPoints": [ { "sourceVolume": "fsx-windows-dir", "containerPath": "C:\\fsx-windows-dir", "readOnly": false } ] }, { "entryPoint": [ "powershell", "-Command" ], "portMappings": [ { "hostPort": 443, "protocol": "tcp", "containerPort": 80 } ], "command": ["Remove-Item -Recurse C:\\inetpub\\wwwroot\\* -Force; Start-Sleep -Seconds 120; Move-Item -Path C:\\fsx-windows-dir\\index.html -Destination C:\\inetpub\\wwwroot\\index.html -Force; C:\\ServiceMonitor.exe w3svc"], "mountPoints": [ { "sourceVolume": "fsx-windows-dir", "containerPath": "C:\\fsx-windows-dir", "readOnly": false } ], "cpu": 512, "memory": 256, "image": "mcr.microsoft.com/windows/servercore/iis:windowsservercore-ltsc2019", "essential": true, "name": "container2" } ], "family": "fsx-windows", "executionRoleArn": "arn:aws:iam::111122223333:role/ecsTaskExecutionRole", "volumes": [ { "name": "fsx-windows-dir", "fsxWindowsFileServerVolumeConfiguration": { "fileSystemId": "fs-0eeb5730b2EXAMPLE", "authorizationConfig": { "domain": "example.com", "credentialsParameter": "arn:arn-1234" }, "rootDirectory": "share" } } ] } ``` `FSxWindowsFileServerVolumeConfiguration` Type: Object Required: No This parameter is specified when you're using [FSx for Windows File Server](https://docs.aws.amazon.com/fsx/latest/WindowsGuide/what-is.html) file system for task storage. `fileSystemId` Type: String Required: Yes The FSx for Windows File Server file system ID to use. `rootDirectory` Type: String Required: Yes The directory within the FSx for Windows File Server file system to mount as the root directory inside the host. `authorizationConfig` `credentialsParameter` Type: String Required: Yes The authorization credential options: + Amazon Resource Name (ARN) of an [Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) secret. + Amazon Resource Name (ARN) of an [Systems Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/integration-ps-secretsmanager.html) parameter. `domain` Type: String Required: Yes A fully qualified domain name that's hosted by an [AWS Directory Service for Microsoft Active Directory](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/directory_microsoft_ad.html) (AWS Managed Microsoft AD) directory or a self-hosted EC2 Active Directory. ## Methods for storing FSx for Windows File Server volume credentials There are two different methods of storing credentials for use with the credentials parameter. + **AWS Secrets Manager secret** This credential can be created in the AWS Secrets Manager console by using the *Other type of secret* category. You add a row for each key/value pair, username/admin and password/*password*. + **Systems Manager parameter** This credential can be created in the Systems Manager parameter console by entering text in the form that's in the following example code snippet. ``` { "username": "admin", "password": "password" } ``` The `credentialsParameter` in the task definition `FSxWindowsFileServerVolumeConfiguration` parameter holds either the secret ARN or the Systems Manager parameter ARN. For more information, see [What is AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) in the *Secrets Manager User Guide* and [Systems Manager Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html) from the *Systems Manager User Guide*. # Learn how to configure FSx for Windows File Server file systems for Amazon ECS Learn how to configure FSx for Windows File Server file systems Learn how to launch an Amazon ECS-Optimized Windows instance that hosts an FSx for Windows File Server file system and containers that can access the file system. To do this, you first create an Directory Service AWS Managed Microsoft Active Directory. Then, you create an FSx for Windows File Server File Server file system and cluster with an Amazon EC2 instance and a task definition. You configure the task definition for your containers to use the FSx for Windows File Server file system. Finally, you test the file system. It takes 20 to 45 minutes each time you launch or delete either the Active Directory or the FSx for Windows File Server file system. Be prepared to reserve at least 90 minutes to complete the tutorial or complete the tutorial over a few sessions. ## Prerequisites for the tutorial + An administrative user. See [Set up to use Amazon ECS](get-set-up-for-amazon-ecs.md). + (Optional) A `PEM` key pair for connecting to your EC2 Windows instance through RDP access. For information about how to create key pairs, see [Amazon EC2 key pairs and Amazon EC2 instances](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html) in the *Amazon EC2 User Guide*. + A VPC with at least one public and one private subnet, and one security group. You can use your default VPC. You don't need a NAT gateway or device. Directory Service doesn't support Network Address Translation (NAT) with Active Directory. For this to work, the Active Directory, FSx for Windows File Server file system, ECS Cluster, and EC2 instance must be located within your VPC. For more information regarding VPCs and Active Directories, see [Create a VPC](https://docs.aws.amazon.com/vpc/latest/userguide/create-vpc.html) and [Prerequisites for creating an AWS Managed Microsoft AD](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/ms_ad_getting_started.html#ms_ad_getting_started_prereqs). + The IAM ecsInstanceRole and ecsTaskExecutionRole permissions are associated with your account. These service-linked roles allow services to make API calls and access containers, secrets, directories, and file servers on your behalf. ## Step 1: Create IAM access roles **Create a cluster with the AWS Management Console.** 1. See [Amazon ECS container instance IAM role](instance_IAM_role.md) to check whether you have an ecsInstanceRole and to see how you can create one if you don't have one. 1. We recommend that role policies are customized for minimum permissions in an actual production environment. For the purpose of working through this tutorial, verify that the following AWS managed policy is attached to your ecsInstanceRole. Attach the policy if it is not already attached. + AmazonEC2ContainerServiceforEC2Role + AmazonSSMManagedInstanceCore + AmazonSSMDirectoryServiceAccess To attach AWS managed policies. 1. Open the [IAM console](https://console.aws.amazon.com//iam/). 1. In the navigation pane, choose **Roles.** 1. Choose an **AWS managed role**. 1. Choose **Permissions, Attach policies**. 1. To narrow the available policies to attach, use **Filter**. 1. Select the appropriate policy and choose **Attach policy**. 1. See [Amazon ECS task execution IAM role](task_execution_IAM_role.md) to check whether you have an ecsTaskExecutionRole and to see how you can create one if you don't have one. We recommend that role policies are customized for minimum permissions in an actual production environment. For the purpose of working through this tutorial, verify that the following AWS managed policies are attached to your ecsTaskExecutionRole. Attach the policies if they are not already attached. Use the procedure given in the preceding section to attach the AWS managed policies. + SecretsManagerReadWrite + AmazonFSxReadOnlyAccess + AmazonSSMReadOnlyAccess + AmazonECSTaskExecutionRolePolicy ## Step 2: Create Windows Active Directory (AD) 1. Follow the steps described in [Creating your AWS Managed Microsoft AD](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/ms_ad_getting_started.html#ms_ad_getting_started_create_directory) in the AWS *Directory Service Administration Guide*. Use the VPC you have designated for this tutorial. On Step 3 of *Creating your AWS Managed Microsoft AD*, save the user name and admin password for use in a following step. Also, note the fully qualified directory DNS name for future steps. You can complete the following step while the Active Directory is being created. 1. Create an AWS Secrets Manager secret to use in the following steps. For more information, see [Get started with Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html#get-started) in the AWS *Secrets Manager User Guide*. 1. Open the [Secrets Manager console](https://console.aws.amazon.com//secretsmanager/). 1. Click **Store a new secret**. 1. Select **Other type of secrets**. 1. For **Secret key/value**, in the first row, create a key **username** with value **admin**. Click on **\$1 Add row**. 1. In the new row, create a key **password**. For value, type in the password you entered in Step 3 of *Create Your AWS Managed AD Directory*. 1. Click on the **Next** button. 1. Provide a secret name and description. Click **Next**. 1. Click **Next**. Click **Store**. 1. From the list of **Secrets** page, click on the secret you have just created. 1. Save the ARN of the new secret for use in the following steps. 1. You can proceed to the next step while your Active Directory is being created. ## Step 3: Verify and update your security group In this step, you verify and update the rules for the security group that you're using. For this, you can use the default security group that was created for your VPC. **Verify and update security group.** You need to create or edit your security group to send data from and to the ports, which are described in [Amazon VPC Security Groups](https://docs.aws.amazon.com/fsx/latest/WindowsGuide/limit-access-security-groups.html#fsx-vpc-security-groups) in the *FSx for Windows File Server User Guide*. You can do this by creating the security group inbound rule shown in the first row of the following table of inbound rules. This rule allows inbound traffic from network interfaces (and their associated instances) that are assigned to the security group. All of the cloud resources you create are within the same VPC and attached to the same security group. Therefore, this rule allows traffic to be sent to and from the FSx for Windows File Server file system, Active Directory, and ECS instance as required. The other inbound rules allow traffic to serve the website and RDP access for connecting to your ECS instance. The following table shows which security group inbound rules are required for this tutorial. | Type | Protocol | Port range | Source | | --- | --- | --- | --- | | All traffic | All | All | *sg-securitygroup* | | HTTPS | TCP | 443 | 0.0.0.0/0 | | RDP | TCP | 3389 | your laptop IP address | The following table shows which security group outbound rules are required for this tutorial. | Type | Protocol | Port range | Destination | | --- | --- | --- | --- | | All traffic | All | All | 0.0.0.0/0 | 1. Open the [EC2 console](https://console.aws.amazon.com//ec2/) and select **Security Groups** from the left-hand menu. 1. From the list of security groups now displayed, select check the check-box to the left of the security group that you are using for this tutorial. Your security group details are displayed. 1. Edit the inbound and outbound rules by selecting the **Inbound rules** or **Outbound rules** tabs and choosing the **Edit inbound rules** or **Edit outbound rules** buttons. Edit the rules to match those displayed in the preceding tables. After you create your EC2 instance later on in this tutorial, edit the inbound rule RDP source with the public IP address of your EC2 instance as described in [Connect to your Windows instance using RDP](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/connecting_to_windows_instance.html) from the *Amazon EC2 User Guide*. ## Step 4: Create an FSx for Windows File Server file system After your security group is verified and updated and your Active Directory is created and is in the active status, create the FSx for Windows File Server file system in the same VPC as your Active Directory. Use the following steps to create an FSx for Windows File Server file system for your Windows tasks. **Create your first file system.** 1. Open the [Amazon FSx console](https://console.aws.amazon.com//fsx/). 1. On the dashboard, choose **Create file system** to start the file system creation wizard. 1. On the **Select file system type** page, choose **FSx for Windows File Server**, and then choose **Next**. The **Create file system** page appears. 1. In the **File system details** section, provide a name for your file system. Naming your file systems makes it easier to find and manage your them. You can use up to 256 Unicode characters. Allowed characters are letters, numbers, spaces, and the special characters plus sign (\$1). minus sign (-), equal sign (=), period (.), underscore (\$1), colon (:), and forward slash (/). 1. For **Deployment type** choose **Single-AZ** to deploy a file system that is deployed in a single Availability Zone. *Single-AZ 2* is the latest generation of single Availability Zone file systems, and it supports SSD and HDD storage. 1. For **Storage type**, choose **HDD**. 1. For **Storage capacity**, enter the minimum storage capacity. 1. Keep **Throughput capacity** at its default setting. 1. In the **Network & security** section, choose the same Amazon VPC that you chose for your Directory Service directory. 1. For **VPC Security Groups**, choose the security group that you verified in *Step 3: Verify and update your security group*. 1. For **Windows authentication**, choose **AWS Managed Microsoft Active Directory**, and then choose your Directory Service directory from the list. 1. For **Encryption**, keep the default **Encryption key** setting of **aws/fsx (default)**. 1. Keep the default settings for **Maintenance preferences**. 1. Click on the **Next** button. 1. Review the file system configuration shown on the **Create file system** page. For your reference, note which file system settings you can modify after file system is created. Choose **Create file system**. 1. Note the file system ID. You will need to use it in a later step. You can go on to the next steps to create a cluster and EC2 instance while the FSx for Windows File Server file system is being created. ## Step 5: Create an Amazon ECS cluster **Create a cluster using the Amazon ECS console** 1. Open the console at [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2). 1. From the navigation bar, select the Region to use. 1. In the navigation pane, choose **Clusters**. 1. On the **Clusters** page, choose **Create cluster**. 1. Under **Cluster configuration**, for **Cluster name**, enter **windows-fsx-cluster**. 1. Expand **Infrastructure**, clear AWS Fargate (serverless) and then select **Amazon EC2 instances**. 1. To create a Auto Scaling group, from **Auto Scaling group (ASG)**, select **Create new group**, and then provide the following details about the group: + For **Operating system/Architecture**, choose **Windows Server 2019 Core**. + For **EC2 instance type**, choose t2.medium or t2.micro. 1. Choose **Create**. ## Step 6: Create an Amazon ECS optimized Amazon EC2 instance Create an Amazon ECS Windows container instance. **To create an Amazon ECS instance** 1. Use the `aws ssm get-parameters` command to retrieve the AMI name for the Region that hosts your VPC. For more information, see [Retrieving Amazon ECS-Optimized AMI metadata](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/retrieve-ecs-optimized_windows_AMI.html). 1. Use the Amazon EC2 console to launch the instance. 1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/). 1. From the navigation bar, select the Region to use. 1. From the **EC2 Dashboard**, choose **Launch instance**. 1. For **Name**, enter a unique name. 1. For **Application and OS Images (Amazon Machine Image)**, in the **search** field, enter the AMI name that you retrieved. 1. For **Instance type**, choose t2.medium or t2.micro. 1. For **Key pair (login)**, choose a key pair. If you don't specify a key pair, you 1. Under **Network settings**, for **VPC** and **Subnet**, choose your VPC and a public subnet. 1. Under **Network settings**, for **Security group**, choose an existing security group, or create a new one. Ensure that the security group you choose has the inbound and outbound rules defined in [Prerequisites for the tutorial](#wfsx-prerequisites) 1. Under **Network settings**, for **Auto-assign Public IP**, select **Enable**. 1. Expand **Advanced details**, and then for **Domain join directory**, select the ID of the Active Directory that you created. This option domain joins your AD when the EC2 instance is launched. 1. Under **Advanced details**, for **IAM instance profile** , choose **ecsInstanceRole**. 1. Configure your Amazon ECS container instance with the following user data. Under **Advanced Details**, paste the following script into the **User data** field, replacing *cluster\$1name* with the name of your cluster. ```You are using Amazon FSx for Windows File Server file system for persistent container storage.
' -Force"], "cpu": 512, "memory": 256, "image": "mcr.microsoft.com/windows/servercore/iis:windowsservercore-ltsc2019", "essential": false, "name": "container1", "mountPoints": [ { "sourceVolume": "fsx-windows-dir", "containerPath": "C:\\fsx-windows-dir", "readOnly": false } ] }, { "entryPoint": [ "powershell", "-Command" ], "portMappings": [ { "hostPort": 443, "protocol": "tcp", "containerPort": 80 } ], "command": ["Remove-Item -Recurse C:\\inetpub\\wwwroot\\* -Force; Start-Sleep -Seconds 120; Move-Item -Path C:\\fsx-windows-dir\\index.html -Destination C:\\inetpub\\wwwroot\\index.html -Force; C:\\ServiceMonitor.exe w3svc"], "mountPoints": [ { "sourceVolume": "fsx-windows-dir", "containerPath": "C:\\fsx-windows-dir", "readOnly": false } ], "cpu": 512, "memory": 256, "image": "mcr.microsoft.com/windows/servercore/iis:windowsservercore-ltsc2019", "essential": true, "name": "container2" } ], "family": "fsx-windows", "executionRoleArn": "arn:aws:iam::111122223333:role/ecsTaskExecutionRole", "volumes": [ { "name": "fsx-windows-dir", "fsxWindowsFileServerVolumeConfiguration": { "fileSystemId": "fs-0eeb5730b2EXAMPLE", "authorizationConfig": { "domain": "example.com", "credentialsParameter": "arn:arn-1234" }, "rootDirectory": "share" } } ] } ``` ## Step 8: Run a task and view the results Before running the task, verify that the status of your FSx for Windows File Server file system is **Available**. After it is available, you can run a task using the task definition that you created. The task starts out by creating containers that shuffle an HTML file between them using the file system. After the shuffle, a web server serves the simple HTML page. **Note** You might not be able to connect to the website from within a VPN. **Run a task and view the results with the Amazon ECS console.** 1. Open the console at [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2). 1. In the navigation pane, choose **Clusters**, and then choose **windows-fsx-cluster**. 1. Choose the **Tasks** tab, and then choose **Run new task**. 1. For **Launch Type**, choose **EC2**. 1. Under Deployment configuration, for **Task Definition**, choose the **fsx-windows**, and then choose **Create**. 1. When your task status is **RUNNING**, choose the task ID. 1. Under **Containers**, when the container1 status is **STOPPED**, select container2 to view the container's details. 1. Under **Container details for container2**, select **Network bindings** and then click on the external IP address that is associated with the container. Your browser will open and display the following message. ``` Amazon ECS Sample App It Works! You are using Amazon FSx for Windows File Server file system for persistent container storage. ``` **Note** It may take a few minutes for the message to be displayed. If you don't see this message after a few minutes, check that you aren't running in a VPN and make sure that the security group for your container instance allows inbound network HTTP traffic on port 443. ## Step 9: Clean up **Note** It takes 20 to 45 minutes to delete the FSx for Windows File Server file system or the AD. You must wait until the FSx for Windows File Server file system delete operations are complete before starting the AD delete operations. **Delete FSx for Windows File Server file system.** 1. Open the [Amazon FSx console](https://console.aws.amazon.com//fsx/) 1. Choose the radio button to the left of the FSx for Windows File Server file system that you just created. 1. Choose **Actions**. 1. Select **Delete file system**. **Delete AD.** 1. Open the [Directory Service console](https://console.aws.amazon.com//directoryservicev2/). 1. Choose the radio button to the left of the AD you just created. 1. Choose **Actions**. 1. Select **Delete directory**. **Delete the cluster.** 1. Open the console at [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2). 1. In the navigation pane, choose **Clusters**, and then choose **windows-fsx-cluster**. 1. Choose **Delete cluster**. 1. Enter the phrase and then choose **Delete**. **Terminate EC2 instance.** 1. Open the [Amazon EC2 console](https://console.aws.amazon.com//ec2/). 1. From the left-hand menu, select **Instances**. 1. Check the box to the left of the EC2 instance you created. 1. Click the **Instance state**, **Terminate instance**. **Delete secret.** 1. Open the [Secrets Manager console](https://console.aws.amazon.com//secretsmanager/). 1. Select the secret you created for this walk through. 1. Click **Actions**. 1. Select **Delete secret**. # Configuring S3 Files for Amazon ECS Amazon S3 Files S3 Files is a shared file system that connects any AWS compute resource directly with your data in Amazon S3. It provides fast, direct access to all of your S3 data as files with full file system semantics and low-latency performance, without your data ever leaving S3. You can read, write, and organize data using file and directory operations, while S3 Files keeps your file system and S3 bucket synchronized automatically. With Amazon ECS, you can define S3 file systems as volumes in your task definitions, giving your containers direct file system access to data stored in S3 buckets. To learn more about Amazon S3 Files and its capabilities, see the [Amazon S3 User Guide](https://docs.aws.amazon.com/AmazonS3/latest/userguide/). ## Availability S3 Files support in Amazon ECS is available for the following launch types at General Availability: + **Fargate** — Fully supported. + **Amazon ECS Managed Instances** — Fully supported. **Important** S3 Files are not supported on the Amazon EC2 launch type at this time. If you configure an S3 file system in a task definition and attempt to run it on the Amazon EC2 launch type, the task will fail at launch. Amazon EC2 launch type support is planned for a future release. ## Considerations + S3 file system uses a dedicated `s3filesVolumeConfiguration` parameter in the task definition. + S3 file system requires a full Amazon Resource Name (ARN) to identify the file system. The ARN format is: ``` arn:{partition}:s3files:{region}:{account-id}:file-system/fs-xxxxx ``` + Transit encryption is mandatory for S3 file system volumes and is automatically enforced. There is no option to disable it. + Task IAM Role is mandatory for S3 file system volumes and is automatically enforced. There is no option to disable it. ## Prerequisites Before configuring S3 file system volumes in your Amazon ECS task definitions, ensure the following prerequisites are met: + **An S3 file system and mount target** — You must have an S3 file system created and associated with an S3 bucket. For instructions on creating an S3 file system, see the [Amazon S3 Files User Guide](https://docs.aws.amazon.com/AmazonS3/latest/userguide/). + **A Task IAM Role** — Your task definition must include a Task IAM Role with the following permissions: + Permissions to connect to and interact with S3 file systems from your application code (running in the container). + Permissions to read S3 objects from your application code (running in the container). + **VPC and security group configuration** — Your S3 file system must be accessible from the VPC and subnets where your Amazon ECS tasks run. + **(Optional) S3 Files access points** — If you want to enforce application-specific access controls, create an S3 Files access point and provide the ARN in the task definition. For more information, refer to [prerequisites for S3 Files](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-files-prereq-policies.html#s3-files-prereq-iam-compute-role). # Specify an Amazon S3 Files volume in your Amazon ECS task definition Specify an S3 Files volume in a task definition You can configure S3 Files volumes in your Amazon ECS task definitions using the Amazon ECS console, the AWS CLI, or the AWS API. ## Using the Amazon ECS console 1. Open the Amazon ECS console at [https://console.aws.amazon.com/ecs/](https://console.aws.amazon.com/ecs/). 1. In the navigation pane, choose **Task definitions**. 1. Choose **Create new task definition** or select an existing task definition and create a new revision. 1. In the **Infrastructure** section, ensure you have a Task IAM Role configured with the required permissions. 1. In the **Storage** section, choose **Add volume**. 1. For **Volume type**, select **S3 Files**. 1. For **File system ARN**, enter the full ARN of your S3 file system. The ARN format is: ``` arn:{partition}:s3files:{region}:{account-id}:file-system/fs-xxxxx ``` 1. (Optional) For **Root directory**, enter the path within the file system to mount as the root. If not specified, the root of the file system (`/`) is used. 1. (Optional) For **Transit encryption port**, enter the port number for sending encrypted data between the Amazon ECS host and the S3 file system. If you don't specify a transit encryption port, it uses the port selection strategy that the Amazon EFS mount helper uses. 1. (Optional) For **Access point ARN**, select the S3 Files access point to use from the dropdown list. 1. In the **Container mount points** section, select the container and specify the local mount path in your container where the volume should be mounted inside the container. 1. Choose **Create** to create the task definition. ## Using the AWS CLI To specify an S3 Files volume in a task definition using the AWS CLI, use the `register-task-definition` command with the `s3filesVolumeConfiguration` parameter in the volume definition. The following is an example task definition JSON snippet that defines an S3 Files volume and mounts it to a container: ``` { "family": "s3files-task-example", "taskRoleArn": "arn:aws:iam::123456789012:role/ecsTaskRole", "containerDefinitions": [ { "name": "my-container", "image": "my-image:latest", "essential": true, "mountPoints": [ { "containerPath": "/mnt/s3data", "sourceVolume": "my-s3files-volume" } ] } ], "volumes": [ { "name": "my-s3files-volume", "s3filesVolumeConfiguration": { "fileSystemArn": "arn:aws:s3files:us-east-1:123456789012:file-system/fs-0123456789abcdef0", "rootDirectory": "/", "transitEncryptionPort": 2999 } } ] } ``` Register the task definition: ``` aws ecs register-task-definition --cli-input-json file://s3files-task-def.json ``` To use an access point, include the `accessPointArn` parameter: ``` { "name": "my-s3files-volume", "s3filesVolumeConfiguration": { "fileSystemArn": "arn:aws:s3files:us-east-1:123456789012:file-system/fs-0123456789abcdef0", "rootDirectory": "/", "transitEncryptionPort": 2999, "accessPointArn": "arn:aws:s3files:us-east-1:123456789012:file-system/fs-0123456789abcdef0/access-point/fsap-0123456789abcdef0" } } ``` ## S3 Files volume configuration parameters The following table describes the parameters available in the `s3filesVolumeConfiguration` object: `fileSystemArn` Type: String Required: Yes The full ARN of the S3 file system to mount. Format: `arn:{partition}:s3files:{region}:{account-id}:file-system/fs-xxxxx` `rootDirectory` Type: String Required: No The directory within the S3 file system to mount as the root of the volume. Defaults to `/` if not specified. `transitEncryptionPort` Type: Integer Required: No The port to use for sending encrypted data between the Amazon ECS host and the S3 file system. Transit encryption itself is always enabled and cannot be disabled. `accessPointArn` Type: String Required: No The full ARN of the S3 Files access point to use. Access points provide application-specific entry points into the file system with enforced user identity and root directory settings. # Use Docker volumes with Amazon ECS Docker volumes When using Docker volumes, the built-in `local` driver or a third-party volume driver can be used. Docker volumes are managed by Docker and a directory is created in `/var/lib/docker/volumes` on the container instance that contains the volume data. To use Docker volumes, specify a `dockerVolumeConfiguration` in your task definition. For more information, see [Volumes](https://docs.docker.com/engine/storage/volumes/) in the Docker documentation. Some common use cases for Docker volumes are the following: + To provide persistent data volumes for use with containers + To share a defined data volume at different locations on different containers on the same container instance + To define an empty, nonpersistent data volume and mount it on multiple containers within the same task + To provide a data volume to your task that's managed by a third-party driver ## Considerations for using Docker volumes Consider the following when using Docker volumes: + Docker volumes are only supported when using the EC2 launch type or external instances. + Windows containers only support the use of the `local` driver. + If a third-party driver is used, make sure it's installed and active on the container instance before the container agent is started. If the third-party driver isn't active before the agent is started, you can restart the container agent using one of the following commands: + For the Amazon ECS-optimized Amazon Linux 2 AMI: ``` sudo systemctl restart ecs ``` + For the Amazon ECS-optimized Amazon Linux AMI: ``` sudo stop ecs && sudo start ecs ``` For information about how to specify a Docker volume in a task definition, see [Specify a Docker volume in an Amazon ECS task definition](specify-volume-config.md). # Specify a Docker volume in an Amazon ECS task definition Specify a Docker volume in a task definition Before your containers can use data volumes, you must specify the volume and mount point configurations in your task definition. This section describes the volume configuration for a container. For tasks that use a Docker volume, specify a `dockerVolumeConfiguration`. For tasks that use a bind mount host volume, specify a `host` and optional `sourcePath`. The following task definition JSON shows the syntax for the `volumes` and `mountPoints` objects for a container. ``` { "containerDefinitions": [ { "mountPoints": [ { "sourceVolume": "string", "containerPath": "/path/to/mount_volume", "readOnly": boolean } ] } ], "volumes": [ { "name": "string", "dockerVolumeConfiguration": { "scope": "string", "autoprovision": boolean, "driver": "string", "driverOpts": { "key": "value" }, "labels": { "key": "value" } } } ] } ``` `name` Type: String Required: No The name of the volume. Up to 255 letters (uppercase and lowercase), numbers, hyphens (`-`), and underscores (`_`) are allowed. This name is referenced in the `sourceVolume` parameter of the container definition `mountPoints` object. `dockerVolumeConfiguration` Type: [DockerVolumeConfiguration](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_DockerVolumeConfiguration.html) Object Required: No This parameter is specified when using Docker volumes. Docker volumes are supported only when running tasks on EC2 instances. Windows containers support only the use of the `local` driver. To use bind mounts, specify a `host` instead. `scope` Type: String Valid Values: `task` \$1 `shared` Required: No The scope for the Docker volume, which determines its lifecycle. Docker volumes that are scoped to a `task` are automatically provisioned when the task starts and destroyed when the task stops. Docker volumes that are scoped as `shared` persist after the task stops. `autoprovision` Type: Boolean Default value: `false` Required: No If this value is `true`, the Docker volume is created if it doesn't already exist. This field is used only if the `scope` is `shared`. If the `scope` is `task`, then this parameter must be omitted. `driver` Type: String Required: No The Docker volume driver to use. The driver value must match the driver name provided by Docker because this name is used for task placement. If the driver was installed by using the Docker plugin CLI, use `docker plugin ls` to retrieve the driver name from your container instance. If the driver was installed by using another method, use Docker plugin discovery to retrieve the driver name. `driverOpts` Type: String Required: No A map of Docker driver-specific options to pass through. This parameter maps to `DriverOpts` in the Create a volume section of Docker. `labels` Type: String Required: No Custom metadata to add to your Docker volume. `mountPoints` Type: Object array Required: No The mount points for the data volumes in your container. This parameter maps to `Volumes` in the create-container Docker API and the `--volume` option to docker run. Windows containers can mount whole directories on the same drive as `$env:ProgramData`. Windows containers cannot mount directories on a different drive, and mount points cannot be used across drives. You must specify mount points to attach an Amazon EBS volume directly to an Amazon ECS task. `sourceVolume` Type: String Required: Yes, when `mountPoints` are used The name of the volume to mount. `containerPath` Type: String Required: Yes, when `mountPoints` are used The path in the container where the volume will be mounted. `readOnly` Type: Boolean Required: No If this value is `true`, the container has read-only access to the volume. If this value is `false`, then the container can write to the volume. The default value is `false`. For tasks that run on EC2 instances running the Windows operating system, leave the value as the default of `false`. # Docker volume examples for Amazon ECS Docker volume examples The following examples show how to provide ephemeral storage for a container and how to provide a shared volume for multiple containers, and how to provide NFS persistent storage for a container. **To provide ephemeral storage for a container using a Docker volume** In this example, a container uses an empty data volume that is disposed of after the task is finished. One example use case is that you might have a container that needs to access some scratch file storage location during a task. This task can be achieved using a Docker volume. 1. In the task definition `volumes` section, define a data volume with `name` and `DockerVolumeConfiguration` values. In this example, we specify the scope as `task` so the volume is deleted after the task stops and use the built-in `local` driver. ``` "volumes": [ { "name": "scratch", "dockerVolumeConfiguration" : { "scope": "task", "driver": "local", "labels": { "scratch": "space" } } } ] ``` 1. In the `containerDefinitions` section, define a container with `mountPoints` values that reference the name of the defined volume and the `containerPath` value to mount the volume at on the container. ``` "containerDefinitions": [ { "name": "container-1", "mountPoints": [ { "sourceVolume": "scratch", "containerPath": "/var/scratch" } ] } ] ``` **To provide persistent storage for multiple containers using a Docker volume** In this example, you want a shared volume for multiple containers to use and you want it to persist after any single task that use it stopped. The built-in `local` driver is being used. This is so the volume is still tied to the lifecycle of the container instance. 1. In the task definition `volumes` section, define a data volume with `name` and `DockerVolumeConfiguration` values. In this example, specify a `shared` scope so the volume persists, set autoprovision to `true`. This is so that the volume is created for use. Then, also use the built-in `local` driver. ``` "volumes": [ { "name": "database", "dockerVolumeConfiguration" : { "scope": "shared", "autoprovision": true, "driver": "local", "labels": { "database": "database_name" } } } ] ``` 1. In the `containerDefinitions` section, define a container with `mountPoints` values that reference the name of the defined volume and the `containerPath` value to mount the volume at on the container. ``` "containerDefinitions": [ { "name": "container-1", "mountPoints": [ { "sourceVolume": "database", "containerPath": "/var/database" } ] }, { "name": "container-2", "mountPoints": [ { "sourceVolume": "database", "containerPath": "/var/database" } ] } ] ``` **To provide NFS persistent storage for a container using a Docker volume** In this example, a container uses an NFS data volume that is automatically mounted when the task starts and unmounted when the task stops. This uses the Docker built-in `local` driver. One example use case is that you might have a local NFS storage and need to access it from an ECS Anywhere task. This can be achieved using a Docker volume with NFS driver option. 1. In the task definition `volumes` section, define a data volume with `name` and `DockerVolumeConfiguration` values. In this example, specify a `task` scope so the volume is unmounted after the task stops. Use the `local` driver and configure the `driverOpts` with the `type`, `device`, and `o` options accordingly. Replace `NFS_SERVER` with the NFS server endpoint. ``` "volumes": [ { "name": "NFS", "dockerVolumeConfiguration" : { "scope": "task", "driver": "local", "driverOpts": { "type": "nfs", "device": "$NFS_SERVER:/mnt/nfs", "o": "addr=$NFS_SERVER" } } } ] ``` 1. In the `containerDefinitions` section, define a container with `mountPoints` values that reference the name of the defined volume and the `containerPath` value to mount the volume on the container. ``` "containerDefinitions": [ { "name": "container-1", "mountPoints": [ { "sourceVolume": "NFS", "containerPath": "/var/nfsmount" } ] } ] ``` # Use bind mounts with Amazon ECS Bind mounts With bind mounts, a file or directory on a host, such as an Amazon EC2 instance, is mounted into a container. Bind mounts are supported for tasks that are hosted on both Fargate and Amazon EC2 instances. Bind mounts are tied to the lifecycle of the container that uses them. After all of the containers that use a bind mount are stopped, such as when a task is stopped, the data is removed. For tasks that are hosted on Amazon EC2 instances, the data can be tied to the lifecycle of the host Amazon EC2 instance by specifying a `host` and optional `sourcePath` value in your task definition. For more information, see [Bind mounts](https://docs.docker.com/engine/storage/bind-mounts/) in the Docker documentation. The following are common use cases for bind mounts. + To provide an empty data volume to mount in one or more containers. + To mount a host data volume in one or more containers. + To share a data volume from a source container with other containers in the same task. + To expose a path and its contents from a Dockerfile to one or more containers. ## Considerations when using bind mounts When using bind mounts, consider the following. + By default, tasks that are hosted on AWS Fargate using platform version `1.4.0` or later (Linux) or `1.0.0` or later (Windows) receive a minimum of 20 GiB of ephemeral storage for bind mounts. You can increase the total amount of ephemeral storage up to a maximum of 200 GiB by specifying the `ephemeralStorage` parameter in your task definition. + To expose files from a Dockerfile to a data volume when a task is run, the Amazon ECS data plane looks for a `VOLUME` directive. If the absolute path that's specified in the `VOLUME` directive is the same as the `containerPath` that's specified in the task definition, the data in the `VOLUME` directive path is copied to the data volume. In the following Dockerfile example, a file that's named `examplefile` in the `/var/log/exported` directory is written to the host and then mounted inside the container. ``` FROM public.ecr.aws/amazonlinux/amazonlinux:latest RUN mkdir -p /var/log/exported RUN touch /var/log/exported/examplefile VOLUME ["/var/log/exported"] ``` By default, the volume permissions are set to `0755` and the owner as `root`. You can customize these permissions in the Dockerfile. The following example defines the owner of the directory as `node`. ``` FROM public.ecr.aws/amazonlinux/amazonlinux:latest RUN yum install -y shadow-utils && yum clean all RUN useradd node RUN mkdir -p /var/log/exported && chown node:node /var/log/exported RUN touch /var/log/exported/examplefile USER node VOLUME ["/var/log/exported"] ``` + For tasks that are hosted on Amazon EC2 instances, when a `host` and `sourcePath` value aren't specified, the Docker daemon manages the bind mount for you. When no containers reference this bind mount, the Amazon ECS container agent task cleanup service eventually deletes it. By default, this happens three hours after the container exits. However, you can configure this duration with the `ECS_ENGINE_TASK_CLEANUP_WAIT_DURATION` agent variable. For more information, see [Amazon ECS container agent configuration](ecs-agent-config.md). If you need this data to persist beyond the lifecycle of the container, specify a `sourcePath` value for the bind mount. + For tasks that are hosted on Amazon ECS Managed Instances, portions of the root filesystem are read-only. Read/write bind mounts must use writable directories such as `/var` for persistent data or `/tmp` for temporary data. Attempting to create read/write bind mounts to other directories results in the task failing to launch with an error similar to the following: ``` error creating empty volume: error while creating volume path '/path': mkdir /path: read-only file system ``` Read-only bind mounts (configured with `"readOnly": true` in the `mountPoints` parameter) can point to any accessible directory on the host. To view a full list of writable paths, you can run a task on a Amazon ECS Managed Instance and use to inspect the instance's mount table. Create a task definition with the following settings to access the host filesystem: ``` { "pidMode": "host", "containerDefinitions": [{ "privileged": true, ... }] } ``` Then run the following commands from within the container: ``` # List writable mounts cat /proc/1/root/proc/1/mounts | awk '$4 ~ /^rw,/ || $4 == "rw" {print $2}' | sort # List read-only mounts cat /proc/1/root/proc/1/mounts | awk '$4 ~ /^ro,/ || $4 == "ro" {print $2}' | sort ``` **Important** The `privileged` setting grants the container extended capabilities on the host, equivalent to root access. In this example, it is used to inspect the host's mount table for diagnostic purposes. For more information, see [Avoid running containers as privileged (Amazon EC2)](security-tasks-containers.md#security-tasks-containers-recommendations-avoid-privileged-containers). For more information about running commands interactively in containers, see [Monitor Amazon ECS containers with ECS Exec](ecs-exec.md). # Specify a bind mount in an Amazon ECS task definition Specify a bind mount in a task definition For Amazon ECS tasks that are hosted on either Fargate or Amazon EC2 instances, the following task definition JSON snippet shows the syntax for the `volumes`, `mountPoints`, and `ephemeralStorage` objects for a task definition. ``` { "family": "", ... "containerDefinitions" : [ { "mountPoints" : [ { "containerPath" : "/path/to/mount_volume", "sourceVolume" : "string" } ], "name" : "string" } ], ... "volumes" : [ { "name" : "string" } ], "ephemeralStorage": { "sizeInGiB": integer } } ``` For Amazon ECS tasks that are hosted on Amazon EC2 instances, you can use the optional `host` parameter and a `sourcePath` when specifying the task volume details. When it's specified, it ties the bind mount to the lifecycle of the task rather than the container. ``` "volumes" : [ { "host" : { "sourcePath" : "string" }, "name" : "string" } ] ``` The following describes each task definition parameter in more detail. `name` Type: String Required: No The name of the volume. Up to 255 letters (uppercase and lowercase), numbers, hyphens (`-`), and underscores (`_`) are allowed. This name is referenced in the `sourceVolume` parameter of the container definition `mountPoints` object. `host` Required: No The `host` parameter is used to tie the lifecycle of the bind mount to the host Amazon EC2 instance, rather than the task, and where it is stored. If the `host` parameter is empty, then the Docker daemon assigns a host path for your data volume, but the data is not guaranteed to persist after the containers associated with it stop running. Windows containers can mount whole directories on the same drive as `$env:ProgramData`. The `sourcePath` parameter is supported only when using tasks that are hosted on Amazon EC2 instances or Amazon ECS Managed Instances. `sourcePath` Type: String Required: No When the `host` parameter is used, specify a `sourcePath` to declare the path on the host Amazon EC2 instance that is presented to the container. If this parameter is empty, then the Docker daemon assigns a host path for you. If the `host` parameter contains a `sourcePath` file location, then the data volume persists at the specified location on the host Amazon EC2 instance until you delete it manually. If the `sourcePath` value does not exist on the host Amazon EC2 instance, the Docker daemon creates it. If the location does exist, the contents of the source path folder are exported. `mountPoints` Type: Object array Required: No The mount points for the data volumes in your container. This parameter maps to `Volumes` in the create-container Docker API and the `--volume` option to docker run. Windows containers can mount whole directories on the same drive as `$env:ProgramData`. Windows containers cannot mount directories on a different drive, and mount points cannot be used across drives. You must specify mount points to attach an Amazon EBS volume directly to an Amazon ECS task. `sourceVolume` Type: String Required: Yes, when `mountPoints` are used The name of the volume to mount. `containerPath` Type: String Required: Yes, when `mountPoints` are used The path in the container where the volume will be mounted. `readOnly` Type: Boolean Required: No If this value is `true`, the container has read-only access to the volume. If this value is `false`, then the container can write to the volume. The default value is `false`. For tasks that run on EC2 instances running the Windows operating system, leave the value as the default of `false`. `ephemeralStorage` Type: Object Required: No The amount of ephemeral storage to allocate for the task. This parameter is used to expand the total amount of ephemeral storage available, beyond the default amount, for tasks hosted on AWS Fargate using platform version `1.4.0` or later (Linux) or `1.0.0` or later (Windows). You can use the Copilot CLI, CloudFormation, the AWS SDK or the CLI to specify ephemeral storage for a bind mount. # Bind mount examples for Amazon ECS The following examples cover the common use cases for using a bind mount for your containers. **To allocate an increased amount of ephemeral storage space for a Fargate task** For Amazon ECS tasks that are hosted on Fargate using platform version `1.4.0` or later (Linux) or `1.0.0` (Windows), you can allocate more than the default amount of ephemeral storage for the containers in your task to use. This example can be incorporated into the other examples to allocate more ephemeral storage for your Fargate tasks. + In the task definition, define an `ephemeralStorage` object. The `sizeInGiB` must be an integer between the values of `21` and `200` and is expressed in GiB. ``` "ephemeralStorage": { "sizeInGiB": integer } ``` **To provide an empty data volume for one or more containers** In some cases, you want to provide the containers in a task some scratch space. For example, you might have two database containers that need to access the same scratch file storage location during a task. This can be achieved using a bind mount. 1. In the task definition `volumes` section, define a bind mount with the name `database_scratch`. ``` "volumes": [ { "name": "database_scratch" } ] ``` 1. In the `containerDefinitions` section, create the database container definitions. This is so that they mount the volume. ``` "containerDefinitions": [ { "name": "database1", "image": "my-repo/database", "cpu": 100, "memory": 100, "essential": true, "mountPoints": [ { "sourceVolume": "database_scratch", "containerPath": "/var/scratch" } ] }, { "name": "database2", "image": "my-repo/database", "cpu": 100, "memory": 100, "essential": true, "mountPoints": [ { "sourceVolume": "database_scratch", "containerPath": "/var/scratch" } ] } ] ``` **To expose a path and its contents in a Dockerfile to a container** In this example, you have a Dockerfile that writes data that you want to mount inside a container. This example works for tasks that are hosted on Fargate or Amazon EC2 instances. 1. Create a Dockerfile. The following example uses the public Amazon Linux 2 container image and creates a file that's named `examplefile` in the `/var/log/exported` directory that we want to mount inside the container. The `VOLUME` directive should specify an absolute path. ``` FROM public.ecr.aws/amazonlinux/amazonlinux:latest RUN mkdir -p /var/log/exported RUN touch /var/log/exported/examplefile VOLUME ["/var/log/exported"] ``` By default, the volume permissions are set to `0755` and the owner as `root`. These permissions can be changed in the Dockerfile. In the following example, the owner of the `/var/log/exported` directory is set to `node`. ``` FROM public.ecr.aws/amazonlinux/amazonlinux:latest RUN yum install -y shadow-utils && yum clean all RUN useradd node RUN mkdir -p /var/log/exported && chown node:node /var/log/exported USER node RUN touch /var/log/exported/examplefile VOLUME ["/var/log/exported"] ``` 1. In the task definition `volumes` section, define a volume with the name `application_logs`. ``` "volumes": [ { "name": "application_logs" } ] ``` 1. In the `containerDefinitions` section, create the application container definitions. This is so they mount the storage. The `containerPath` value must match the absolute path that's specified in the `VOLUME` directive from the Dockerfile. ``` "containerDefinitions": [ { "name": "application1", "image": "my-repo/application", "cpu": 100, "memory": 100, "essential": true, "mountPoints": [ { "sourceVolume": "application_logs", "containerPath": "/var/log/exported" } ] }, { "name": "application2", "image": "my-repo/application", "cpu": 100, "memory": 100, "essential": true, "mountPoints": [ { "sourceVolume": "application_logs", "containerPath": "/var/log/exported" } ] } ] ``` **To provide an empty data volume for a container that's tied to the lifecycle of the host Amazon EC2 instance** For tasks that are hosted on Amazon EC2 instances, you can use bind mounts and have the data tied to the lifecycle of the host Amazon EC2 instance. You can do this by using the `host` parameter and specifying a `sourcePath` value. Any files that exist at the `sourcePath` are presented to the containers at the `containerPath` value. Any files that are written to the `containerPath` value are written to the `sourcePath` value on the host Amazon EC2 instance. **Important** Amazon ECS doesn't sync your storage across Amazon EC2 instances. Tasks that use persistent storage can be placed on any Amazon EC2 instance in your cluster that has available capacity. If your tasks require persistent storage after stopping and restarting, always specify the same Amazon EC2 instance at task launch time with the AWS CLI [start-task](https://docs.aws.amazon.com/cli/latest/reference/ecs/start-task.html) command. You can also use Amazon EFS volumes for persistent storage. For more information, see [Use Amazon EFS volumes with Amazon ECS](efs-volumes.md). 1. In the task definition `volumes` section, define a bind mount with `name` and `sourcePath` values. In the following example, the host Amazon EC2 instance contains data at `/ecs/webdata` that you want to mount inside the container. ``` "volumes": [ { "name": "webdata", "host": { "sourcePath": "/ecs/webdata" } } ] ``` 1. In the `containerDefinitions` section, define a container with a `mountPoints` value that references the name of the bind mount and the `containerPath` value to mount the bind mount at on the container. ``` "containerDefinitions": [ { "name": "web", "image": "public.ecr.aws/docker/library/nginx:latest", "cpu": 99, "memory": 100, "portMappings": [ { "containerPort": 80, "hostPort": 80 } ], "essential": true, "mountPoints": [ { "sourceVolume": "webdata", "containerPath": "/usr/share/nginx/html" } ] } ] ``` **To mount a defined volume on multiple containers at different locations** You can define a data volume in a task definition and mount that volume at different locations on different containers. For example, your host container has a website data folder at `/data/webroot`. You might want to mount that data volume as read-only on two different web servers that have different document roots. 1. In the task definition `volumes` section, define a data volume with the name `webroot` and the source path `/data/webroot`. ``` "volumes": [ { "name": "webroot", "host": { "sourcePath": "/data/webroot" } } ] ``` 1. In the `containerDefinitions` section, define a container for each web server with `mountPoints` values that associate the `webroot` volume with the `containerPath` value pointing to the document root for that container. ``` "containerDefinitions": [ { "name": "web-server-1", "image": "my-repo/ubuntu-apache", "cpu": 100, "memory": 100, "portMappings": [ { "containerPort": 80, "hostPort": 80 } ], "essential": true, "mountPoints": [ { "sourceVolume": "webroot", "containerPath": "/var/www/html", "readOnly": true } ] }, { "name": "web-server-2", "image": "my-repo/sles11-apache", "cpu": 100, "memory": 100, "portMappings": [ { "containerPort": 8080, "hostPort": 8080 } ], "essential": true, "mountPoints": [ { "sourceVolume": "webroot", "containerPath": "/srv/www/htdocs", "readOnly": true } ] } ] ``` **To mount volumes from another container using `volumesFrom`** For tasks hosted on Amazon EC2 instances, you can define one or more volumes on a container, and then use the `volumesFrom` parameter in a different container definition within the same task to mount all of the volumes from the `sourceContainer` at their originally defined mount points. The `volumesFrom` parameter applies to volumes defined in the task definition, and those that are built into the image with a Dockerfile. 1. (Optional) To share a volume that is built into an image, use the `VOLUME` instruction in the Dockerfile. The following example Dockerfile uses an `httpd` image, and then adds a volume and mounts it at `dockerfile_volume` in the Apache document root. It is the folder used by the `httpd` web server. ``` FROM httpd VOLUME ["/usr/local/apache2/htdocs/dockerfile_volume"] ``` You can build an image with this Dockerfile and push it to a repository, such as Docker Hub, and use it in your task definition. The example `my-repo/httpd_dockerfile_volume` image that's used in the following steps was built with the preceding Dockerfile. 1. Create a task definition that defines your other volumes and mount points for the containers. In this example `volumes` section, you create an empty volume called `empty`, which the Docker daemon manages. There's also a host volume defined that's called `host_etc`. It exports the `/etc` folder on the host container instance. ``` { "family": "test-volumes-from", "volumes": [ { "name": "empty", "host": {} }, { "name": "host_etc", "host": { "sourcePath": "/etc" } } ], ``` In the container definitions section, create a container that mounts the volumes defined earlier. In this example, the `web` container mounts the `empty` and `host_etc` volumes. This is the container that uses the image built with a volume in the Dockerfile. ``` "containerDefinitions": [ { "name": "web", "image": "my-repo/httpd_dockerfile_volume", "cpu": 100, "memory": 500, "portMappings": [ { "containerPort": 80, "hostPort": 80 } ], "mountPoints": [ { "sourceVolume": "empty", "containerPath": "/usr/local/apache2/htdocs/empty_volume" }, { "sourceVolume": "host_etc", "containerPath": "/usr/local/apache2/htdocs/host_etc" } ], "essential": true }, ``` Create another container that uses `volumesFrom` to mount all of the volumes that are associated with the `web` container. All of the volumes on the `web` container are likewise mounted on the `busybox` container. This includes the volume that's specified in the Dockerfile that was used to build the `my-repo/httpd_dockerfile_volume` image. ``` { "name": "busybox", "image": "busybox", "volumesFrom": [ { "sourceContainer": "web" } ], "cpu": 100, "memory": 500, "entryPoint": [ "sh", "-c" ], "command": [ "echo $(date) > /usr/local/apache2/htdocs/empty_volume/date && echo $(date) > /usr/local/apache2/htdocs/host_etc/date && echo $(date) > /usr/local/apache2/htdocs/dockerfile_volume/date" ], "essential": false } ] } ``` When this task is run, the two containers mount the volumes, and the `command` in the `busybox` container writes the date and time to a file. This file is called `date` in each of the volume folders. The folders are then visible at the website displayed by the `web` container. **Note** Because the `busybox` container runs a quick command and then exits, it must be set as `"essential": false` in the container definition. Otherwise, it stops the entire task when it exits.