Este é o novo *Guia de referência de modelos do CloudFormation*. Atualize seus favoritos e links. Para obter ajuda para começar a usar o CloudFormation, consulte o [Guia do usuário do AWS CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html). # Formato de especificação O CloudFormation cria uma especificação para cada tipo de recurso, como `AWS::S3::Bucket` ou `AWS::EC2::Instance`. As seções a seguir descrevem o formato e cada campo na especificação. **Topics** + [Seções de especificação](#w2aac37b9c23b7) + [Especificação de propriedade](#cfn-resource-specification-format-propertytypes) + [Especificação de recurso](#cfn-resource-specification-format-resourcetype) + [Exemplo de especificação de recurso](#w2aac37b9c23c13) ## Seções de especificação A definição formal para cada tipo de recurso é organizado em três seções principais: `PropertyTypes`, `ResourceSpecificationVersion` e `ResourceTypes`, como mostrado no exemplo a seguir: ``` { "PropertyTypes": { {{Property specifications}} }, "ResourceSpecificationVersion": "{{Specification version number}}", "ResourceTypes": { {{Resource specification}} } } ``` `PropertyTypes` Para recursos que têm propriedades em uma propriedade (também conhecidas como subpropriedades), uma lista de especificações de subpropriedade, como as propriedades necessárias, o tipo de valor permitido para cada propriedade e seu comportamento de atualização. Para obter mais informações, consulte [Especificação de propriedade](#cfn-resource-specification-format-propertytypes). Se um recurso não tem subpropriedades, essa seção é omitida. `ResourceSpecificationVersion` A versão da especificação do recurso. O formato da versão é `{{majorVersion}}.{{minorVersion}}.{{patch}}`, em que cada versão aumenta incrementa o seu número. Todos os recursos têm o mesmo número de versão, independentemente de o recurso ter sido atualizado. O CloudFormation incrementa o número do patch quando o serviço faz uma correção de erros compatível com as versões anteriores, como a correção de um link de documentação desfeito. Quando o CloudFormation adiciona recursos ou propriedades com compatibilidade retroativa, ele aumenta o número de versões secundárias. Por exemplo, versões posteriores de uma especificação podem adicionar propriedades de recursos extras para oferecer suporte a novos recursos de um produto da AWS. Alterações incompatíveis retroativas incrementam o número da versão principal. Uma alteração incompatível retroativa pode ser resultado de uma modificação na especificação do recurso, como uma mudança de nome para um campo, ou uma alteração em um recurso, como tornar uma propriedade de recurso opcional obrigatória. `ResourceTypes` A lista de recursos e as informações sobre cada propriedade de recurso, como seus nomes de propriedade, as propriedades necessárias e seu comportamento de atualização. Para obter mais informações, consulte [Especificação de recurso](#cfn-resource-specification-format-resourcetype). Se você visualizar um arquivo que contém a definição de um tipo de recurso, esse nome de propriedade é `ResourceType` (único). ## Especificação de propriedade A especificação para cada propriedade inclui os seguintes campos. Para as subpropriedades, o nome da propriedade usa o formato `{{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` Um link para o *Guia do usuário do AWS CloudFormation*, que fornece informações sobre a propriedade. `DuplicatesAllowed` Caso o valor do campo `Type` seja `List`, isso indica se o CloudFormation permite valores duplicados. Se o valor for `true`, o CloudFormation ignorará valores duplicados. Se o valor for `false`, o CloudFormation retornará um erro se você enviar valores duplicados. `ItemType` Se o valor do `Type` campo é `List` ou `Map`, indica o tipo de lista ou mapa se estes contêm tipos não primitivos. Caso contrário, esse campo é omitido. Para listas ou mapas que contêm tipos primitivos, a propriedade `PrimitiveItemType` indica o tipo de valor válido. Uma subpropriedade é um tipo de item válido. Por exemplo, se o valor do tipo é `List` e o valor do tipo de item é `PortMapping`, você poderá especificar uma lista de propriedades de mapeamento de porta. `PrimitiveItemType` Se o valor do `Type` campo é `List` ou `Map`, indica o tipo de lista ou mapa se estes contêm tipos primitivos. Caso contrário, esse campo é omitido. Para listas ou mapas que contêm tipos não primitivos, a propriedade `ItemType` indica o tipo de valor válido. Os tipos primitivos válidos para listas e mapas são `String`, `Long`, `Integer`, `Double`, `Boolean` ou `Timestamp`. Por exemplo, se o valor do tipo é `List` e o valor do tipo de item é `String`, você pode especificar uma lista de cadeias de caracteres para a propriedade. Se o tipo de valor é `Map` e o valor do tipo de item valor é `Boolean`, você pode especificar cadeia de caracteres para mapeamento Booleano da propriedade. `PrimitiveType` Para valores primitivos, o tipo primitivo válido para a propriedade. Um tipo primitivo é um tipo de dado básico para valores da propriedade de recurso. Os tipos primitivos válidos são `String`, `Long`, `Integer`, `Double`, `Boolean`, `Timestamp` ou `Json`. Se os valores válidos são um tipo não primitivo, esse campo é omitido e o campo `Type` indica o tipo de valor válido. `Required` Indica se a propriedade é obrigatória. `Type` Para tipos não primitivos, valores válidos para a propriedade. Os tipos válidos são um nome de subpropriedade, `List` ou `Map`. Se os valores válidos são um tipo primitivo, esse campo é omitido e o campo `PrimitiveType` indica o tipo de valor válido. Uma lista é uma lista de valores separados por vírgula. Um mapa é um conjunto de pares de valores chave/valor, onde as chaves são sempre cadeias de caracteres. O tipo de valor para listas e mapas é indicado pelo campo `ItemType` ou `PrimitiveItemType`. `UpdateType` Durante uma atualização da pilha, o comportamento de atualização quando você adiciona, remove ou modifica a propriedade. O CloudFormation substitui o recurso quando você altera as propriedades imutáveis. O CloudFormation não substitui o recurso quando você altera as propriedades mutáveis. As atualizações condicionais podem ser mutáveis ou imutáveis, dependendo, por exemplo, de quais outras propriedades você atualizou. Para obter mais informações, consulte [AWSReferência de tipos de propriedades e recursos da](aws-template-resource-type-ref.md). ## Especificação de recurso A especificação para cada tipo de recurso inclui os campos a seguir. ``` "{{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` Uma lista de atributos de recursos que você pode usar em uma função [`Fn::GetAtt`](intrinsic-function-reference-getatt.md). Para cada atributo, esta seção fornece o nome do atributo e o tipo de valor que o CloudFormation retorna. `ItemType` Se o valor do campo `Type` é `List`, indica o tipo de lista que a função `Fn::GetAtt` retorna para o atributo se a lista contém tipos não primitivos. O tipo válido é o nome de uma propriedade. `PrimitiveItemType` Se o valor do campo `Type` é `List`, indica o tipo de lista que a função `Fn::GetAtt` retorna para o atributo se a lista contém tipos primitivos. Para listas que contêm tipos não primitivos, a propriedade `ItemType` indica o tipo de valor válido. Os tipos primitivos válidos para listas são `String`, `Long`, `Integer`, `Double`, `Boolean` ou `Timestamp`. Por exemplo, se o tipo de valor é `List` e o valor de tipo do item primitivo é `String`, a função `Fn::GetAtt` retorna uma lista de cadeia de caracteres. `PrimitiveType` Para valores primitivos de retorno, o tipo de valor primitivo que a função `Fn::GetAtt` retorna para o atributo. Um tipo primitivo é um tipo de dado básico para valores da propriedade de recurso. Os tipos primitivos válidos são `String`, `Long`, `Integer`, `Double`, `Boolean`, `Timestamp` ou `Json`. `Type` Para valores não primitivos de retorno, o tipo de valor primitivo que a função `Fn::GetAtt` retorna para o atributo. Os tipos válidos são o nome de uma propriedade ou `List`. Uma lista é uma lista de valores separados por vírgula. O tipo de valor para listas é indicado pelo campo `ItemType` ou `PrimitiveItemType`. `Documentation` Um link para o *Guia do usuário do AWS CloudFormation* para obter informações sobre o recurso. `Properties` Uma lista de especificações de propriedade para o recurso. Para obter detalhes, consulte [Especificação de propriedade](#cfn-resource-specification-format-propertytypes). ## Exemplo de especificação de recurso Os exemplos a seguir destacam e explicam partes da especificação do recurso [AWS::Elasticsearch::Domain](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-elasticsearch-domain.html). O tipo de recurso `AWS::Elasticsearch::Domain` contém subpropriedades; dessa forma, a especificação inclui a seção `PropertyTypes`. Essa seção é seguida pela seção `ResourceSpecificationVersion`, que mostra a versão de especificação como `1.0.0`. Após a versão da especificação é a seção `ResourceType` que especifica o tipo de recurso, fornece um link de documentação e detalha as propriedades do recurso. ``` { "PropertyTypes": { ... }, "ResourceSpecificationVersion": "1.0.0", "ResourceType": { "AWS::Elasticsearch::Domain": { "Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-elasticsearch-domain.html", "Properties": { ... } } } } } ``` Com foco na seção `ResourceType`, o exemplo a seguir mostra duas propriedades de tipo do recurso `AWS::Elasticsearch::Domain`. A propriedade `AdvancedOptions` não é obrigatória e aceita um mapa de cadeia de caracteres para cadeia de caracteres. Um mapa é um coleção de pares chave/valor, na qual as chaves são sempre cadeia de caracteres. O tipo de valor é indicado pelo campo `ItemType`, que é `String`. Portanto, o tipo é um mapa de cadeia de caracteres para cadeia de caracteres. O comportamento de atualização dessa propriedade é mutável. Se você atualizar essa propriedade, o CloudFormation manterá o recurso em vez de criar uma nova e, em seguida, excluirá o antigo (uma atualização imutável). A propriedade `SnapshotOptions` não é obrigatória e aceita uma subpropriedade nomeada `SnapshotOptions`. Os detalhes da subpropriedade `SnapshotOptions` são fornecidos na seção `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" }, ... } } } } ``` No `PropertyTypes`, a especificação lista todas as subpropriedades de um recurso (incluindo subpropriedades aninhadas). O exemplo a seguir detalha a subpropriedade `AWS::Elasticsearch::Domain.SnapshotOptions`. Ele contém uma propriedade nomeada `AutomatedSnapshotStartHour`, que não é obrigatória e aceita tipos de valor inteiro. ``` "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" } } }, ... } ``` Para sua referência, o exemplo a seguir fornece toda a especificação do recurso `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" } ```