规范格式 - Amazon CloudFormation
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

规范格式

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

规范部分

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

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

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

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

ResourceSpecificationVersion

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

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

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

ResourceTypes

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

注意

如果您查看包含一种资源类型定义的文件,则属性名称为 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

指向《Amazon CloudFormation 用户指南》的链接,其中提供有关属性的信息。

DuplicatesAllowed

如果 Type 字段的值为 List,则指示 Amazon CloudFormation 是否允许使用重复值。如果值为 true,Amazon CloudFormation 将忽略重复值。如果值为 false,则 Amazon 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

在堆栈更新期间,这是添加、删除或修改属性时的更新行为。在更改不可变属性时,Amazon CloudFormation 将替换资源。在更改可变属性时,Amazon 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 函数中使用的资源属性的列表。对于每个属性,此部分提供属性名称和 Amazon 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

指向《Amazon 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 资源类型的两个属性。AdvancedOptions 属性不是必需属性,并且接受字符串到字符串映射。映射是一个键值对集合,其中,键始终为字符串。值类型由 ItemType 字段指示,为 String。因此,该类型为字符串到字符串映射。该属性的更新行为是可变的。如果更新该属性,Amazon 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 的属性,该属性不是必需属性,并且接受整数值类型。

"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" }