AWS CloudFormation
User Guide (API Version 2010-05-15)
AWS 服务或AWS文档中描述的功能,可能因地区/位置而异。请点击 Amazon AWS 入门,可查看中国地区的具体差异

规范格式

AWS CloudFormation 为每个资源类型 (如 AWS::S3::BucketAWS::EC2::Instance) 创建规范。以下部分介绍了格式和此规范内的每个字段。

规范部分

每个资源类型的正式定义组织成三个主要部分:PropertyTypesResourceSpecificationVersionResourceTypes,如以下示例所示:

Copy
{ "PropertyTypes": { Property specifications }, "ResourceSpecificationVersion": "Specification version number", "ResourceTypes": { Resource specification } }
PropertyTypes

对于具有某个属性中的属性 (又称为子属性) 的资源,为一个子属性规范列表,例如哪些属性是必需的,每个属性允许的值的类型以及属性的更新行为。有关更多信息,请参阅 属性规范

如果资源没有子属性,则忽略此部分。

ResourceSpecificationVersion

资源规范的版本。版本格式为 majorVersion.minorVersion.patch,其中,每个版本会增加版本号。所有资源都具有相同的版本号,无论资源是否已更新。

AWS CloudFormation 在服务进行向后兼容的错误修复 (如修复断开的文档链接) 时会增加修补程序版本号。当 AWS CloudFormation 添加向后兼容的资源或属性时,它会增加次要版本号。例如,更高版本的规范可能添加其他资源属性以支持 AWS 服务的新功能。

向后兼容的更改会增加主要版本号。向后兼容的更改可能是由资源规范中的更改 (如字段的名称更改) 或资源更改 (如将可选资源属性设为必需属性) 导致的。

ResourceTypes

资源以及有关每项资源的属性信息,如其属性名称、哪些属性是必需的以及属性的更新行为。有关更多信息,请参阅 资源规范

注意

如果您查看包含一种资源类型定义的文件,则属性名称为 ResourceType (单数)。

属性规范

每个属性的规范均包含以下字段。对于子属性,属性名称使用 resourceType.subpropertyName 格式。

Copy
"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,则指示 AWS CloudFormation 是否允许重复值。如果值为 true,则 AWS CloudFormation 将忽略重复值。如果值为 false,则 AWS CloudFormation 会在您提交重复值时返回错误。

ItemType

如果 Type 字段的值为 ListMap,则指示列表或映射的类型 (如果它们包含非基元类型)。否则,将忽略此字段。对于包含基元类型的列表或映射,PrimitiveItemType 属性指示有效值类型。

子属性名称是有效项目类型。例如,如果类型值为 List 且项目类型值为 PortMapping,则您可指定端口映射属性的列表。

PrimitiveItemType

如果 Type 字段的值为 ListMap,则指示列表或映射的类型 (如果它们包含基元类型)。否则,将忽略此字段。对于包含非基元类型的列表或映射,ItemType 属性指示有效值类型。

列表和映射的有效基元类型为 StringLongIntegerDoubleBooleanTimestamp

例如,如果类型值为 List 且项目类型值为 String,您可以指定属性的字符串列表。如果类型值为 Map 且项目类型值为 Boolean,您可以指定属性的字符串到布尔值映射。

PrimitiveType

对于基元值,为属性的有效基元类型。基元类型是资源属性值的基本数据类型。有效基元类型为 StringLongIntegerDoubleBooleanTimestampJson。如果有效值为非基元类型,则将忽略此字段,并且 Type 字段指示有效值类型。

Required

指示属性是否为必需属性。

Type

对于非基元类型,为属性的有效值。有效类型为子属性名称、ListMap。如果有效值为基元类型,则将忽略此字段,并且 PrimitiveType 字段指示有效值类型。

列表是值的逗号分隔列表。映射是一组密钥/值对,其中,密钥始终为字符串。列表和映射的值类型由 ItemTypePrimitiveItemType 字段指示。

UpdateType

堆栈更新期间,为添加、删除或修改属性时的更新行为。在您更改 Immutable 属性时,AWS CloudFormation 将替换资源。在您更改 mutable 属性时,AWS CloudFormation 不会替换资源。条件更新可以是可变的,也可以是不可变的,具体取决于您更新的其他属性。有关更多信息,请参阅相关的资源类型文档。

资源规范

每个资源类型的规范均包含以下字段。

Copy
"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 函数中使用的资源属性的列表。对于每个属性,此部分提供属性名称和 AWS CloudFormation 返回的值的类型。

ItemType

如果 Type 字段的值为 List,则指示在列表包含非基元类型的情况下,Fn::GetAtt 函数为此属性返回的列表的类型。有效类型为属性的名称。

PrimitiveItemType

如果 Type 字段的值为 List,则指示在列表包含基元类型的情况下,Fn::GetAtt 函数为此属性返回的列表的类型。对于包含非基元类型的列表,ItemType 属性指示有效值类型。列表的有效基元类型为 StringLongIntegerDoubleBooleanTimestamp

例如,如果类型值为 List 且基元项目类型值为 String,则 Fn::GetAtt 函数返回字符串列表。

PrimitiveType

对于基元返回值,为 Fn::GetAtt 函数为此属性返回的基元值的类型。基元类型是资源属性值的基本数据类型。有效基元类型为 StringLongIntegerDoubleBooleanTimestampJson

Type

对于非基元返回值,为 Fn::GetAtt 函数为此属性返回的值的类型。有效类型为属性名称或 List

列表是值的逗号分隔列表。列表的值类型由 ItemTypePrimitiveItemType 字段指示。

Documentation

有关资源的信息的 AWS CloudFormation 用户指南 的链接。

Properties

资源的属性规范的列表。有关详细信息,请参阅 属性规范

示例资源规范

以下示例重点介绍和说明 AWS::Elasticsearch::Domain 资源规范的各个部分。

AWS::Elasticsearch::Domain 资源类型包含子属性,因此其规范包括 PropertyTypes 部分。此部分后跟 ResourceSpecificationVersion 部分,它将规范版本显示为 1.0.0。在规范版本为指定资源类型的 ResourceType 部分后,提供文档链接并详细说明资源的属性。

Copy
{ "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 资源类型的两个属性。AdvancedOptions 属性不是必需属性,并且接受字符串到字符串映射。映射是一个密钥/值对集合,其中,密钥始终为字符串。值类型由 ItemType 字段指示,为 String。因此,该类型为字符串到字符串映射。此属性的更新行为是可变的。如果更新此属性,AWS CloudFormation 会保留资源而不是创建新资源,然后删除旧资源 (不可变更新)。

SnapshotOptions 属性不是必需属性,并且接受名为 SnapshotOptions 的子属性。PropertyTypes 部分提供了 SnapshotOptions 子属性的详细信息。

Copy
{ "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 的属性,此属性不是必需属性,并且接受整数值类型。

Copy
"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 资源规范以供您参考。

Copy
{ "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-instnacetype", "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" }