FSx for Windows File Server volumes
FSx for Windows File Server provides fully managed Microsoft 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?.
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 cannot use FSx for Windows File Server volumes in a Windows containers on Fargate configuration.
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 ECS container that runs on an ECS Windows instance. You can share FSx for Windows File Server file system volumes between multiple ECS containers within a single 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, 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 domain join the Active Directory 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.
The following sections describe how to get started using FSx for Windows File Server with Amazon ECS.
For a related tutorial, see Tutorial: Using FSx for Windows File Server file systems with Amazon ECS.
FSx for Windows File Server volume considerations
Consider the following when using FSx for Windows File Server volumes:
-
FSx for Windows File Server with Amazon ECS only supports Windows Amazon EC2 instances. Linux Amazon EC2 instances aren't supported.
-
Amazon ECS only supports FSx for Windows File Server. Amazon ECS doesn't support FSx for Lustre.
-
FSx for Windows File Server with Amazon ECS doesn't support AWS Fargate.
-
FSx for Windows File Server with Amazon ECS with
awsvpc
network mode requires version1.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. -
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 AD domain with correctly configured AD security groups can access the FSx for Windows File Server file-share. If the security groups are misconfigured, 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 in the Amazon FSx Windows User Guide.
Specifying an FSx for Windows File Server file system in your 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 '<html> <head> <title>Amazon ECS Sample App</title> <style>body {margin-top: 40px; background-color: #333;} </style> </head><body> <div style=color:white;text-align:center> <h1>Amazon ECS Sample App</h1> <h2>It Works!</h2> <p>You are using Amazon FSx for Windows File Server file system for persistent container storage.</p>' -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": 8080, "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-vol", "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 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 secret.
-
Amazon Resource Name (ARN) of an Systems Manager parameter.
-
domain
-
Type: String
Required: Yes
A fully qualified domain name that's hosted by an AWS Directory Service Managed Microsoft AD (Active Directory) or self-hosted EC2 AD.
Credential storage methods
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 in the Secrets Manager User Guide and Systems Manager Parameter Store from the Systems Manager User
Guide.