IAM roles

The AWS ECS Terraform module creates up to five distinct IAM roles depending on which features you enable. Each role has a specific purpose tied to a different phase of the ECS task lifecycle or a different compute type.

Role summary

Role	Principal	Created by	Purpose
Task execution role	`ecs-tasks.amazonaws.com`	Cluster or service sub-module	Lets ECS pull images and retrieve secrets during task launch
Tasks IAM role	`ecs-tasks.amazonaws.com`	Service sub-module	Lets containers access AWS services at runtime
Service IAM role	`ecs.amazonaws.com`	Service sub-module	Lets ECS register/deregister load balancer targets
Infrastructure IAM role	`ecs.amazonaws.com`	Cluster sub-module	Used by ECS to manage EC2 fleet for Managed Instances
Node IAM role	`ec2.amazonaws.com`	Cluster sub-module	Used by EC2 nodes in the Managed Instances fleet

Task execution role

The task execution role is assumed by the ECS service (ecs-tasks.amazonaws.com) during task launch — not by the containers themselves. ECS uses this role to:

Pull container images from Amazon ECR.
Write log streams to CloudWatch Logs.
Retrieve SSM Parameter Store values injected as environment variables.
Retrieve Secrets Manager secrets injected as environment variables.

The task execution role’s permissions are not accessible to the containers at runtime. They are consumed only during the task creation process. Runtime access to AWS services is handled by the tasks IAM role.

Shared vs. per-service patterns

Cluster-level (shared)
Service-level (per-service)

Create one task execution role in the cluster sub-module and share it across all services in the cluster. This is the simplest pattern and works well when all services in the cluster are owned by the same team.

module "cluster" {
  source  = "terraform-aws-modules/ecs/aws//modules/cluster"
  version = "~> 7.0"

  name = "my-cluster"

  # Create the role here — all services will inherit it
  create_task_exec_iam_role = true
  create_task_exec_policy   = true

  # Optionally scope SSM and Secrets Manager access at the cluster level
  task_exec_ssm_param_arns = ["arn:aws:ssm:us-east-1:123456789012:parameter/shared/*"]
  task_exec_secret_arns    = ["arn:aws:secretsmanager:us-east-1:123456789012:secret:shared/*"]
}

module "service" {
  source  = "terraform-aws-modules/ecs/aws//modules/service"
  version = "~> 7.0"

  name        = "api"
  cluster_arn = module.cluster.arn

  # Don't create a new role — use the one from the cluster module
  create_task_exec_iam_role = false
  task_exec_iam_role_arn    = module.cluster.task_exec_iam_role_arn
}

When using the root module, this is handled automatically: setting create_task_exec_iam_role = true at the top level creates the cluster-level role, and its ARN is forwarded to every service via task_exec_iam_role_arn = try(coalesce(each.value.task_exec_iam_role_arn, module.cluster.task_exec_iam_role_arn), null).

Create one task execution role per service. This is the recommended pattern for shared clusters where different teams own different services and need SSM/Secrets Manager access scoped to their own parameters.

module "cluster" {
  source  = "terraform-aws-modules/ecs/aws//modules/cluster"
  version = "~> 7.0"

  name = "shared-cluster"

  # No cluster-level task execution role
  create_task_exec_iam_role = false
}

module "team_a_service" {
  source  = "terraform-aws-modules/ecs/aws//modules/service"
  version = "~> 7.0"

  name        = "team-a-api"
  cluster_arn = module.cluster.arn

  # Each service creates its own task execution role
  create_task_exec_iam_role = true
  create_task_exec_policy   = true

  # Scoped to this team's secrets only
  task_exec_ssm_param_arns = ["arn:aws:ssm:us-east-1:123456789012:parameter/team-a/*"]
  task_exec_secret_arns    = ["arn:aws:secretsmanager:us-east-1:123456789012:secret:team-a/*"]
}

Task execution role permissions

The module creates a custom IAM policy (rather than attaching the AWS-managed AmazonECSTaskExecutionRolePolicy) so that permissions can be scoped precisely. The policy includes:

Statement	Actions	Resources
`Logs`	`logs:CreateLogStream`, `logs:PutLogEvents`	`*`
`ECR`	`ecr:GetAuthorizationToken`, `ecr:BatchCheckLayerAvailability`, `ecr:GetDownloadUrlForLayer`, `ecr:BatchGetImage`	`*`
`GetSSMParams`	`ssm:GetParameters`	ARNs from `task_exec_ssm_param_arns`
`GetSecrets`	`secretsmanager:GetSecretValue`	ARNs from `task_exec_secret_arns`
Custom	Any	Fully configurable via `task_exec_iam_statements`

Additional managed policies can be attached via task_exec_iam_role_policies (a map of policy name to ARN).The GetSSMParams and GetSecrets statements are only included when the respective ARN lists are non-empty, keeping the policy minimal by default.

Controlling variables

Variable	Module	Default	Description
`create_task_exec_iam_role`	Cluster, Service	`true`	Whether to create the role
`create_task_exec_policy`	Cluster, Service	`true`	Whether to create and attach the inline policy
`task_exec_iam_role_name`	Cluster, Service	`<cluster/service>-task-exec`	Role name
`task_exec_iam_role_use_name_prefix`	Cluster, Service	`true`	Use a name prefix instead of a fixed name
`task_exec_iam_role_policies`	Cluster, Service	`{}`	Additional managed policies to attach
`task_exec_ssm_param_arns`	Cluster, Service	`[]`	SSM parameter ARNs to allow `ssm:GetParameters`
`task_exec_secret_arns`	Cluster, Service	`[]`	Secrets Manager ARNs to allow `secretsmanager:GetSecretValue`
`task_exec_iam_statements`	Cluster, Service	`{}`	Additional inline policy statements
`task_exec_iam_role_permissions_boundary`	Cluster, Service	`null`	Permissions boundary ARN

Tasks IAM role

The tasks IAM role is assumed by the containers within the task at runtime. This is analogous to an EC2 instance profile or a Kubernetes IRSA role. If your application needs to read from S3, connect to RDS using IAM authentication, publish to SQS, or call any AWS API, those permissions belong on the tasks IAM role. The tasks IAM role is created by the service sub-module only. It is scoped to the specific service.

Tasks IAM role permissions

The base tasks IAM role has no permissions by default. Permissions are added through:

Mechanism	Variable	Description
Inline policy statements	`tasks_iam_role_statements`	List of IAM policy statement objects
Managed policy attachments	`tasks_iam_role_policies`	Map of policy name to ARN
ECS Exec	`enable_execute_command`	Automatically adds `ssmmessages:*` permissions required for `ecs execute-command`

When enable_execute_command = true, the module injects the following statement:

statement {
  sid = "ECSExec"
  actions = [
    "ssmmessages:CreateControlChannel",
    "ssmmessages:CreateDataChannel",
    "ssmmessages:OpenControlChannel",
    "ssmmessages:OpenDataChannel",
  ]
  resources = ["*"]
}

The assume role policy includes two conditions to prevent confused deputy attacks:

aws:SourceArn must match arn:*:ecs:<region>:<account>:*
aws:SourceAccount must match the deploying account ID

Controlling variables

Variable	Default	Description
`create_tasks_iam_role`	`true`	Whether to create the tasks IAM role
`tasks_iam_role_arn`	`null`	ARN of a pre-existing role to use instead
`tasks_iam_role_name`	`<service>-tasks`	Role name
`tasks_iam_role_use_name_prefix`	`true`	Use a name prefix
`tasks_iam_role_policies`	`{}`	Managed policies to attach
`tasks_iam_role_statements`	`null`	Inline policy statements
`tasks_iam_role_permissions_boundary`	`null`	Permissions boundary ARN
`tasks_iam_role_max_session_duration`	`null`	Maximum session duration in seconds

Service IAM role

The service IAM role is assumed by the ECS service (ecs.amazonaws.com) and is used to register and deregister task IPs or instances with Elastic Load Balancing target groups or classic load balancers.

This role is only required when the service uses a load balancer and the task network mode is not awsvpc. For Fargate tasks (which always use awsvpc), the load balancer registers task ENI IPs directly and this role is not needed. The module automatically determines whether to create it based on network_mode and load_balancer.

The condition for creation in the service module is:

needs_iam_role  = var.network_mode != "awsvpc" && var.load_balancer != null
create_iam_role = var.create && var.create_iam_role && local.needs_iam_role

Service IAM role permissions

The service IAM role receives a policy with the following permissions:

Statement	Actions
`ECSService`	`ec2:Describe`, `elasticloadbalancing:DeregisterInstancesFromLoadBalancer`, `elasticloadbalancing:DeregisterTargets`, `elasticloadbalancing:Describe`, `elasticloadbalancing:RegisterInstancesWithLoadBalancer`, `elasticloadbalancing:RegisterTargets`

Additional statements can be added via iam_role_statements.

Controlling variables

Variable	Default	Description
`create_iam_role`	`true`	Whether to create the service IAM role
`iam_role_arn`	`null`	ARN of a pre-existing role to use
`iam_role_name`	`<service>`	Role name
`iam_role_use_name_prefix`	`true`	Use a name prefix
`iam_role_statements`	`null`	Additional inline policy statements
`iam_role_permissions_boundary`	`null`	Permissions boundary ARN

Infrastructure IAM role

The infrastructure IAM role is used by ECS to manage the underlying EC2 compute fleet when using the ECS Managed Instances capacity provider type. It is assumed by the ECS service principal (ecs.amazonaws.com) and allows ECS to create and manage EC2 launch templates, run EC2 instances, and tag resources. This role is created by the cluster sub-module and is only created when at least one capacity provider in capacity_providers has a managed_instances_provider block configured.

locals {
  create_infrastructure_iam_role = (
    var.create &&
    var.create_infrastructure_iam_role &&
    local.managed_instances_enabled  # true when any capacity provider uses managed_instances_provider
  )
}

Infrastructure IAM role permissions

The module creates a custom policy (rather than using AmazonECSInfrastructureRolePolicyForManagedInstances) to avoid a surprising AWS requirement that the role name start with ecsInstanceRole when using the managed policy.Key permission groups:

Statement	Actions	Notes
`CreateLaunchTemplateForManagedInstances`	`ec2:CreateLaunchTemplate`	Restricted to resources tagged `AmazonECSManaged=true`
`CreateLaunchTemplateVersionsForManagedInstances`	`ec2:CreateLaunchTemplateVersion`, `ec2:ModifyLaunchTemplate`	Restricted to ECS-managed resources
`ProvisionEC2InstancesForManagedInstances`	`ec2:CreateFleet`	Fleet, instance, network interface, launch template, volume
`RunInstancesForManagedInstances`	`ec2:RunInstances`	Instance, volume, network interface
`TagOnCreateEC2ResourcesForManagedInstances`	`ec2:CreateTags`	Only on `CreateFleet`, `CreateLaunchTemplate`, `RunInstances`
`PassInstanceRoleForManagedInstances`	`iam:PassRole`	Passes the node IAM role to EC2
`CreateServiceLinkedRoleForEC2Spot`	`iam:CreateServiceLinkedRole`	For EC2 Spot service-linked role
`DescribeEC2ResourcesManagedByECS`	`ec2:Describe*`	Read-only discovery of VPC, subnet, SG, instance resources

Controlling variables

Variable	Default	Description
`create_infrastructure_iam_role`	`true`	Whether to create the role (only applies when Managed Instances is enabled)
`infrastructure_iam_role_name`	`<cluster>-infra`	Role name
`infrastructure_iam_role_use_name_prefix`	`true`	Use a name prefix
`infrastructure_iam_role_source_policy_documents`	`null`	Source policy documents to merge
`infrastructure_iam_role_override_policy_documents`	`null`	Override policy documents
`infrastructure_iam_role_statements`	`null`	Additional inline policy statements
`infrastructure_iam_role_permissions_boundary`	`null`	Permissions boundary ARN

Node IAM role

The node IAM role is attached to EC2 instances launched by the ECS Managed Instances capacity provider via an instance profile. It is assumed by ec2.amazonaws.com and grants the ECS agent running on each node the permissions it needs to register with the cluster, poll for tasks, and report state. Like the infrastructure role, the node IAM role is created by the cluster sub-module and is only created when Managed Instances is in use.

AWS documentation states that when using the AWS-managed AmazonECSInstanceRolePolicyForManagedInstances policy, the instance profile must be named ecsInstanceRole. This module avoids that constraint by creating a custom equivalent policy, allowing any name.

Node IAM role permissions

The module creates a custom policy equivalent to AmazonECSInstanceRolePolicyForManagedInstances:

Statement	Actions	Resources
`ECSAgentDiscoverPollEndpointPermissions`	`ecs:DiscoverPollEndpoint`	`*`
`ECSAgentRegisterPermissions`	`ecs:RegisterContainerInstance`	The specific cluster ARN
`ECSAgentPollPermissions`	`ecs:Poll`	Container instances in the account
`ECSAgentTelemetryPermissions`	`ecs:StartTelemetrySession`, `ecs:PutSystemLogEvents`	Container instances in the account
`ECSAgentStateChangePermissions`	`ecs:SubmitAttachmentStateChanges`, `ecs:SubmitTaskStateChange`	The specific cluster ARN

Additional policies can be attached via node_iam_role_additional_policies. Custom statements can be added via node_iam_role_statements.An aws_iam_instance_profile resource is created alongside the role so that EC2 instances launched by the Managed Instances fleet can use it.

Controlling variables

Variable	Default	Description
`create_node_iam_instance_profile`	`true`	Whether to create the node role and instance profile
`node_iam_role_name`	`<cluster>-node`	Role name
`node_iam_role_use_name_prefix`	`true`	Use a name prefix
`node_iam_role_additional_policies`	`{}`	Additional managed policies to attach
`node_iam_role_source_policy_documents`	`null`	Source policy documents to merge
`node_iam_role_override_policy_documents`	`null`	Override policy documents
`node_iam_role_statements`	`null`	Additional inline policy statements
`node_iam_role_permissions_boundary`	`null`	Permissions boundary ARN

Get Started

Architecture

Guides

Upgrade Guides

Role summary

Task execution role

Shared vs. per-service patterns

Controlling variables

Tasks IAM role

Controlling variables

Service IAM role

Controlling variables

Infrastructure IAM role

Controlling variables

Node IAM role

Controlling variables

Build docs developers (and LLMs) love

Get Started

Architecture

Guides

Upgrade Guides

​Role summary

​Task execution role

​Shared vs. per-service patterns

​Controlling variables

​Tasks IAM role

​Controlling variables

​Service IAM role

​Controlling variables

​Infrastructure IAM role

​Controlling variables

​Node IAM role

​Controlling variables

Build docs developers (and LLMs) love

Role summary

Task execution role

Shared vs. per-service patterns

Controlling variables

Tasks IAM role

Controlling variables

Service IAM role

Controlling variables

Infrastructure IAM role

Controlling variables

Node IAM role

Controlling variables