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.
Tópicos
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 ter mais informações, consulte Especificação de propriedade.
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 é
, 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.majorVersion
.minorVersion
.patch
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 ter mais informações, consulte Especificação de recurso.
nota
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
sejaList
, isso indica se o CloudFormation permite valores duplicados. Se o valor fortrue
, o CloudFormation ignorará valores duplicados. Se o valor forfalse
, o CloudFormation retornará um erro se você enviar valores duplicados. ItemType
-
Se o valor do
Type
campo éList
ouMap
, 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 propriedadePrimitiveItemType
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
ouMap
, 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 propriedadeItemType
indica o tipo de valor válido.Os tipos primitivos válidos para listas e mapas são
String
,Long
,Integer
,Double
,Boolean
ouTimestamp
.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
ouJson
. Se os valores válidos são um tipo não primitivo, esse campo é omitido e o campoType
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
ouMap
. Se os valores válidos são um tipo primitivo, esse campo é omitido e o campoPrimitiveType
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
ouPrimitiveItemType
. 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 a documentação relevante tipo de recurso.
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. 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çãoFn::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çãoFn::GetAtt
retorna para o atributo se a lista contém tipos primitivos. Para listas que contêm tipos não primitivos, a propriedadeItemType
indica o tipo de valor válido. Os tipos primitivos válidos para listas sãoString
,Long
,Integer
,Double
,Boolean
ouTimestamp
.Por exemplo, se o tipo de valor é
List
e o valor de tipo do item primitivo éString
, a funçãoFn::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ãoString
,Long
,Integer
,Double
,Boolean
,Timestamp
ouJson
. 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 ouList
.Uma lista é uma lista de valores separados por vírgula. O tipo de valor para listas é indicado pelo campo
ItemType
ouPrimitiveItemType
.
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.
Exemplo de especificação de recurso
Os exemplos a seguir destacam e explicam partes da especificação do recurso AWS::Elasticsearch::Domain
.
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"
}