AWS CloudFormation -- capabilities parameter
Originally published at https://lukemiller.dev/blog/aws-cloudformation-capabilities-parameter-ab73a373278/
If you’re anything like me, you’ve probably found yourself wondering what the capabilities parameter does that is requested during a deployment of a CloudFormation (CF) template?
We’ve all hit that InsufficientCapabilitiesException: Requires capabilities : [CAPABILITY_IAM] error before, and if you’re on the CLI it tells you exactly how to overcome the error. With the solution provided for you, it’s easy to give the CLI what it wants and move right along with the rest of your work without digging into what that CAPABILITY_IAM is even doing. So, here’s an explanation.
tl;dr
When you update or create a CF stack, there are certain events that CF requires your explicit acknowledgment of before completing. Adding the capabilities parameter is you giving consent to perform those necessary actions. It’s like granting an IAM permission that only lasts for a single CF stack update or creation. There are three capabilities you can grant to CF, the most common, CAPABILITY_IAM, gives CF consent to create IAM resources on your behalf.
Why It’s Needed
The CF API documentation for CreateStack states that “in some cases, you must explicitly acknowledge that your stack template contains certain capabilities for AWS CloudFormation to create the stack.” The key words there are “explicitly acknowledge.” That’s why in the command line we need to add — capabilities, and in the API pass Capabilities.member.1= <capability>, because CF needs to know we know what’s in our stack.
Without that parameter, CF will throw a security-related error. This is because AWS takes IAM seriously and doesn’t want IAM resources created all willy-nilly for you. AWS encourages users to closely monitor their IAM roles and policies, and regularly review their maintenance of a least-privilege permissions environment. In that spirit, AWS wants to have an explicit acknowledgement from you regarding any IAM resources created for you. You’ve seen AWS ask you about IAM roles when setting up other resources on the management console. For instance, here’s the message about AWS potentially creating you a role for CodePipeline…
And here’s the Lambda console, again with a message asking you to create a role or let AWS create one for you…
The CloudFormation management console provides a similar form when creating or updating a stack…
In my experience, however, I’ve never created/updated a CF template from the console. So, that may be why it might feel a little different on the CLI or API when asked to type out this capability, but it’s the same concept.
Again, without the capabilities parameter passed, you’ll receive the InsufficientCapabilities error because your template contains resources with required CF capabilities that weren’t specified in the capabilities parameter. The capabilities parameter is you saying to CF, “I know I’m giving you the power to <fill in the blank>”.
The three capabilities and when you need them.
CAPABILITY_IAM: needed whenever AWS is affecting your permissions or creating new IAM resources
CAPABILITY_NAMED_IAM: needed if you are providing a custom name for an IAM resource
CAPABILITY_AUTO_EXPAND: needed anytime you use template macros, most commonly for SAM template users is the AWS::Serverless transform macro which turns your SAM template into a CF template.
So the CAPABILITY_AUTO_EXPAND has nothing to do with AWS protecting your IAM resources, but it’s them checking to make sure you realize your template is about to change since your using macros. The moral of the story, if your account will experience changes, they want to make sure you know it’s happening.
Here are some manifestations of the capabilities error:
An error occurred (InsufficientCapabilitiesException) when calling the ExecuteChangeSet operation: Requires capabilities : [CAPABILITY_IAM]
An error occurred (InsufficientCapabilitiesException) when calling the CreateStack operation: Requires capabilities : [CAPABILITY_NAMED_IAM]
An error occurred (InsufficientCapabilitiesException) when calling the UpdateStack operation: Requires capabilities : [CAPABILITY_NAMED_IAM]
JobFailed Requires capabilities: [CAPABILITY_AUTO_EXPAND]
InsufficientCapabilitiesException: Requires capabilities : [CAPABILITY_AUTO_EXPAND]
All in all, it’s pretty straightforward. I think it’s funny that it’s treated as a one-time capability when it’ll likely be added to your buildspec.yml to repeated on every deployment, but nevertheless, AWS is protective of your IAM resources, so I guess that’s nice.
