Sign In to the Console
AWS CloudFormation
User Guide (API Version 2010-05-15)

AWS Documentation » AWS CloudFormation » User Guide » Template Reference » AWS Resource and Property Types Reference » AWS Identity and Access Management Resource Types Reference » AWS::IAM::Role

AWS::IAM::Role

Creates an AWS Identity and Access Management (IAM) role. Use an IAM role to enable applications running on an EC2 instance to securely access your AWS resources.

For more information about IAM roles, see Working with Roles in the AWS Identity and Access Management User Guide.

Syntax

To declare this entity in your AWS CloudFormation template, use the following syntax:

JSON

{
  "Type": "AWS::IAM::Role",
  "Properties": {
    "AssumeRolePolicyDocument": { JSON },
    "ManagedPolicyArns": [ String, ... ],
    "MaxSessionDuration": Integer,
    "Path": String,
    "PermissionsBoundary": String,
    "Policies": [ Policies, ... ],
    "RoleName": String
  }
}

YAML

Type: AWS::IAM::Role
Properties: 
  AssumeRolePolicyDocument:
    JSON object
  ManagedPolicyArns:
    - String
  MaxSessionDuration: Integer
  Path: String
  PermissionsBoundary: String
  Policies:
    - Policies
  RoleName: String

Properties

AssumeRolePolicyDocument

The trust policy that is associated with this role. You can associate only one assume role policy with a role. For an example of an assume role policy, see Template Examples. For more information about the elements that you can use in an IAM policy, see IAM Policy Elements Reference in the IAM User Guide.

Required: Yes

Type: A JSON policy document

Note

AWS Identity and Access Management (IAM) requires that policies be in JSON format. However, for templates formatted in YAML, you can create an IAM policy in either JSON or YAML format. AWS CloudFormation always converts a policy to JSON format before submitting it to IAM.

Update requires: No interruption

ManagedPolicyArns

One or more managed policy ARNs to attach to this role.

Required: No

Type: List of String values

Update requires: No interruption

MaxSessionDuration

The maximum session duration (in seconds) for the specified role. Anyone who uses the AWS CLI or API to assume the role can specify the duration using the optional DurationSeconds API parameter or duration-seconds CLI parameter. Minimum value of 3600. Maximum value of 43200.

Required: No

Type: Integer

Update requires: No interruption

Path

The path associated with this role. For information about IAM paths, see Friendly Names and Paths in IAM User Guide.

Required: No

Type: String

Update requires: Replacement

PermissionsBoundary

The ARN of the policy that is used to set the permissions boundary for the role. Minimum length of 20. Maximum length of 2048.

Required: No

Type: String

Update requires: No interruption

Policies

The policies to associate with this role. For sample templates, see Template Examples.

Important

The name of each policy for a role, user, or group must be unique. If you don't, updates to the IAM role will fail.

Note

If an external policy (such as AWS::IAM::Policy or AWS::IAM::ManagedPolicy) has a Ref to a role and if a resource (such as AWS::ECS::Service) also has a Ref to the same role, add a DependsOn attribute to the resource to make the resource depend on the external policy. This dependency ensures that the role's policy is available throughout the resource's lifecycle. For example, when you delete a stack with an AWS::ECS::Service resource, the DependsOn attribute ensures that AWS CloudFormation deletes the AWS::ECS::Service resource before deleting its role's policy.

Required: No

Type: List of IAM Policies

Update requires: No interruption

RoleName

A name for the IAM role. For valid values, see the RoleName parameter for the CreateRole action in the IAM API Reference. If you don't specify a name, AWS CloudFormation generates a unique physical ID and uses that ID for the group name.

Important

If you specify a name, you cannot perform updates that require replacement of this resource. You can perform updates that require no or some interruption. If you must replace the resource, specify a new name.

If you specify a name, you must specify the CAPABILITY_NAMED_IAM value to acknowledge your template's capabilities. For more information, see Acknowledging IAM Resources in AWS CloudFormation Templates.

Warning

Naming an IAM resource can cause an unrecoverable error if you reuse the same template in multiple regions. To prevent this, we recommend using Fn::Join and AWS::Region to create a region-specific name, as in the following example: {"Fn::Join": ["", [{"Ref": "AWS::Region"}, {"Ref": "MyResourceName"}]]}.

Required: No

Type: String

Update requires: Replacement

Notes on policies for IAM roles

For general information about IAM policies and policy documents, see How to Write a Policy in IAM User Guide.

Return Values

Ref

When the logical ID of this resource is provided to the Ref intrinsic function, Ref returns the resource name. For example: 

{ "Ref": "RootRole" }

For the IAM::Role with the logical ID "RootRole", Ref will return the resource name.

For more information about using the Ref function, see Ref.

Fn::GetAtt

Fn::GetAtt returns a value for a specified attribute of this type. The following are the available attributes and sample return values.

Arn

Returns the Amazon Resource Name (ARN) for the role. For example:

{"Fn::GetAtt" : ["MyRole", "Arn"] }

This will return a value such as “arn:aws:iam::1234567890:role/MyRole-AJJHDSKSDF”.

RoleId

Returns the stable and unique string identifying the role. For example, AIDAJQABLZS4A3QDU576Q.

For more information about IDs, see IAM Identifiers in the IAM User Guide.

For more information about using Fn::GetAtt, see Fn::GetAtt.

Template Examples

IAM Role with Embedded Policy and Instance Profiles

This example shows an embedded Policy in the IAM::Role. The policy is specified inline in the IAM::Role Policies property.

JSON

{
   "AWSTemplateFormatVersion": "2010-09-09",
   "Resources": {
      "RootRole": {
         "Type": "AWS::IAM::Role",
         "Properties": {
            "AssumeRolePolicyDocument": {
               "Version" : "2012-10-17",
               "Statement": [ {
                  "Effect": "Allow",
                  "Principal": {
                     "Service": [ "ec2.amazonaws.com" ]
                  },
                  "Action": [ "sts:AssumeRole" ]
               } ]
            },
            "Path": "/",
            "Policies": [ {
               "PolicyName": "root",
               "PolicyDocument": {
                  "Version" : "2012-10-17",
                  "Statement": [ {
                     "Effect": "Allow",
                     "Action": "*",
                     "Resource": "*"
                  } ]
               }
               } ]
            }
      },
      "RootInstanceProfile": {
         "Type": "AWS::IAM::InstanceProfile",
         "Properties": {
            "Path": "/",
            "Roles": [ {
               "Ref": "RootRole"
            } ]
         }
      }
   }
}

YAML

AWSTemplateFormatVersion: "2010-09-09"
Resources: 
  RootRole: 
    Type: "AWS::IAM::Role"
    Properties: 
      AssumeRolePolicyDocument: 
        Version: "2012-10-17"
        Statement: 
          - 
            Effect: "Allow"
            Principal: 
              Service: 
                - "ec2.amazonaws.com"
            Action: 
              - "sts:AssumeRole"
      Path: "/"
      Policies: 
        - 
          PolicyName: "root"
          PolicyDocument: 
            Version: "2012-10-17"
            Statement: 
              - 
                Effect: "Allow"
                Action: "*"
                Resource: "*"
  RootInstanceProfile: 
    Type: "AWS::IAM::InstanceProfile"
    Properties: 
      Path: "/"
      Roles: 
        - 
          Ref: "RootRole"

IAM Role with External Policy and Instance Profiles

In this example, the Policy and InstanceProfile resources are specified externally to the IAM Role. They refer to the role by specifying its name, "RootRole", in their respective Roles properties.

JSON

{
   "AWSTemplateFormatVersion": "2010-09-09",
   "Resources": {
      "RootRole": {
         "Type": "AWS::IAM::Role",
         "Properties": {
            "AssumeRolePolicyDocument": {
               "Version" : "2012-10-17",
               "Statement": [ {
                  "Effect": "Allow",
                  "Principal": {
                     "Service": [ "ec2.amazonaws.com" ]
                  },
                  "Action": [ "sts:AssumeRole" ]
               } ]
            },
            "Path": "/"
         }
      },
      "RolePolicies": {
         "Type": "AWS::IAM::Policy",
         "Properties": {
            "PolicyName": "root",
            "PolicyDocument": {
               "Version" : "2012-10-17",
               "Statement": [ {
                  "Effect": "Allow",
                  "Action": "*",
                  "Resource": "*"
               } ]
            },
            "Roles": [ {
               "Ref": "RootRole"
            } ]
         }
      },
      "RootInstanceProfile": {
         "Type": "AWS::IAM::InstanceProfile",
         "Properties": {
            "Path": "/",
            "Roles": [ {
               "Ref": "RootRole"
            } ]
         }
      }
   }
}

YAML

AWSTemplateFormatVersion: "2010-09-09"
Resources: 
  RootRole: 
    Type: "AWS::IAM::Role"
    Properties: 
      AssumeRolePolicyDocument: 
        Version: "2012-10-17"
        Statement: 
          - 
            Effect: "Allow"
            Principal: 
              Service: 
                - "ec2.amazonaws.com"
            Action: 
              - "sts:AssumeRole"
      Path: "/"
  RolePolicies: 
    Type: "AWS::IAM::Policy"
    Properties: 
      PolicyName: "root"
      PolicyDocument: 
        Version: "2012-10-17"
        Statement: 
          - 
            Effect: "Allow"
            Action: "*"
            Resource: "*"
      Roles: 
        - 
          Ref: "RootRole"
  RootInstanceProfile: 
    Type: "AWS::IAM::InstanceProfile"
    Properties: 
      Path: "/"
      Roles: 
        - 
          Ref: "RootRole"

See Also