IAM Role

Amazon Web Services
An IAM role is an IAM identity attached with permissions policies that grant access and actions to AWS resources. A role can be delegated to users on an individual basis and can be assigned to as many individuals as needed.
Terraform Name
IAM Role

The following argument is required:

  • assume_role_policy - (Required) Policy that grants an entity permission to assume the role.


The assume_role_policy is very similar to but slightly different than a standard IAM policy and cannot use an aws_iam_policy resource. However, it can use an aws_iam_policy_document data source. See the example above of how this works.

The following arguments are optional:

  • description - (Optional) Description of the role.
  • force_detach_policies - (Optional) Whether to force detaching any policies the role has before destroying it. Defaults to false.
  • inline_policy - (Optional) Configuration block defining an exclusive set of IAM inline policies associated with the IAM role. See below. If no blocks are configured, Terraform will not manage any inline policies in this resource. Configuring one empty block (i.e., inline_policy {}) will cause Terraform to remove all inline policies added out of band on apply.
  • managed_policy_arns - (Optional) Set of exclusive IAM managed policy ARNs to attach to the IAM role. If this attribute is not configured, Terraform will ignore policy attachments to this resource. When configured, Terraform will align the role's managed policy attachments with this set by attaching or detaching managed policies. Configuring an empty set (i.e., managed_policy_arns = []) will cause Terraform to remove all managed policy attachments.
  • max_session_duration - (Optional) Maximum session duration (in seconds) that you want to set for the specified role. If you do not specify a value for this setting, the default maximum of one hour is applied. This setting can have a value from 1 hour to 12 hours.
  • name - (Optional, Forces new resource) Friendly name of the role. If omitted, Terraform will assign a random, unique name. See IAM Identifiers for more information.
  • name_prefix - (Optional, Forces new resource) Creates a unique friendly name beginning with the specified prefix. Conflicts with name.
  • path - (Optional) Path to the role. See IAM Identifiers for more information.
  • permissions_boundary - (Optional) ARN of the policy that is used to set the permissions boundary for the role.
  • tags - Key-value mapping of tags for the IAM role. If configured with a provider default_tags configuration block present, tags with matching keys will overwrite those defined at the provider-level.


This configuration block supports the following:


Since one empty block (i.e., inline_policy {}) is valid syntactically to remove out of band policies on apply, name and policy are technically optional. However, they are both required in order to manage actual inline policies. Not including one or the other may not result in Terraform errors but will result in unpredictable and incorrect behavior.

  • name - (Required) Name of the role policy.
  • policy - (Required) Policy document as a JSON formatted string. For more information about building IAM policy documents with Terraform, see the AWS IAM Policy Document Guide.

Associating resources with a
IAM Role
Resources do not "belong" to a
IAM Role
Rather, one or more Security Groups are associated to a resource.
IAM Role
via Terraform:
The following HCL creates an IAM role resource with assume role policy

resource "aws_iam_role" "test_role" {
 name = "test_role"

 # Terraform's "jsonencode" function converts a
 # Terraform expression result to valid JSON syntax.
 assume_role_policy = jsonencode({
   Version = "2012-10-17"
   Statement = [
       Action = "sts:AssumeRole"
       Effect = "Allow"
       Sid    = ""
       Principal = {
         Service = ""

 tags = {
   tag-key = "tag-value"

IAM Role
via CLI:

[--path <value>]
--role-name <value>
--assume-role-policy-document <value>
[--description <value>]
[--max-session-duration <value>]
[--permissions-boundary <value>]
[--tags <value>]
[--cli-input-json | --cli-input-yaml]
[--generate-cli-skeleton <value>]
[--endpoint-url <value>]
[--output <value>]
[--query <value>]
[--profile <value>]
[--region <value>]
[--version <value>]
[--color <value>]
[--ca-bundle <value>]
[--cli-read-timeout <value>]
[--cli-connect-timeout <value>]
[--cli-binary-format <value>]


aws iam create-role --role-name Test-Role --assume-role-policy-document file://Test-Role-Trust-Policy.json

aws cost
The cost of using Identity and Access Management (IAM) features is free, as it is included in the overall cost of using Amazon Web Services (AWS). There are no charges for creating or using IAM users, groups, roles, or policies. However, some AWS services, such as Amazon S3 or Amazon EC2, may incur charges for using IAM features, such as creating an IAM role to access an Amazon S3 bucket or an Amazon EC2 instance.
Direct Cost


Indirect Cost
No items found.
Best Practices for
IAM Role

Categorized by Availability, Security & Compliance and Cost

Access allowed from VPN
No items found.
Auto Scaling Group not in use
No items found.
Connections towards DynamoDB should be via VPC endpoints
No items found.
Container in CrashLoopBackOff state
No items found.
EC2 with GPU capabilities
No items found.
EC2 with high privileged policies
No items found.
ECS cluster delete alarm
No items found.
ECS task with Admin access (*:*)
ECS task with high privileged policies
No items found.
EKS cluster delete alarm
No items found.
ElastiCache cluster delete alarm
No items found.
Ensure Container liveness probe is configured
No items found.
Ensure ECS task definition has memory limit
No items found.
Ensure EMR cluster master nodes are not publicly accessible
No items found.
More from
Amazon Web Services