仕様の形式
CloudFormation は、AWS::S3::Bucket
や AWS::EC2::Instance
など、各リソースタイプ用の仕様を作成します。次のセクションで、仕様の形式と各フィールドについて説明します。
固有セクション
各リソースタイプの形式定義は、次の例に示すように、PropertyTypes
、ResourceSpecificationVersion
、および ResourceTypes
という 3 つの主要セクションで構成されています。
{ "PropertyTypes": { Property specifications }, "ResourceSpecificationVersion": "
Specification version number
", "ResourceTypes": { Resource specification } }
PropertyTypes
-
プロパティ内にプロパティがある (サブプロパティともいいます) リソースの場合の、サブプロパティのリスト。どのプロパティが必須か、各プロパティで許可される値の型、それらの更新動作などです。詳細については、「プロパティの仕様」を参照してください。
リソースにサブプロパティが存在しない場合は、このセクションは省略されます。
ResourceSpecificationVersion
-
リソース仕様のバージョン。バージョン形式は
であり、リリースごとにバージョン番号が増加します。リソースが更新されたかどうかにかかわらず、すべてのリソースのバージョン番号は同じです。majorVersion
.minorVersion
.patch
CloudFormation では、繋がっていなかったドキュメントリンクの修正など、サービスで後方互換性のあるバグ修正が行われた場合、パッチ番号が増加します。CloudFormation で後方互換性のあるリソースまたはプロパティが追加された場合は、マイナーバージョン番号が増加します。たとえば、仕様のより新しいバージョンによって、AWS のサービスの新機能をサポートするための追加リソースプロパティが追加されることがあります。
後方互換性が変更されるとメジャーバージョン番号が増加します。後方互換性の変更は、フィールドの名前変更などのリソース仕様の変更、またはオプションのリソースプロパティを必須にするなどのリソースへの変更により発生します。
ResourceTypes
-
リソースと、プロパティ名、どのプロパティが必須か、および更新動作など、各リソースプロパティに関する情報のリストです。詳細については、「リソース仕様」を参照してください。
注記
1 つのリソースタイプの定義を含むファイルを確認すると、このプロパティ名は
ResourceType
(単数) になっています。
プロパティの仕様
各プロパティの仕様には以下のフィールドが含まれています。サブプロパティでは、プロパティ名には
形式が使用されます。resourceType
.subpropertyName
"
Property name
": { "Documentation": "Link to the relevant documentation
" "DuplicatesAllowed": "true or false
", "ItemType": "Type of list or map (non-primitive)
", "PrimitiveItemType": "Type of list or map (primitive)
", "PrimitiveType": "Type of value (primitive)
", "Required": "true or false
", "Type": "Type of value (non-primitive)
", "UpdateType": "Mutable, Immutable, or Conditional
", }
Documentation
-
プロパティに関する情報が記載された「AWS CloudFormation ユーザーガイド」へのリンク。
DuplicatesAllowed
-
Type
フィールドの値がList
の場合、CloudFormation で重複した値が許可されるかどうかを示します。値がtrue
の場合、CloudFormation は重複した値を無視します。値がfalse
の場合、重複した値が送信されると CloudFormation はエラーを返します。 ItemType
-
Type
フィールドの値がList
またはMap
の場合、リストまたはマップにプリミティブ型以外が含まれていれば、その型を示します。それ以外の場合、このフィールドは省略されます。リストまたはマップにプリミティブ型が含まれる場合は、PrimitiveItemType
プロパティに有効な値の型が示されます。サブプロパティ名は有効な項目の型です。たとえば、型の値が
List
であり項目型の値がPortMapping
である場合、ポートマッピングプロパティのリストを指定できます。 PrimitiveItemType
-
Type
フィールドの値がList
またはMap
の場合、リストまたはマップにプリミティブ型が含まれていれば、その型を示します。それ以外の場合、このフィールドは省略されます。リストまたはマップにプリミティブ型以外が含まれる場合は、ItemType
プロパティに有効な値の型が示されます。リストまたはマップの有効なプリミティブ型は、
String
、Long
、Integer
、Double
、Boolean
、またはTimestamp
です。たとえば、型の値が
List
であり項目型の値がString
である場合、プロパティに文字列のリストを指定できます。型の値がMap
であり項目型の値がBoolean
である場合、プロパティに文字列からブール型のマッピングを指定できます。 PrimitiveType
-
プリミティブ型の値の場合、プロパティの有効なプリミティブ型。プリミティブ型はリソースプロパティの値の基本的なデータ型です。有効なプリミティブ型は、
String
、Long
、Integer
、Double
、Boolean
、Timestamp
またはJson
です。有効な値がプリミティブ型以外の場合は、このフィールドは省略され、Type
フィールドに有効な値の型が表示されます。 Required
-
プロパティが必須かどうかを示します。
Type
-
プリミティブ型以外では、プロパティの有効値。有効な型はサブプロパティ名、
List
またはMap
です。有効な値がプリミティブ型の場合は、このフィールドは省略され、PrimitiveType
フィールドに有効な値の型が表示されます。リストは、コンマ区切りの値の一覧です。マップは、キーが常に文字列である一連のキーと値のペアです。リストおよびマップの値の型は、
ItemType
またはPrimitiveItemType
フィールドで示されます。 UpdateType
-
スタックの更新中に、プロパティを追加、削除、または変更したときの更新動作。変更不可能なプロパティを変更すると、CloudFormation はリソースを置き換えます。変更可能なプロパティを変更すると、CloudFormation はリソースを置き換えません。条件付き更新は、たとえば更新した他のプロパティによって、ミュータブルまたはイミュータブルになります。詳細については、関連するリソースタイプのドキュメントを参照してください。
リソース仕様
各リソースタイプの仕様には次のフィールドが含まれています。
"
Resource type name
": { "Attributes": { "AttributeName
": { "ItemType": "Return list or map type (non-primitive)
", "PrimitiveItemType": "Return list or map type (primitive)
", "PrimitiveType": "Return value type (primitive)
", "Type": "Return value type (non-primitive)
", } }, "Documentation": "Link to the relevant documentation
", "Properties": { Property specifications } }
Attributes
-
Fn::GetAtt 関数で使用できるリソース属性の一覧。このセクションでは、各属性について、属性名と CloudFormation から返される値の型を説明します。
ItemType
-
Type
フィールドの値がList
の場合、リストにプリミティブ型以外が含まれていれば、Fn::GetAtt
関数によって属性に返されるリストの型が示されます。有効な型はプロパティ名です。 PrimitiveItemType
-
Type
フィールドの値がList
の場合、リストにプリミティブ型が含まれていれば、Fn::GetAtt
関数によって属性に返されるリストの型が示されます。リストにプリミティブ型以外が含まれる場合は、ItemType
プロパティに有効な値の型が示されます。リストの有効なプリミティブ型は、String
、Long
、Integer
、Double
、Boolean
、またはTimestamp
です。たとえば、型の値が
List
でありプリミティブ項目型の値がString
である場合、Fn::GetAtt
関数によって文字列のリストが返されます。 PrimitiveType
-
プリミティブ型の戻り値の場合、
Fn::GetAtt
関数によって属性に返されるプリミティブ値の型。プリミティブ型はリソースプロパティの値の基本的なデータ型です。有効なプリミティブ型は、String
、Long
、Integer
、Double
、Boolean
、Timestamp
またはJson
です。 Type
-
プリミティブ型以外の戻り値の場合、
Fn::GetAtt
関数によって属性に返される値の型。有効な型はプロパティ名またはList
です。リストは、コンマ区切りの値の一覧です。リストの値の型は、
ItemType
またはPrimitiveItemType
フィールドで示されます。
Documentation
-
リソースに関する情報が記載された「AWS CloudFormation ユーザーガイド」へのリンク。
Properties
-
リソースのプロパティ仕様のリスト。詳細については、「プロパティの仕様」を参照してください。
リソース仕様の例
次の例では、AWS::Elasticsearch::Domain
リソース仕様の一部を取り上げて説明します。
AWS::Elasticsearch::Domain
リソースタイプにはサブプロパティが含まれているため、仕様に PropertyTypes
セクションが含まれます。このセクションに、仕様バージョンを ResourceSpecificationVersion
と示す 1.0.0
セクションが続きます。仕様のバージョンの後は、リソースタイプを指定する ResourceType
セクションであり、ドキュメントのリンクとリソースのプロパティの詳細が示されます。
{ "PropertyTypes": { ... }, "ResourceSpecificationVersion": "1.0.0", "ResourceType": { "AWS::Elasticsearch::Domain": { "Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-elasticsearch-domain.html", "Properties": { ... } } } } }
ResourceType
セクションに焦点を当てた次の例では、AWS::Elasticsearch::Domain
リソースタイプの 2 つのプロパティが示されています。AdvancedOptions
プロパティは必須ではなく、文字列間マップを使用します。マップは、キーが常に文字列であるキーと値のペアの集合です。値型は ItemType
フィールドで示されます。String
になります。したがって、型は文字列間マップです。このプロパティの更新動作はミュータブルです。このプロパティを更新すると、CloudFormation は新しいリソースを作成する代わりにこのリソースを保持して、古いものを削除します (イミュータブル更新)。
SnapshotOptions
プロパティは必須ではなく、SnapshotOptions
という名前のサブプロパティを使用します。SnapshotOptions
サブプロパティの詳細は、「PropertyTypes
」セクションで説明されています。
{ "PropertyTypes": { ... }, "ResourceSpecificationVersion": "1.0.0", "ResourceType": { "AWS::Elasticsearch::Domain": { "Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-elasticsearch-domain.html", "Properties": { ... "AdvancedOptions": { "Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-elasticsearch-domain.html#cfn-elasticsearch-domain-advancedoptions", "DuplicatesAllowed": false, "PrimitiveItemType": "String", "Required": false, "Type": "Map", "UpdateType": "Mutable" }, ... "SnapshotOptions": { "Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-elasticsearch-domain.html#cfn-elasticsearch-domain-snapshotoptions", "Required": false, "Type": "SnapshotOptions", "UpdateType": "Mutable" }, ... } } } }
PropertyTypes
では、仕様内容はリソースのサブプロパティがすべて一覧表示します (ネストされたサブプロパティ含む)。次の例では、AWS::Elasticsearch::Domain.SnapshotOptions
サブプロパティについて説明します。これには AutomatedSnapshotStartHour
という名前のプロパティが 1 つ含まれますが必須ではなく、整数値タイプを使用します。
"PropertyTypes": { ... "AWS::Elasticsearch::Domain.SnapshotOptions": { "Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-elasticsearch-domain-snapshotoptions.html", "Properties": { "AutomatedSnapshotStartHour": { "Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-elasticsearch-domain-snapshotoptions.html#cfn-elasticsearch-domain-snapshotoptions-automatedsnapshotstarthour", "PrimitiveType": "Integer", "Required": false, "UpdateType": "Mutable" } } }, ... }
参考のために、次の例で AWS::Elasticsearch::Domain
リソース仕様全体を示します。
{ "PropertyTypes": { "AWS::Elasticsearch::Domain.EBSOptions": { "Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-elasticsearch-domain-ebsoptions.html", "Properties": { "EBSEnabled": { "Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-elasticsearch-domain-ebsoptions.html#cfn-elasticsearch-domain-ebsoptions-ebsenabled", "PrimitiveType": "Boolean", "Required": false, "UpdateType": "Mutable" }, "Iops": { "Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-elasticsearch-domain-ebsoptions.html#cfn-elasticsearch-domain-ebsoptions-iops", "PrimitiveType": "Integer", "Required": false, "UpdateType": "Mutable" }, "VolumeSize": { "Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-elasticsearch-domain-ebsoptions.html#cfn-elasticsearch-domain-ebsoptions-volumesize", "PrimitiveType": "Integer", "Required": false, "UpdateType": "Mutable" }, "VolumeType": { "Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-elasticsearch-domain-ebsoptions.html#cfn-elasticsearch-domain-ebsoptions-volumetype", "PrimitiveType": "String", "Required": false, "UpdateType": "Mutable" } } }, "AWS::Elasticsearch::Domain.ElasticsearchClusterConfig": { "Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-elasticsearch-domain-elasticsearchclusterconfig.html", "Properties": { "DedicatedMasterCount": { "Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-elasticsearch-domain-elasticsearchclusterconfig.html#cfn-elasticsearch-domain-elasticseachclusterconfig-dedicatedmastercount", "PrimitiveType": "Integer", "Required": false, "UpdateType": "Mutable" }, "DedicatedMasterEnabled": { "Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-elasticsearch-domain-elasticsearchclusterconfig.html#cfn-elasticsearch-domain-elasticseachclusterconfig-dedicatedmasterenabled", "PrimitiveType": "Boolean", "Required": false, "UpdateType": "Mutable" }, "DedicatedMasterType": { "Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-elasticsearch-domain-elasticsearchclusterconfig.html#cfn-elasticsearch-domain-elasticseachclusterconfig-dedicatedmastertype", "PrimitiveType": "String", "Required": false, "UpdateType": "Mutable" }, "InstanceCount": { "Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-elasticsearch-domain-elasticsearchclusterconfig.html#cfn-elasticsearch-domain-elasticseachclusterconfig-instancecount", "PrimitiveType": "Integer", "Required": false, "UpdateType": "Mutable" }, "InstanceType": { "Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-elasticsearch-domain-elasticsearchclusterconfig.html#cfn-elasticsearch-domain-elasticseachclusterconfig-instancetype", "PrimitiveType": "String", "Required": false, "UpdateType": "Mutable" }, "ZoneAwarenessEnabled": { "Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-elasticsearch-domain-elasticsearchclusterconfig.html#cfn-elasticsearch-domain-elasticseachclusterconfig-zoneawarenessenabled", "PrimitiveType": "Boolean", "Required": false, "UpdateType": "Mutable" } } }, "AWS::Elasticsearch::Domain.SnapshotOptions": { "Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-elasticsearch-domain-snapshotoptions.html", "Properties": { "AutomatedSnapshotStartHour": { "Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-elasticsearch-domain-snapshotoptions.html#cfn-elasticsearch-domain-snapshotoptions-automatedsnapshotstarthour", "PrimitiveType": "Integer", "Required": false, "UpdateType": "Mutable" } } }, "Tag": { "Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-resource-tags.html", "Properties": { "Key": { "Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-resource-tags.html#cfn-resource-tags-key", "PrimitiveType": "String", "Required": true, "UpdateType": "Immutable" }, "Value": { "Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-resource-tags.html#cfn-resource-tags-value", "PrimitiveType": "String", "Required": true, "UpdateType": "Immutable" } } } }, "ResourceType": { "AWS::Elasticsearch::Domain": { "Attributes": { "DomainArn": { "PrimitiveType": "String" }, "DomainEndpoint": { "PrimitiveType": "String" } }, "Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-elasticsearch-domain.html", "Properties": { "AccessPolicies": { "Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-elasticsearch-domain.html#cfn-elasticsearch-domain-accesspolicies", "PrimitiveType": "Json", "Required": false, "UpdateType": "Mutable" }, "AdvancedOptions": { "Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-elasticsearch-domain.html#cfn-elasticsearch-domain-advancedoptions", "DuplicatesAllowed": false, "PrimitiveItemType": "String", "Required": false, "Type": "Map", "UpdateType": "Mutable" }, "DomainName": { "Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-elasticsearch-domain.html#cfn-elasticsearch-domain-domainname", "PrimitiveType": "String", "Required": false, "UpdateType": "Immutable" }, "EBSOptions": { "Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-elasticsearch-domain.html#cfn-elasticsearch-domain-ebsoptions", "Required": false, "Type": "EBSOptions", "UpdateType": "Mutable" }, "ElasticsearchClusterConfig": { "Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-elasticsearch-domain.html#cfn-elasticsearch-domain-elasticsearchclusterconfig", "Required": false, "Type": "ElasticsearchClusterConfig", "UpdateType": "Mutable" }, "ElasticsearchVersion": { "Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-elasticsearch-domain.html#cfn-elasticsearch-domain-elasticsearchversion", "PrimitiveType": "String", "Required": false, "UpdateType": "Immutable" }, "SnapshotOptions": { "Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-elasticsearch-domain.html#cfn-elasticsearch-domain-snapshotoptions", "Required": false, "Type": "SnapshotOptions", "UpdateType": "Mutable" }, "Tags": { "Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-elasticsearch-domain.html#cfn-elasticsearch-domain-tags", "DuplicatesAllowed": true, "ItemType": "Tag", "Required": false, "Type": "List", "UpdateType": "Mutable" } } } }, "ResourceSpecificationVersion": "1.4.1" }