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 removedcontainer_insights variable replaced with cluster_settingscapacity_providers and default_capacity_provider_strategy replaced with fargate_capacity_providers and autoscaling_capacity_providersaws_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
Renamed outputs
| Before | After |
|---|
ecs_cluster_id | cluster_id |
ecs_cluster_arn | cluster_arn |
Added outputs
cluster_capacity_providersautoscaling_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.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.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.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
}
}
}
aws_ecs_capacity_provider resource and move the configuration into autoscaling_capacity_providers.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"
}
