Formato de especificação - AWS CloudFormation
Seções de especificaçãoEspecificação de propriedadeEspecificação de recursoExemplo de especificação de recurso

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.

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 é 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 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 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 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çã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.

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