FSx for Windows File Server volumes - Amazon Elastic Container Service
FSx for Windows File Server volume considerationsSpecifying an FSx for Windows File Server file system in your task definition

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.

  • 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 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.

  • 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": 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 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:

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.