Understanding `InsufficientCapabilitiesException [CAPABILITY_NAMED_IAM]` in AWS

Amazon Web Services (AWS) CloudFormation is a powerful Infrastructure as Code (IaC) service that allows developers to define and provision AWS infrastructure in a consistent manner. When launching a CloudFormation stack, you may encounter an error known as `InsufficientCapabilitiesException [CAPABILITY_NAMED_IAM]`. This exception occurs when the stack includes AWS Identity and Access Management (IAM) resources such as roles, users, or policies, and the necessary capabilities have not been explicitly acknowledged.

What is `CAPABILITY_NAMED_IAM`?

The `CAPABILITY_NAMED_IAM` is a capability that must be explicitly specified when creating or updating a CloudFormation stack that includes IAM resources. When AWS CloudFormation needs to create IAM resources that have custom names, it requires acknowledgment of this capability to ensure you are aware of the implications of granting potentially wide-ranging permissions.

Why the Exception Occurs

The `InsufficientCapabilitiesException [CAPABILITY_NAMED_IAM]` is thrown if:

1. IAM Resources Detected: The template includes IAM resources such as roles, users, or policies with custom names.
2. Lack of Explicit Acknowledgment: The stack operation command or request does not include the explicit acknowledgment of the `CAPABILITY_NAMED_IAM`.
3. Automation Scripts Missing Capabilities Argument: Automation scripts or CI/CD pipelines invoking CloudFormation stack creation/update fail to include the necessary capabilities, resulting in the exception.

How to Resolve the Exception

To resolve this exception, you must explicitly acknowledge the capability when using the AWS Management Console, AWS CLI, or SDKs.

AWS Management Console

1. When creating or updating the stack, at the Review page, you will see a section asking for acknowledgment.
2. Check the box next to "I acknowledge that AWS CloudFormation might create IAM resources with custom names."

AWS CLI

When using the AWS CLI to create or update a stack, you need to include the `--capabilities` option:

• Wide-reaching Permissions: Custom IAM resources can grant broad permissions across your AWS account, and these permissions might be exploited if not correctly scoped.
• Resource Isolation: Ensure that the IAM policies are crafted following the principle of least privilege, granting only the necessary permissions required for your applications or services.