CloudFormationの隠されたプロパティを見つける方法
2025.05.02はじめに
皆様こんにちは、あかいけです。
突然ですがCloudFormationを書くときに、どのドキュメントを参考にしていますでしょうか？
CloudFormation初学者の私はもっぱらAWS CloudFormation User Guideを使っており、
日々格闘しながらコードを書き続けています。
しかしAWS CloudFormation User Guideでは、リソースによっては記載されていないプロパティがあり、
それが原因で様々な問題に直面することがありました。
そこで今回は、CloudFormationで指定できるリソースの詳細な仕様を確認できるドキュメントについてまとめました。
ドキュメント
1. AWS CloudFormation User Guide
まず最初に、多くの方が利用している基本的なガイドラインです。
リソースタイプをブラウザで検索すると、通常最初に表示されるのではないでしょうか。
ただし冒頭でも触れたように、記述が不足していたり曖昧な部分があったりするため、
複雑な設定を行おうとすると困難に直面することがあります。
例えばElastiCacheのパラメータグループ(AWS::ElastiCache::ParameterGroup)のドキュメントでは、
パラメータグループ名を指定するプロパティが明示されていません。
しかし同ページ内のReturn valuesのセクションにCacheParameterGroupNameという項目の記述があり、
実際にこれをPropertiesで指定すると、パラメータグループ名を指定して作成できます。
Resources:
ElastiCacheParameterGroup:
Type: AWS::ElastiCache::ParameterGroup
Properties:
CacheParameterGroupName: elasticache-valkey8-pg
CacheParameterGroupFamily: valkey8
Description: Parameter group for ElastiCache Valkey8
このようにAWS CloudFormation User Guide上では部分的に仕様が欠落している場合があるため、
個人的にはこれ以降に紹介する方法を推奨します。
2. AWS CLI
リソースタイプの詳細な仕様は、以下のAWS CLIコマンドで確認できます。
aws cloudformation describe-type \
--type RESOURCE \
--type-name $RESOURCE_NAME
例えばElastiCacheのパラメータグループであれば以下のように指定します。
aws cloudformation describe-type \
--type RESOURCE \
--type-name AWS::ElastiCache::ParameterGroup
出力結果
arn:aws:cloudformation:ap-northeast-1::type/resource/AWS-ElastiCache-ParameterGroup LIVE Resource Type definition for AWS::ElastiCache::ParameterGroup True FULLY_MUTABLE {
"typeName": "AWS::ElastiCache::ParameterGroup",
"description": "Resource Type definition for AWS::ElastiCache::ParameterGroup",
"additionalProperties": false,
"properties": {
"Description": {
"type": "string",
"description": "The description for this cache parameter group."
},
"Properties": {
"type": "object",
"additionalProperties": false,
"patternProperties": {
"[a-zA-Z0-9]+": {
"type": "string"
}
},
"description": "A comma-delimited list of parameter name/value pairs. For more information see ModifyCacheParameterGroup in the Amazon ElastiCache API Reference Guide."
},
"Tags": {
"type": "array",
"description": "Tags are composed of a Key/Value pair. You can use tags to categorize and track each parameter group. The tag value null is permitted.",
"items": {
"$ref": "#/definitions/Tag"
},
"insertionOrder": false,
"uniqueItems": false
},
"CacheParameterGroupName": {
"type": "string",
"description": "The name of the Cache Parameter Group."
},
"CacheParameterGroupFamily": {
"type": "string",
"description": "The name of the cache parameter group family that this cache parameter group is compatible with."
}
},
"definitions": {
"Tag": {
"type": "object",
"additionalProperties": false,
"properties": {
"Key": {
"type": "string"
},
"Value": {
"type": "string"
}
},
"required": [
"Value",
"Key"
]
}
},
"required": [
"Description",
"CacheParameterGroupFamily"
],
"readOnlyProperties": [
"/properties/CacheParameterGroupName"
],
"createOnlyProperties": [
"/properties/CacheParameterGroupFamily"
],
"primaryIdentifier": [
"/properties/CacheParameterGroupName"
],
"tagging": {
"taggable": true,
"tagOnCreate": true,
"tagUpdatable": true,
"cloudFormationSystemTags": false,
"tagProperty": "/properties/Tags"
},
"handlers": {
"create": {
"permissions": [
"ElastiCache:CreateCacheParameterGroup",
"ElastiCache:DescribeCacheParameterGroups",
"ElastiCache:AddTagsToResource",
"ElastiCache:ModifyCacheParameterGroup",
"iam:CreateServiceLinkedRole",
"iam:PutRolePolicy"
]
},
"read": {
"permissions": [
"ElastiCache:DescribeCacheParameterGroups",
"ElastiCache:DescribeCacheParameters",
"ElastiCache:ListTagsForResource"
]
},
"update": {
"permissions": [
"ElastiCache:ModifyCacheParameterGroup",
"ElastiCache:DescribeCacheParameterGroups",
"ElastiCache:DescribeCacheParameters",
"ElastiCache:DescribeEngineDefaultParameters",
"ElastiCache:AddTagsToResource",
"ElastiCache:RemoveTagsFromResource"
]
},
"delete": {
"permissions": [
"ElastiCache:DescribeCacheParameterGroups",
"ElastiCache:DeleteCacheParameterGroup"
]
},
"list": {
"permissions": [
"ElastiCache:DescribeCacheParameterGroups"
]
}
}
}
プロパティだけ確認したければ、
以下のようにフィルターをかけるといい感じに抜き出せます。
aws cloudformation describe-type \
--type RESOURCE \
--type-name AWS::ElastiCache::ParameterGroup \
--query 'Schema' | jq -r 'fromjson.properties'
出力結果
{
"Description": {
"type": "string",
"description": "The description for this cache parameter group."
},
"Properties": {
"type": "object",
"additionalProperties": false,
"patternProperties": {
"[a-zA-Z0-9]+": {
"type": "string"
}
},
"description": "A comma-delimited list of parameter name/value pairs. For more information see ModifyCacheParameterGroup in the Amazon ElastiCache API Reference Guide."
},
"Tags": {
"type": "array",
"description": "Tags are composed of a Key/Value pair. You can use tags to categorize and track each parameter group. The tag value null is permitted.",
"items": {
"$ref": "#/definitions/Tag"
},
"insertionOrder": false,
"uniqueItems": false
},
"CacheParameterGroupName": {
"type": "string",
"description": "The name of the Cache Parameter Group."
},
"CacheParameterGroupFamily": {
"type": "string",
"description": "The name of the cache parameter group family that this cache parameter group is compatible with."
}
}
プロパティも網羅的に記載されていますし、何よりCLI上で操作が完結するので、
ブラウザとエディターの行き来が億劫な方はこの方法がいいかもしれませんね。
3. CloudFormation レジストリ
CloudFormation レジストリは、
CloudFormationアカウントで使用できる拡張機能を管理するためのものです。
AWS公式のリソースタイプはパブリック拡張機能として公開されています。
マネジメントコンソールから確認することができ、
スキーマの内容はaws cloudformation describe-typeコマンドで出力される内容と同一です。
したがって、ブラウザで仕様を確認したい場合はCloudFormationレジストリ、
エディター上で完結したい場合はAWS CLI、と使い分けるのが良さそうですね。
4. API リファレンス
最後にAPIリファレンスです。
例として、以下はElastiCacheのAPIリファレンスです。
APIリファレンスはサービスごとにページが分かれており、
以下のドキュメントのトップページ → 各サービス → API Reference と進むと辿り着けます。
CloudFormation、ひいてはAWSの内部動作に関わる部分であり、
通常はここまで詳細に確認する必要はないかもしれません。
しかし、一度目を通しておくと理解が深まるため、時間があるときに参照してみるのも良いでしょう。
またCloudFormationのリソースタイプのプロパティと、APIのリクエストパラメータが対応関係にあり、
CloudFormationが裏側でどれだけ多くのAPIリクエストを代行してくれているかを知ることができます。
とてもありがたいですね。
さいごに
以上、CloudFormationの隠されたプロパティを見つける方法でした。
これだけ多様なリファレンスを整備・管理してくれているAWSの取り組みは素晴らしいですね。
皆さんもCloudFormationを記述する際に、これらのドキュメントを活用していただければと思います。
