Format de la spécification - AWS CloudFormation
Sections de spécificationSpécification de la propriétéSpécification de ressourceExemple de spécification de ressource

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Format de la spécification

CloudFormation crée une spécification pour chaque type de ressource, telle que AWS::S3::Bucket ouAWS::EC2::Instance. Les sections suivantes décrivent le format et chaque domaine au sein de la spécification.

Sections de spécification

La définition formelle pour chaque type de ressource s'organise en trois sections principales : PropertyTypes, ResourceSpecificationVersion, et ResourceTypes, comme l'illustre l'exemple suivant :

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

Pour les ressources qui disposent de propriétés au sein d'une propriété (que l'on appelle aussi sous-propriétés) : une liste des spécifications des sous-propriétés (par exemple, quelles sont les propriétés obligatoires), le type de valeur autorisée pour chaque propriété et leur comportement de mise à jour. Pour plus d’informations, consultez Spécification de la propriété.

Si une ressource ne dispose pas de sous-propriétés, cette section est omise.

ResourceSpecificationVersion

Version de la spécification de ressource. Le format de la version est majorVersion.minorVersion.patch, où chaque publication fait augmenter le numéro de la version. Toutes les ressources ont le même numéro de version, indépendamment de la mise à jour de la ressource.

CloudFormation augmente le numéro de correctif lorsque le service corrige un bogue rétrocompatible, par exemple en corrigeant un lien de documentation rompu. Lorsque CloudFormation des ressources ou des propriétés rétrocompatibles sont ajoutées, le numéro de version secondaire est incrémenté. Par exemple, les versions ultérieures d'une spécification peuvent ajouter des propriétés de ressources supplémentaires pour prendre en charge les nouvelles fonctionnalités d'un AWS service.

Les modifications qui ne sont pas rétrocompatibles augmentent le numéro de la version majeure. Une modification non rétrocompatible peut se produire suite à un changement dans la spécification d'une ressource, comme la rectification du nom d'un champ ou une modification apportée à une ressource, telle que le passage d'une propriété de ressource facultative en option obligatoire.

ResourceTypes

Liste de ressources et informations sur les propriétés de chaque ressource, telles que les noms de ses propriétés, les propriétés requises et leur comportement de mise à jour. Pour plus d’informations, consultez Spécification de ressource.

Note

Si vous consultez un fichier qui contient la définition d'un type de ressource, ce nom de propriété est ResourceType (singulier).

Spécification de la propriété

La spécification de chaque propriété comprend les champs suivants. Pour les sous-propriétés, le nom de la propriété utilise le format 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

Lien vers le Guide de l'utilisateur AWS CloudFormation qui fournit des informations sur la propriété.

DuplicatesAllowed

Si la valeur du Type champ estList, indique si les valeurs CloudFormation dupliquées sont autorisées. Si la valeur esttrue, CloudFormation ignore les valeurs dupliquées. Si la valeur estfalse, CloudFormation renvoie une erreur si vous soumettez des valeurs dupliquées.

ItemType

Si la valeur du champ Type est List ou Map, il indique le type de liste ou de carte en cas de types non primitifs. Sinon, ce champ est omis. Pour des listes ou des cartes qui contiennent des types primitifs, la propriété PrimitiveItemType indique le type de valeur valide.

Un nom de sous-propriété est un type d'élément valide. Par exemple, si la valeur du type est List et la valeur du type d'élément est PortMapping, vous pouvez spécifier une liste des propriétés de mappage des ports.

PrimitiveItemType

Si la valeur du champ Type est List ou Map, il indique le type de liste ou de carte en cas de types primitifs. Sinon, ce champ est omis. Pour des listes ou des cartes qui contiennent des types non primitifs, la propriété ItemType indique le type de valeur valide.

Les types primitifs valides pour les listes et les cartes sont String, Long, Integer, Double, Boolean ou Timestamp.

Par exemple, si la valeur du type est List et la valeur du type d'élément est String, vous pouvez spécifier une liste de chaînes pour la propriété. Si la valeur de type est Map et la valeur du type d'élément est Boolean, vous pouvez spécifier une chaîne de mappage booléen pour la propriété.

PrimitiveType

Pour les valeurs primitives, c'est le type primitif valide pour la propriété. Un type primitif est un type de données basique pour les valeurs des propriétés de ressource. Les types primitifs valides sont String, Long, Integer, Double, Boolean, Timestamp ou Json. Si les valeurs valides sont de type non primitif, ce champ est omis et le champ Type indique le type de valeur valide.

Required

Indique si la propriété est obligatoire.

Type

Pour les types non primitifs, il s'agit des valeurs valides pour la propriété. Les types valides sont un nom de sous-propriété, List ou Map. Si les valeurs valides sont de type primitif, ce champ est omis et le champ PrimitiveType indique le type de valeur valide.

Une liste est une liste de valeurs séparées par des virgules. Une carte est un jeu de paires clé-valeur, où les clés sont toujours des chaînes. Le type de valeur pour les listes et les cartes est indiqué par le champ ItemType ou PrimitiveItemType.

UpdateType

Lors d'une mise à jour de la pile, le comportement de mise à jour lorsque vous ajoutez, supprimez ou modifiez la propriété. CloudFormation remplace la ressource lorsque vous modifiez des propriétés immuables. CloudFormationne remplace pas la ressource lorsque vous modifiez les propriétés mutables. Les mises à jour conditionnelles peuvent être réversibles ou immuables, en fonction, par exemple, des autres propriétés mises à jour. Pour plus d'informations, consultez la documentation du type de ressource concerné.

Spécification de ressource

La spécification pour chaque type de ressource comprend les champs suivants.

"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

Liste des attributs de ressource que vous pouvez utiliser dans une fonction Fn::GetAtt. Pour chaque attribut, cette section fournit le nom de l'attribut et le type de valeur CloudFormation renvoyé.

ItemType

Si la valeur du champ Type est List, il indique le type de liste que la fonction Fn::GetAtt renvoie pour l'attribut si la liste contient des types non primitifs. Le type valide est un nom de propriété.

PrimitiveItemType

Si la valeur du champ Type est List, il indique le type de liste que la fonction Fn::GetAtt renvoie pour l'attribut si la liste contient des types primitifs. Pour des listes qui contiennent des types non primitifs, la propriété ItemType indique le type de valeur valide. Les types primitifs valides pour les listes sont String, Long, Integer, Double, Boolean, ou Timestamp.

Par exemple, si la valeur du type est List et la valeur du type d'élément primitif est String, la fonction Fn::GetAtt renvoie une liste de chaînes.

PrimitiveType

Pour les valeurs de retour primitives, il s'agit du type de valeur primitive que la fonction Fn::GetAtt renvoie pour l'attribut. Un type primitif est un type de données basique pour les valeurs des propriétés de ressource. Les types primitifs valides sont String, Long, Integer, Double, Boolean, Timestamp ou Json.

Type

Pour les valeurs de retour non primitives, il s'agit du type de valeur primitive que la fonction Fn::GetAtt renvoie pour l'attribut. Les types valides sont un nom de propriété ou List.

Une liste est une liste de valeurs séparées par des virgules. Le type de valeur pour les listes sont indiqués par le champ ItemType ou PrimitiveItemType.

Documentation

Lien vers le Guide de l'utilisateur AWS CloudFormation qui fournit des informations sur la ressource.

Properties

Liste des spécifications de propriété pour la ressource. Pour plus de détails, consultez Spécification de la propriété.

Exemple de spécification de ressource

Les exemples suivants soulignent et expliquent certaines parties de la spécification de ressource AWS::Elasticsearch::Domain.

Le type de ressource AWS::Elasticsearch::Domain contient des sous-propriétés, donc les spécifications comprennent une section PropertyTypes. Cette section est suivie par la section ResourceSpecificationVersion, qui affiche la version de la spécification en tant que 1.0.0. Après la version de spécification se trouve la section ResourceType qui spécifie le type de ressource, fournit un lien vers la documentation et détaille les propriétés de la ressource.

{
  "PropertyTypes": {
    ...

  },
  "ResourceSpecificationVersion": "1.0.0",
  "ResourceType": {
    "AWS::Elasticsearch::Domain": {
      "Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-elasticsearch-domain.html",
      "Properties": {
        ...

        }
      }
    }
  }
}

Pour illustrer la section ResourceType, l'exemple suivant montre deux propriétés du type de ressource AWS::Elasticsearch::Domain. La propriété AdvancedOptions n'est pas obligatoire et elle accepte un mappage chaîne/chaîne. Une carte est un ensemble de paires clé-valeur, où les clés sont toujours des chaînes. Le type de valeur est indiqué par le champ ItemType, qui est String. Par conséquent, le type est un mappage chaîne/chaîne. Le comportement de mise à jour pour cette propriété est réversible. Si vous mettez à jour cette propriété CloudFormation , vous conservez la ressource au lieu d'en créer une nouvelle puis de supprimer l'ancienne (mise à jour immuable).

La propriété SnapshotOptions n'est pas obligatoire et elle accepte une sous-propriété nommée SnapshotOptions. Des détails sur la sous-propriété SnapshotOptions sont disponibles dans la section 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"
        },
        ...

      }
    }
  }
}

Dans les PropertyTypes, les spécifications répertorient toutes les sous-propriétés d'une ressource (y compris les sous-propriétés imbriquées). L'exemple suivant détaille la sous-propriété AWS::Elasticsearch::Domain.SnapshotOptions. Il contient une propriété nommée AutomatedSnapshotStartHour qui n'est pas obligatoire et accepte les types de valeur entières.

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

A titre de référence, l'exemple suivant fournit l'intégralité de la spécification de ressource 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"
}