【AWS CloudFormation】CAPABILITY_IAM と CAPABILITY_NAMED_IAM どう使い分けたら良いのか

概要

AWS CLI を用いて、CloudFormation のスタックを作成する時に、
Capabilities を要求される場面があるかと思います。

その時に、CAPABILITY_IAM と CAPABILITY_NAMED_IAM どっちでも通るけどどっち使えばいいんだ？ってなることがあったので、公式リファレンスの自分の理解をこの場にまとめます。

そもそもどういう場合にCapabilitiesが必要になるのか

作成する CloudFormation のスタックの中のリソースに IAM リソースがある場合です。

AWS CloudFormationがスタックを作成するために、スタックテンプレートに特定の機能が含まれていることを明示的に確認する必要があります。
参考: https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_CreateStack.html

AWS のドキュメントにもある通り、CloudFormation がスタックを作成するために、特定の機能が含まれていることを明示的に示す必要があるということです。

では、2つの違いは

それでは CAPABILITY_IAM と CAPABILITY_NAMED_IAM は何が違うのでしょうか。
それはカスタム名の IAM リソースがある場合とそうでない場合です。
IAM リソース名は指定しない場合、<CloudFormationスタック名>-<CloudFormationリソース名>-<ランダム文字列>で作成されますが、これを任意の名称に指定することもできます。

名称を指定した（=カスタム名）IAM リソースがある場合は CAPABILITY_NAMED_IAM のみ。名称を指定しない場合は、どちらでも指定することが出来る様です。

まだ2つほどCapabilitiesはある

上で紹介した 2 つ以外にも、CAPABILITY_RESOURCE_POLICY および CAPABILITY_AUTO_EXPAND なるものが存在する様です。（参考: https://docs.aws.amazon.com/ja_jp/serverlessrepo/latest/devguide/acknowledging-application-capabilities.html ）

CAPABILITY_RESOURCE_POLICY に関しては以下のものがリソースとして存在する場合に必要な様です。

AWS::Lambda::LayerVersionPermission,AWS::Lambda::Permission,AWS::Events::EventBusPolicy,AWS። IAM: ポリシー,AWS::ApplicationAutoScaling::ScalingPolicy,AWS::S3::BucketPolicy,AWS::SQS::QueuePolicy, およびAWS::SNS::TopicPolicy。
参考: https://docs.aws.amazon.com/ja_jp/serverlessrepo/latest/devguide/acknowledging-application-capabilities.html

CAPABILITY_AUTO_EXPAND に関しては 1 つまたは複数のネストされたアプリケーションが含まれているアプリケーションで指定する必要がある。とあり、具体的にはこちらでサンプルとして用意されているものと同様のリソースが当てはまるようです。
タイトルとは少し逸れてしまうので、詳しくは公式ドキュメントを参考にしてみて下さい。

まとめ

CloudFormation で作成されるスタックのリソースの中にカスタム名の IAM リソースがあれば CAPABILITY_NAMED_IAM。
IAM リソースの名称を指定していない場合は、CAPABILTY_IAM CAPABILITY_NAMED_IAM どちらも使える様です。（とはいえ、不必要に NAMED の方を使う理由も無さそうですが）