规范格式

CloudFormation 为每种资源类型（如 AWS::S3::Bucket 或 AWS::EC2::Instance）创建一个规范。以下部分介绍了格式和此规范内的每个字段。

主题

规范部分
属性规范
资源规范
示例资源规范

规范部分

每个资源类型的正式定义组织成三个主要部分：PropertyTypes、ResourceSpecificationVersion 和 ResourceTypes，如以下示例所示：


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

PropertyTypes

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

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

ResourceSpecificationVersion

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

CloudFormation 在服务进行向后兼容的错误修复（如修复断开的文档链接）时会递增补丁版本号。当 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，则指示 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 不会替换该资源。条件更新可以是可变的，也可以是不可变的，具体取决于您更新的其他属性。有关更多信息，请参阅 Amazon 资源和属性类型参考。

资源规范

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


"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

指向《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。因此，该类型为字符串到字符串映射。该属性的更新行为是可变的。如果更新该属性，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"
}

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

资源规范

资源提供程序架构