Menu
AWS CloudFormation
User Guide (API Version 2010-05-15)

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

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

Properties

AssumeRolePolicyDocument

The trust policy that is associated with this role.

Required: Yes

Type: A JSON policy document

Update requires: No interruption

Note

You can associate only one assume role policy with a role. For an example of an assume role policy, see Template Examples.

ManagedPolicyArns

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

Required: No

Type: List of strings

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

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 do updates that require this resource to be replaced. You can still do 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. This section lists the available attributes and sample return values.

Arn

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

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

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

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

Template Examples

Example 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.

{
   "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"
            } ]
         }
      }
   }
}

Example 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.


{
   "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"
            } ]
         }
      }
   }
}