When do I need to have CAPABILITY_NAMED_IAM

Question

I was editing my CloudFormation templates and suddenly AWS tells me I need CAPABILITY_NAMED_IAM. I am curious as to which change triggers this?

What is

Answer 1

You've added a resource of type AWS::IAM::Role to your resources section. This tells CloudFormation to create an IAM Role. In order to create IAM resources, you need to supply CAPABILITY_IAM or CAPABILITY_NAMED_IAM. It's an acknowledgement from you to CloudFormation that you understand that you are creating resources that can affect permissions in your AWS account.

Answer 2

When are CAPABILITIES_IAM/CAPABILITIES_NAMED_IAM Required

According to CloudFormation CreateStack Parameters, one of these is required when your Template includes any of the following o:

AWS::IAM::AccessKey
AWS::IAM::Group
AWS::IAM::InstanceProfile
AWS::IAM::Policy
AWS::IAM::Role
AWS::IAM::User
AWS::IAM::UserToGroupAddition 

When to use CAPABILITIES_NAMED_IAM instead of CAPABILITIES_IAM

When any of your IAM resources have a custom name, such as a RoleName then CAPABILITIES_NAMED_IAM is required.

Why are these required?

The Capabilites are there to ensure you realize that you're creating IAM resources, that these will modify the permissions on your account, and that you have reviewed these resources and their permissions as necessary.