Upgrading to v4.0

v4.0 upgrades minimum provider and Terraform requirements, consolidates capacity provider configuration into the module, and removes the ecs-instance-profile sub-module.

What changed

Minimum Terraform version raised to v1.0
Minimum AWS provider version raised to v4.6
ecs-instance-profile sub-module removed
container_insights variable replaced with cluster_settings
capacity_providers and default_capacity_provider_strategy replaced with fargate_capacity_providers and autoscaling_capacity_providers
aws_ecs_capacity_provider resources are now managed inside the module

Breaking changes

The ecs-instance-profile sub-module has been removed. You must migrate to the IAM instance profile provided by the terraform-aws-autoscaling module (v6.5.0+). See the examples/complete directory for a reference implementation.

The capacity_providers and default_capacity_provider_strategy variables have been removed and replaced with fargate_capacity_providers and autoscaling_capacity_providers. AutoScaling Group capacity providers are now created and managed directly by this module rather than being referenced externally.

Variable and output changes

Removed variables

default_capacity_provider_strategy — now embedded in fargate_capacity_providers and autoscaling_capacity_providers

Renamed variables

Before	After
`create_ecs`	`create`
`name`	`cluster_name`
`container_insights`	`cluster_settings`
`capacity_providers`	`fargate_capacity_providers` / `autoscaling_capacity_providers`

Added variables

cluster_configuration — dynamic block supporting all current attributes

Removed outputs

ecs_cluster_name

Renamed outputs

Before	After
`ecs_cluster_id`	`cluster_id`
`ecs_cluster_arn`	`cluster_arn`

Added outputs

cluster_capacity_providers
autoscaling_capacity_providers

Migration guide

Update the module version

Change the version constraint in your module source to 4.0.0 (or ~> 4.0).

module "ecs" {
  source  = "terraform-aws-modules/ecs/aws"
  version = "~> 4.0"
  # ...
}

Rename the cluster name variable

Replace name with cluster_name.

Before
After

module "ecs" {
  name = "example"
}

module "ecs" {
  cluster_name = "example"
}

Replace container_insights with cluster_settings

The container_insights boolean has been replaced by cluster_settings, which accepts a map and allows finer control. Container insights is enabled by default, so you can simply remove the variable if you were setting it to true.

Before
After

container_insights = true

# Enabled by default — no configuration needed
# To explicitly control it:
cluster_settings = {
  name  = "containerInsights"
  value = "enabled"
}

Migrate capacity providers

Replace capacity_providers and default_capacity_provider_strategy with fargate_capacity_providers and autoscaling_capacity_providers.

Before
After

capacity_providers = ["FARGATE", "FARGATE_SPOT"]

default_capacity_provider_strategy = [{
  capacity_provider = "FARGATE"
  weight            = 50
  base              = 20
  }, {
  capacity_provider = "FARGATE_SPOT"
  weight            = 50
}]

fargate_capacity_providers = {
  FARGATE = {
    default_capacity_provider_strategy = {
      weight = 50
      base   = 20
    }
  }
  FARGATE_SPOT = {
    default_capacity_provider_strategy = {
      weight = 50
    }
  }
}

For EC2 AutoScaling Group capacity providers, remove the standalone aws_ecs_capacity_provider resource and move the configuration into autoscaling_capacity_providers.

Before
After

resource "aws_ecs_capacity_provider" "prov1" {
  name = "prov1"

  auto_scaling_group_provider {
    auto_scaling_group_arn = module.autoscaling.autoscaling_group_arn
  }
}

module "ecs" {
  capacity_providers = [aws_ecs_capacity_provider.prov1.name]

  default_capacity_provider_strategy = [{
    capacity_provider = aws_ecs_capacity_provider.prov1.name
    weight            = "1"
  }]
}

module "ecs" {
  autoscaling_capacity_providers = {
    prov1 = {
      auto_scaling_group_arn = module.autoscaling.autoscaling_group_arn
      default_capacity_provider_strategy = {
        weight = 1
      }
    }
  }
}

Migrate the ecs-instance-profile sub-module

The ecs-instance-profile sub-module has been removed. You can pin the sub-module at v3.5.0 until you are ready to migrate to the IAM instance profile provided by the terraform-aws-autoscaling module.

module "ec2_profile" {
  source  = "terraform-aws-modules/ecs/aws//modules/ecs-instance-profile"
  # Pin to last version that includes the sub-module
  version = "3.5.0"

  name = "example"
}

See the examples/complete example for a full demonstration of integrating with terraform-aws-autoscaling to replace this sub-module.

Move capacity provider state (optional)

If you previously managed aws_ecs_capacity_provider resources outside the module and want to bring them under module management, use terraform state mv to avoid destroying and recreating them.

# Update the resource address to match your configuration names
terraform state mv \
  'aws_ecs_capacity_provider.prov1' \
  'module.ecs.aws_ecs_capacity_provider.this["prov1"]'

This step is optional. If you skip it, Terraform will destroy the existing capacity provider and create a new one under the module’s management. This may cause brief disruption to cluster capacity.

Update output references

Update any references to the renamed outputs:

Old reference	New reference
`module.ecs.ecs_cluster_id`	`module.ecs.cluster_id`
`module.ecs.ecs_cluster_arn`	`module.ecs.cluster_arn`
`module.ecs.ecs_cluster_name`	(removed — use `module.ecs.cluster_id` which returns the ARN, or hardcode the name)

Complete before/after example

Before (v3.x)
After (v4.x)

module "ecs" {
  source  = "terraform-aws-modules/ecs/aws"
  version = "3.5.0"

  name               = "example"
  container_insights = true

  capacity_providers = ["FARGATE", "FARGATE_SPOT", aws_ecs_capacity_provider.prov1.name]

  default_capacity_provider_strategy = [{
    capacity_provider = aws_ecs_capacity_provider.prov1.name
    weight            = "1"
  }]
}

module "ec2_profile" {
  source  = "terraform-aws-modules/ecs/aws//modules/ecs-instance-profile"
  version = "3.5.0"

  name = local.name
}

resource "aws_ecs_capacity_provider" "prov1" {
  name = "prov1"

  auto_scaling_group_provider {
    auto_scaling_group_arn = module.autoscaling.autoscaling_group_arn
  }
}

module "ecs" {
  source  = "terraform-aws-modules/ecs/aws"
  version = "4.0.0"

  cluster_name = "example"

  fargate_capacity_providers = {
    FARGATE      = {}
    FARGATE_SPOT = {}
  }

  autoscaling_capacity_providers = {
    prov1 = {
      auto_scaling_group_arn = module.autoscaling.autoscaling_group_arn
      default_capacity_provider_strategy = {
        weight = 1
      }
    }
  }
}

module "ec2_profile" {
  source  = "terraform-aws-modules/ecs/aws//modules/ecs-instance-profile"
  # Pin to v3.5.0 until migrating to autoscaling module IAM profile
  version = "3.5.0"

  name = "example"
}

Get Started

Architecture

Guides

Upgrade Guides

What changed

Breaking changes

Variable and output changes

Removed variables

Renamed variables

Added variables

Removed outputs

Renamed outputs

Added outputs

Migration guide

Complete before/after example

​What changed

​Breaking changes

​Variable and output changes

​Removed variables

​Renamed variables

​Added variables

​Removed outputs

​Renamed outputs

​Added outputs

​Migration guide

​Complete before/after example

What changed

Breaking changes

Variable and output changes

Removed variables

Renamed variables

Added variables

Removed outputs

Renamed outputs

Added outputs

Migration guide

Complete before/after example