Tutorial: Using FSx for Windows File Server file systems with
Amazon ECS

FSx for Windows File Server provides fully managed Microsoft Windows file servers, that are backed by a
fully native Windows file system. When using FSx for Windows File Server together with Amazon 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? in the FSx for Windows File Server User
Guide.

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 running on an ECS
Windows instance. You can share FSx for Windows File Server file system volumes among multiple ECS
containers within a single ECS task.

Note

FSx for Windows File Server might not be available in all Regions. For more information about which
Regions support FSx for Windows File Server, see Amazon FSx Endpoints and Quotas in the
AWS General Reference.

In this tutorial, you launch an 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
AWS Directory Service AWS Managed Microsoft Active Directory. Then, you create an Amazon FSx for Windows
File Server file system and an ECS cluster with an ECS instance and an ECS 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 administratice user. See Set up to use Amazon ECS.

• (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 Windows instances in the User
  Guide for Windows Instances.

• 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. AWS 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
  ECS instance must be located within your VPC. For more information regarding
  VPCs and Active Directories, see Amazon VPC console wizard
  configurations and AWS Managed Microsoft AD Prerequisites.

• 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 to
   check whether you have an ecsInstanceRole and to see how you can create one if
   you don’t have one.

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

   To attach AWS managed policies.

   1. Open the IAM
      console.

   2. In the navigation pane, choose Roles.

   3. Choose an AWS managed
role.

   4. Choose Permissions, Attach policies..

   5. To narrow the available policies to attach, use
      Filter.

   6. Select the appropriate policy and choose Attach
      policy.

3. See Amazon ECS task execution IAM role 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 Create Your AWS Managed AD Directory in the AWS
   Directory Service Administration Guide. Use the VPC you
   have designated for this tutorial. On Step 3 of Create Your AWS
   Managed AD Directory, save the user name and password for use in
   a following step. Also, note the fully qualified domain name for future steps.
   You can go on to complete the following step while the Active Directory is being
   created.

2. Create an AWS Secrets Manager secret to use in the following steps. For more
   information, see Getting Started
   with AWS Secrets Manager in the AWS Secrets Manager
   User Guide.

   1. Open the Secrets Manager
      console.

   2. Click Store a new secret.

   3. Select Other type of secrets.

   4. For Secret key/value, in the first row, create a
      key username with value
      admin. Click on + Add
      row.

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

   6. Click on the Next button.

   7. Provide a secret name and description. Click
      Next.

   8. Click Next. Click
      Store.

   9. From the list of Secrets page, click on the
      secret you have just created.

   10. Save the ARN of the new secret for use in the following steps.

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

Custom TCP

TCP

8080

0.0.0.0/0

RDP

TCP

3389

your EC2 instance public 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 and select
   Security Groups from the left-hand menu.

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

3. 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 from the Amazon EC2 User Guide
   for Windows Instances.

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.

2. On the dashboard, choose Create file system to start the
   file system creation wizard.

3. On the Select file system type page, choose
   FSx for Windows File Server, and then choose
   Next. The Create file system page
   appears.

4. 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 (+). minus sign
   (-), equal sign (=), period (.), underscore (_), colon (:), and forward slash
   (/).

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

6. For Storage type, choose
   HDD.

7. For Storage capacity, enter the minimum storage capacity.

8. Keep Throughput capacity at its default
   setting.

9. In the Network & security section, choose the same
   Amazon VPC that you chose for your AWS Directory Service directory.

10. For VPC Security Groups, choose the security group that
    you verified in Step 3: Verify and update your security
    group.

11. For Windows authentication, choose AWS
    Managed Microsoft Active Directory, and then choose your AWS Directory Service
    directory from the
    list.

12. For Encryption, keep the default Encryption
    key setting of aws/fsx (default).

13. Keep the default settings for Maintenance
    preferences.

14. Click on the Next button.

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

16. 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 classic Amazon ECS console

1. Open the Amazon ECS console.

2. In the navigation pane, choose Clusters.

3. On the Clusters page, choose Create
   Cluster.

4. Choose EC2 Windows + Networking and choose Next
   step.

5. For Cluster name enter
   windows-fsx-cluster.

6. Click the check-box under the name of the cluster to create an empty
   cluster.

7. Click the Create button on the lower right corner.

8. Click the View Cluster button when the cluster is
   successfully created.

   You are now on a page where you can view the details of your cluster.

Step 6: Create an Amazon ECS instance

Launch an ECS Optimized Windows EC2 instance into the ECS cluster you just created using
the AWS Management Console and the classic Amazon ECS console

1. Go to Amazon
   ECS-optimized AMI in the Amazon ECS Developer Guide
   to find the latest version of the Windows Server 2019 Full AMI in the same
   Region as your VPC.

2. You can get the latest version using one of the following steps.

   Scroll down to the Windows Server 2019 Full AMI table.

   1. Find the latest version in the table for your Region. Click
      View AMI ID link to a page where you’ll find
      the AMI ID of the latest version. Save a copy of the AMI ID for the next
      steps.

   2. Run the given Systems Manager command using the AWS CLI and save a copy
      of the AMI ID that is returned.

3. Open the Amazon EC2 console.

4. Click on the Launch Instance button and select
   Launch Instance.

   You are now on a page that lists available EC2 instances.

5. Select an AMI for your EC2 instance.

   1. Under Quick Start, click on Community
      AMIs.

   2. In the search field, enter the AMI ID that you
      saved from the previous step and press return.

   3. Select the Windows Server 2019 Full AMI that matches the AMI ID that
      you saved in the previous step.

      You are now on a page listing instance types.

6. For Instance type page, choose t2.medium or t2.micro and
   click on Next: Configure Instance Details.

7. Configure instance details.

   1. On the Configure Instance Details page, enter 1
      for Number of Instances.

   2. For Network select your VPC.

   3. For Subnets select a public subnet.

   4. Select Enable for Auto-assign Public
      IP.

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

   6. For IAM role, select your
      ecsInstanceRole from the drop-down menu.

   7. Scroll to the bottom of the page and enter the following into the
      User data text field.

      <powershell>
      Initialize-ECSAgent -Cluster windows-fsx-cluster -EnableTaskIAMRole
      </powershell>

   8. Click Next: Add Storage button.

   9. Click Next: Add Tags button.

   10. Click Next: Configure Security Group
       button.

8. On the Configure Security Group page, select the security
   group that you verified and updated in Step 3: Verify and update your
   security group. If it doesn’t already exist, add an inbound RDP
   TCP rule to allow traffic from your EC2 instance IP address through port 3389 if
   you want to be able to RDP into your instance.

9. Click on Review and Launch button.

10. On the Review Instance Launch page, click the
    Launch button.

11. For Key pair, choose an Amazon EC2 key pair to use with your
    container instances for RDP access. If you don’t specify a key pair, you can’t
    connect to your container instances with RDP. For more information, see Prerequisites for the tutorial.

12. Click on View instance to see the new instance status
    among your list of instances.

13. Open the classic Amazon ECS console and select
    Clusters.

14. Select your fsx-windows-cluster cluster.

15. Select the ECS Instances tab and verify that your ECS
    instance has been registered in the fsx-windows-cluster
    cluster.

Step 7: Register a Windows task
definition

Before you can run Windows containers in your Amazon ECS cluster, you must register a task
definition. The following task definition example displays a simple web page on port
8080 of a container instance. The task launches two containers that have access to the
FSx file system. The first container writes an HTML file to the file system. The second
container downloads the HTML file from the file system and serves the webpage.

Register the sample task definition with the classic Amazon ECS console

1. Open the Amazon ECS console.

2. In the navigation pane, choose Task Definitions.

3. On the Task Definitions page, choose Create new
   Task Definition.

4. On the Select launch type compatibilities page, choose
   EC2 and then Next step.

   Note

   The Fargate launch type isn’t compatible with Windows
   containers.

5. On the Create new Task Definition page, scroll to the
   bottom of the page and choose Configure via JSON.

6. Use the following sample task definition JSON. Replace the values for your task execution
   role and the details about your FSx file system and then choose
   Save.

   {
       "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"
               }
           }
       ]
   }

7. Click on container1 under Container
   Definitions.

8. Scroll to STORAGE AND LOGGING and, for Mount
   points Source volume, select
   fsx-windows-vol from the drop-down menu.

9. For Container path, enter
   C:\fsx-windows-dir.

10. Click on Update button.

11. Repeat the last four steps for container2 under
    Container Definitions.

12. For Task execution role, choose your
    ecsTaskExecutionRole from the drop-down menu.

13. Verify your information and click on Create
    button.

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 classic console.

1. Open the Amazon ECS console.

2. Choose your fsx-windows-cluster cluster.

3. Choose Tasks tab, and then Run new
   task.

4. For Launch Type, select EC2.

5. For Task Definition, choose the
   fsx-windows task definition that you created, and then
   choose Run
   Task.

6. Under the Tasks tab, choose the task that you just ran.
   Your task appears in the list of tasks.

7. When your task status is RUNNING, click on the task
   ID.

8. Expand container2.

9. Scroll down and click on the external IP address that is associated with the
   container. Your browser will open and display the following message.

   Note

   If you don’t see this message, 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 8080.

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.

Remove FSx for Windows File Server file system.

1. Open the Amazon FSx console

2. Click the radio button to the left of the FSx for Windows File Server file system that you
   just created.

3. Click on Actions.

4. Select Delete file system.

Remove AD.

1. Open the AWS Directory Service
   console.

2. Click the radio button to the left of the AD you just created.

3. Click on Actions.

4. Select Delete directory.

Remove ECS cluster.

1. Open the Amazon ECS console.

2. Select Clusters.

3. Select the cluster you just created.

4. Click the Delete Cluster button.

Remove ECS instance.

1. Open the Amazon EC2 console.

2. From the left-hand menu, select Instances.

3. Check the check-box to the left of the EC2 instance you created during this
   exercise.

4. Click the Instance state and then Terminate
   instance.

Remove secret.

1. Open the Secrets Manager
   console.

2. Select the secret you created for this walk through.

3. Click Actions.

4. Select Delete secret.