AWS CloudFormation
User Guide (API Version 2010-05-15)
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Go to the Kindle Store to download this guide in Kindle format.Did this page help you?  Yes | No |  Tell us about it...

AWS::IAM::Role

Creates an AWS Identity and Access Management (IAM) role. An IAM role can be used to enable applications running on an Amazon 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 },
      "Path": String,
      "Policies": [ IAM policy, ... ]
   }
}

Properties

AssumeRolePolicyDocument

The IAM assume role 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.

Path

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

Required: Yes

Type: String

Update requires: Replacement

Policies

A list of embedded policies to associate with this role. Policies can also be specified externally. For sample templates that demonstrates both embedded and external policies, see Template Examples.

Required: No

Type: A list of IAM policies.

Update requires: No interruption

Notes on policies for IAM roles

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

Return Values

Ref

When the logical ID of this resource is provided to the Ref intrinsic function, it 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 corresponding 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"
            } ]
         }
      }
   }
}