Upgrading to v7.0

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_provider
ordered_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

None

Renamed variables

Before	After
`autoscaling_capacity_providers`	`capacity_providers`

Added variables

cluster_capacity_providers — explicit list of capacity providers to associate with the cluster
disable_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
        }
      }
    }
  }
}

Get Started

Architecture

Guides

Upgrade Guides

What changed

Breaking changes

Variable and output changes

Removed variables

Renamed variables

Added variables

Renamed outputs

Migration guide

State changes

Complete before/after example

Root module

Cluster sub-module

​What changed

​Breaking changes

​Variable and output changes

​Removed variables

​Renamed variables

​Added variables

​Renamed outputs

​Migration guide

​State changes

​Complete before/after example

​Root module

​Cluster sub-module

What changed

Breaking changes

Variable and output changes

Removed variables

Renamed variables

Added variables

Renamed outputs

Migration guide

State changes

Complete before/after example

Root module

Cluster sub-module