ECS Fargate — Terraform Example

Progress checklist

• Prerequisites confirmed (Terraform >= 1.5, AWS CLI v2.34.26+, AWS credentials)
• Existing ECS cluster name confirmed
• terraform.tfvars created with vpc_id, subnet_ids, and ecs_cluster_name
• terraform apply completed successfully
• ECS task is running
• CloudWatch logs confirm file system mount and listing

What this example does

This example provisions:

• An S3 bucket (versioning + SSE-S3 enabled)
• An S3 Files file system and mount targets in each provided subnet
• IAM roles (file system role + ECS task execution role)
• Security groups (compute → mount target on NFS port 2049)
• A CloudWatch log group for the ECS task
• An ECS task definition with s3filesVolumeConfiguration (registered via local-exec)
• An ECS service running one Fargate task on the existing cluster

Caution

S3 Files ECS volumes are supported on Fargate and Managed Instances only. The EC2 launch type is not supported.

Note

The Terraform AWS provider’s aws_ecs_task_definition resource does not yet support s3filesVolumeConfiguration natively. The example uses a terraform_data + local-exec block to call aws ecs register-task-definition directly, which is why AWS CLI v2.34.26+ must be installed on the machine running terraform apply.

Note

ECS service wiring (still non-native): the example runs the service on the existing Fargate cluster you pass as ecs_cluster_name—it does not create a cluster. The task definition revision the service uses exists only after that local-exec registration finishes, so the module resolves the task definition ARN from the AWS API (or from provisioner output) rather than from a normal aws_ecs_task_definition resource with an inline s3filesVolumeConfiguration block.

1. Confirm prerequisites.

   Requirement	Minimum version
   Terraform	1.5
   AWS provider	6.40
   AWS CLI	2.34.26 (called via local-exec during terraform apply)

   Confirm the CLI version:

   aws --version

   You also need an existing ECS cluster to deploy into. Confirm it exists:

   aws ecs describe-clusters \
     --clusters <your-cluster-name> \
     --region ap-southeast-6 \
     --query 'clusters[0].status' \
     --output text

   Expected output: ACTIVE

2. Clone the example.

   git clone https://github.com/jajera/terraform-aws-s3-files.git
   cd terraform-aws-s3-files/examples/ecs

   • Directoryexamples/ecs/

     • main.tf
     • terraform.tfvars.example
     • terraform.tfvars (you create this)

3. Create terraform.tfvars.

   cp terraform.tfvars.example terraform.tfvars

   Edit terraform.tfvars:

   vpc_id           = "vpc-0123456789abcdef0"
   subnet_ids       = ["subnet-aaaaaaaaaaaaaaaaa", "subnet-bbbbbbbbbbbbbbbbb"]
   ecs_cluster_name = "my-cluster"
   
   # Optional overrides (defaults shown):
   # aws_region         = "ap-southeast-6"
   # container_image    = "public.ecr.aws/amazonlinux/amazonlinux:2023"
   # log_retention_days = 7
   # bucket_name        = null   # auto-generated: s3files-demo-<random>
   # bucket_force_destroy = true

   Variable	Default	Required	Description
   vpc_id	—	yes	VPC for mount targets and ECS tasks
   subnet_ids	—	yes	Subnets for mount targets and Fargate task ENIs
   ecs_cluster_name	—	yes	Name of an existing ECS cluster
   aws_region	ap-southeast-6	no	AWS region
   container_image	public.ecr.aws/amazonlinux/amazonlinux:2023	no	Container image for the demo task
   log_retention_days	7	no	CloudWatch log retention period in days
   bucket_name	auto-generated	no	Leave null to use s3files-demo-<random>
   bucket_force_destroy	true	no	Allow destroy even when bucket contains objects

4. Initialise and apply.

   terraform init
   terraform plan
   terraform apply

   Note

   During terraform apply, the local-exec provisioner calls aws ecs register-task-definition to register the task definition with s3filesVolumeConfiguration. This requires AWS CLI v2.34.26+ on the machine running Terraform.

   When apply finishes, note the outputs:

   terraform output

   Key outputs:

   Output	Description
   ecs_service_name	ECS service name
   task_definition_family	ECS task definition family name
   log_group	CloudWatch log group (/ecs/<prefix>-s3files)
   file_system_id	S3 Files file system ID
   bucket_name	Backing S3 bucket name

5. Confirm the ECS service is running.

   aws ecs describe-services \
     --cluster "$(terraform output -raw ecs_service_name | cut -d- -f1-3)" \
     --services "$(terraform output -raw ecs_service_name)" \
     --region ap-southeast-6 \
     --query 'services[0].{status:status,running:runningCount,desired:desiredCount}'

   Wait until runningCount equals desiredCount (1). This can take 2–3 minutes while the mount target becomes available and the container starts.

   Note

   If the task stops with STOPPED reason mentioning the file system, confirm that the mount targets are available:

   aws s3files list-mount-targets \
     --file-system-id "$(terraform output -raw file_system_id)" \
     --region ap-southeast-6

6. Verify via CloudWatch Logs.

   aws logs tail \
     "$(terraform output -raw log_group)" \
     --follow \
     --region ap-southeast-6

   Expected output includes:

   ====S3Files-df====
   Filesystem      Size  Used Avail Use% Mounted on
   ...              ...   ...   ...  ...  /mnt/s3files
   ====listing====
   total 0
   ====done====

   Press Ctrl+C to stop tailing.

7. Tear down.

   terraform destroy

   Caution

   terraform destroy does not de-register ECS task definitions (AWS does not support deletion via API). The task definition family remains in your account in INACTIVE state after destroy.