Documentation Index
Fetch the complete documentation index at: https://mintlify.com/terraform-aws-modules/terraform-aws-ecs/llms.txt
Use this file to discover all available pages before exploring further.
v7.0 adds support for ECS managed instances, introduces explicit capacity provider association via a new cluster_capacity_providers variable, renames autoscaling_capacity_providers to capacity_providers, and changes the type of ordered_placement_strategy from map to list.
What changed
- Capacity providers are no longer inferred from
default_capacity_provider_strategy or autoscaling_capacity_providers — they must be explicitly listed in the new cluster_capacity_providers variable
autoscaling_capacity_providers renamed to capacity_providers; ASG provider configuration is now nested under auto_scaling_group_providerordered_placement_strategy type changed from map(object({...})) to list(object({...}))- Default name postfixes and descriptions added to IAM roles and security groups (opt out with
disable_v7_default_name_description)
- Support for ECS managed instances capacity provider added
Breaking changes
Capacity providers are no longer inferred. If you use FARGATE, FARGATE_SPOT, or any externally created capacity provider, you must now explicitly declare them in the new cluster_capacity_providers variable.
autoscaling_capacity_providers has been renamed to capacity_providers. Each ASG provider definition must also be nested under a new auto_scaling_group_provider block.
Default IAM role and security group name postfixes and descriptions are added in v7.0. This can cause existing resources to be renamed, which Terraform will implement as a destroy-and-recreate. Use disable_v7_default_name_description = true to preserve existing resource names during migration.
Variable and output changes
Removed variables
Renamed variables
| Before | After |
|---|
autoscaling_capacity_providers | capacity_providers |
Added variables
cluster_capacity_providers — explicit list of capacity providers to associate with the clusterdisable_v7_default_name_description — opt out of new default name postfixes and descriptions (will be removed in v8.0)
Renamed outputs
| Before | After |
|---|
autoscaling_capacity_providers | capacity_providers |
Migration guide
Update the module version
Change the version constraint to ~> 7.0.module "ecs" {
source = "terraform-aws-modules/ecs/aws"
version = "~> 7.0"
}
Add cluster_capacity_providers for Fargate and external providers
v7.0 no longer infers which capacity providers to associate with the cluster. You must explicitly list them using the new cluster_capacity_providers variable. Before (v6.x)
After (v7.x)
module "ecs" {
# FARGATE and FARGATE_SPOT were inferred from
# default_capacity_provider_strategy
default_capacity_provider_strategy = {
FARGATE = {
weight = 50
base = 20
}
FARGATE_SPOT = {
weight = 50
}
}
}
module "ecs" {
# Explicitly declare capacity providers
cluster_capacity_providers = ["FARGATE", "FARGATE_SPOT"]
default_capacity_provider_strategy = {
FARGATE = {
weight = 50
base = 20
}
FARGATE_SPOT = {
weight = 50
}
}
}
Capacity providers created by the module itself (via the capacity_providers variable) are automatically associated with the cluster. You only need to list FARGATE, FARGATE_SPOT, or externally created capacity providers in cluster_capacity_providers.
Rename autoscaling_capacity_providers to capacity_providers
Rename the variable and nest each ASG provider’s attributes under a new auto_scaling_group_provider block. Before (v6.x)
After (v7.x)
autoscaling_capacity_providers = {
ASG = {
auto_scaling_group_arn = module.autoscaling.autoscaling_group_arn
managed_draining = "ENABLED"
managed_termination_protection = "ENABLED"
managed_scaling = {
maximum_scaling_step_size = 5
minimum_scaling_step_size = 1
status = "ENABLED"
target_capacity = 60
}
}
}
capacity_providers = {
ASG = {
auto_scaling_group_provider = {
auto_scaling_group_arn = module.autoscaling.autoscaling_group_arn
managed_draining = "ENABLED"
managed_termination_protection = "ENABLED"
managed_scaling = {
maximum_scaling_step_size = 5
minimum_scaling_step_size = 1
status = "ENABLED"
target_capacity = 60
}
}
}
}
No resources will be replaced or destroyed as a result of this rename. Existing ASG capacity providers continue to work as before — this is a variable rename and structural change only.
Preserve existing resource names (optional)
v7.0 introduces default name postfixes (e.g. -service, -task-exec, -tasks, -infra) and default descriptions for IAM roles and security groups created by the module. If you have existing resources and want to avoid renaming them during this upgrade, set disable_v7_default_name_description = true.module "ecs" {
# ...
disable_v7_default_name_description = true
}
disable_v7_default_name_description is a temporary escape hatch that will be removed in v8.0. After upgrading, plan to remove this variable and accept the new naming convention before the next major version.
Update ordered_placement_strategy to a list
If you use ordered_placement_strategy in the service sub-module, change it from a map to a list to preserve ordering. Before (v6.x)
After (v7.x)
ordered_placement_strategy = {
binpack = {
field = "memory"
}
}
ordered_placement_strategy = [
{
type = "binpack"
field = "memory"
}
]
Update output references
Update any references to the renamed output:| Old reference | New reference |
|---|
module.ecs.autoscaling_capacity_providers | module.ecs.capacity_providers |
State changes
No terraform state mv commands are required for this upgrade. The capacity provider rename is a variable-level change and does not affect the underlying resources.
Complete before/after example
Root module
Before (v6.x)
After (v7.x)
module "ecs" {
source = "terraform-aws-modules/ecs/aws"
version = "~> 6.0"
default_capacity_provider_strategy = {
FARGATE = {
weight = 50
base = 20
}
FARGATE_SPOT = {
weight = 50
}
}
autoscaling_capacity_providers = {
ASG = {
auto_scaling_group_arn = module.autoscaling.autoscaling_group_arn
managed_draining = "ENABLED"
managed_termination_protection = "ENABLED"
managed_scaling = {
maximum_scaling_step_size = 5
minimum_scaling_step_size = 1
status = "ENABLED"
target_capacity = 60
}
}
}
}
module "ecs" {
source = "terraform-aws-modules/ecs/aws"
version = "~> 7.0"
cluster_capacity_providers = ["FARGATE", "FARGATE_SPOT"]
default_capacity_provider_strategy = {
FARGATE = {
weight = 50
base = 20
}
FARGATE_SPOT = {
weight = 50
}
}
capacity_providers = {
ASG = {
auto_scaling_group_provider = {
auto_scaling_group_arn = module.autoscaling.autoscaling_group_arn
managed_draining = "ENABLED"
managed_termination_protection = "ENABLED"
managed_scaling = {
maximum_scaling_step_size = 5
minimum_scaling_step_size = 1
status = "ENABLED"
target_capacity = 60
}
}
}
}
}
Cluster sub-module
Before (v6.x)
After (v7.x)
module "ecs_cluster" {
source = "terraform-aws-modules/ecs/aws//modules/cluster"
version = "~> 6.0"
default_capacity_provider_strategy = {
FARGATE = {
weight = 50
base = 20
}
FARGATE_SPOT = {
weight = 50
}
}
autoscaling_capacity_providers = {
ASG = {
auto_scaling_group_arn = module.autoscaling.autoscaling_group_arn
managed_draining = "ENABLED"
managed_termination_protection = "ENABLED"
managed_scaling = {
maximum_scaling_step_size = 5
minimum_scaling_step_size = 1
status = "ENABLED"
target_capacity = 60
}
}
}
}
module "ecs_cluster" {
source = "terraform-aws-modules/ecs/aws//modules/cluster"
version = "~> 7.0"
cluster_capacity_providers = ["FARGATE", "FARGATE_SPOT"]
default_capacity_provider_strategy = {
FARGATE = {
weight = 50
base = 20
}
FARGATE_SPOT = {
weight = 50
}
}
capacity_providers = {
ASG = {
auto_scaling_group_provider = {
auto_scaling_group_arn = module.autoscaling.autoscaling_group_arn
managed_draining = "ENABLED"
managed_termination_protection = "ENABLED"
managed_scaling = {
maximum_scaling_step_size = 5
minimum_scaling_step_size = 1
status = "ENABLED"
target_capacity = 60
}
}
}
}
}
