Spezifikationsformat - AWS CloudFormation

Spezifikationsformat

AWS CloudFormation erstellt eine Spezifikation für jeden Ressourcentyp, z. B. AWS::S3::Bucket oder AWS::EC2::Instance. Die folgenden Abschnitte beschreiben das Format und die einzelnen Felder in der Spezifikation.

Spezifikationsabschnitte

Die formale Definition für jeden Ressourcentyp ist in drei Hauptabschnitte unterteilt: PropertyTypesResourceSpecificationVersion und ResourceTypes (siehe folgendes Beispiel):

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

Für Ressourcen, die Eigenschaften innerhalb einer Eigenschaft (auch "Untereigenschaften" genannt) haben: eine Liste der Spezifikationen der Untereigenschaften, z. B. welche Eigenschaften erforderlich sind, der Typ des zulässigen Werts für die einzelnen Eigenschaften und das Aktualisierungsverhalten. Weitere Informationen finden Sie unter Eigenschaftsspezifikation.

Wenn eine Ressource keine Untereigenschaften hat, wird dieser Abschnitt weggelassen.

ResourceSpecificationVersion

Die Version der Ressourcenspezifikation. Das Versionsformat ist majorVersion.minorVersion.patch, wobei bei jeder Version die Versionsnummer erhöht wird. Alle Ressourcen haben die gleiche Versionsnummer, unabhängig davon, ob die Ressource aktualisiert wurde.

AWS CloudFormation erhöht die Patch-Nummer, wenn der Service einen abwärtskompatiblen Bugfix vornimmt, z. B. zum Beheben eines fehlerhaften Dokumentationslinks. Wenn AWS CloudFormation Ressourcen oder Eigenschaften hinzufügt, die abwärts kompatibel sind, erhöht sich die Nebenversionsnummer. Beispielsweise können in einer späteren Spezifikationsversion weitere Ressourceneigenschaften zur Unterstützung neuer Funktionen eines AWS-Service hinzugefügt werden.

Bei abwärts inkrementellen Änderungen erhöht sich die Hauptversionsnummer. Eine abwärts inkompatible Änderung kann aufgrund einer Änderung in der Ressourcenspezifikation vorgenommen werden, z. B. bei einer Änderung eines Feldnamens, oder bei einer Änderung einer Ressource, z. B. wenn eine optionale Ressourceneigenschaft zu einer Pflichteigenschaft wird.

ResourceTypes

Die Liste der Ressourcen und Informationen zu den Eigenschaften der einzelnen Ressourcen, wie z. B. die Eigenschaftsnamen, welche Eigenschaften erforderlich sind und das Aktualisierungsverhalten. Weitere Informationen finden Sie unter Ressourcenspezifikation.

Anmerkung

Wenn Sie eine Datei mit der Definition eines Ressourcentyps anzeigen, lautet der Name der Eigenschaft ResourceType (Singular).

Eigenschaftsspezifikation

Die Spezifikation für die einzelnen Eigenschaften enthält die folgenden Felder. Für Untereigenschaften steht der Eigenschaftsnamen im 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

Ein Link zum AWS CloudFormation Benutzerhandbuch mit Informationen über die Eigenschaft.

DuplicatesAllowed

Wenn der Wert des Type-Feldes List ist, bedeutet dies, dass AWS CloudFormation doppelte Werte zulässt. Wenn der Wert true ist, ignoriert AWS CloudFormation doppelte Werte. Wenn der Wert false lautet, gibt AWS CloudFormation einen Fehler zurück, wenn Sie doppelte Werte absenden.

ItemType

Wenn der Wert des Type-Feldes List oder Map lautet, gibt dies den Listen- oder Zuweisungstyp an, wenn diese nicht primitive Typen enthalten. Andernfalls ist dieses Feld leer. Für Listen oder Zuweisungen mit primitiven Datentypen gibt die PrimitiveItemType-Eigenschaft den gültigen Wert an.

Ein Untereigenschaftsname ist ein gültiger Elementtyp. Wenn der Typwert beispielsweise List und der Elementtypwert PortMapping lautet, können Sie eine Liste der Portzuweisungseigenschaften angeben.

PrimitiveItemType

Wenn der Wert des Type-Feldes List oder Map lautet, gibt dies den Listen- oder Zuweisungstyp an, wenn diese primitive Typen enthalten. Andernfalls ist dieses Feld leer. Für Listen oder Zuweisungen mit nicht primitiven Datentypen gibt die ItemType-Eigenschaft den gültigen Wert an.

Die gültigen primitiven Typen für Listen und Zuweisungen sind StringLong, Integer, Double, Boolean oder Timestamp.

Wenn der Typwert beispielsweise List und der Elementtypwert String lautet, können Sie eine Liste der Zeichenfolgen für die Eigenschaft angeben. Wenn der Typwert beispielsweise Map und der Elementtypwert Boolean lautet, können Sie eine Zeichenfolge für eine Boolsche Zuweisung für die Eigenschaft angeben.

PrimitiveType

Für primitive Werte der gültige primitive Typ der Eigenschaft. Ein primitiver Typ ist ein grundlegender Datentyp für die Eigenschaftswerte von Ressourcen. Die gültigen primitiven Typen sind String, Long, Integer, Double, Boolean, Timestamp oder Json. Wenn gültige Werte ein nicht primitiver Typ sind, wird dieses Feld ausgelassen und im Feld Type wird der gültige Werttyp angegeben.

Required

Gibt an, ob die Eigenschaft erforderlich ist.

Type

Für nicht primitive Typen gültige Werte der Eigenschaft. Die gültigen Typen sind ein Untereigenschaftsname, List oder Map. Wenn gültige Werte ein primitiver Typ sind, wird dieses Feld ausgelassen und im Feld PrimitiveType wird der gültige Werttyp angegeben.

Eine Liste ist eine durch Komma getrennte Liste der Werte. Eine Zuweisung ist eine Gruppe von Schlüssel-Wert-Paaren, wobei die Schlüssel immer Zeichenfolgen sind. Der Werttyp für Listen und Zuweisungen wird durch das Feld ItemType oder PrimitiveItemType festgelegt.

UpdateType

Während eines Stapel-Updates wird das Aktualisierungsverhalten beim Hinzufügen, Entfernen oder Ändern der Eigenschaft angezeigt. AWS CloudFormation ersetzt die Ressource, wenn Sie unveränderliche Eigenschaften ändern. AWS CloudFormation ersetzt die Ressource nicht, wenn Sie veränderliche Eigenschaften ändern. Bedingte Updates können veränderlich oder unveränderlich sein, z. B. je nachdem, welche anderen Eigenschaften aktualisiert wurden. Weitere Informationen finden Sie in der Dokumentation des entsprechenden Ressourcentyps.

Ressourcenspezifikation

Die Spezifikation für die einzelnen Ressourcentypen enthält die folgenden Felder.

"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

Eine Liste der Attribute, die Sie in einer Fn::GetAtt-Funktion verwenden können. Für jedes Attribut werden in diesem Abschnitt der Attributname und der Werttyp angegeben, den AWS CloudFormation zurückgibt.

ItemType

Wenn der Wert des Type-Feldes List lautet, ist dies der Typ der Liste, die die Fn::GetAtt-Funktion für das Attribut zurückgibt, wenn die Liste nicht primitive Datentypen enthält. Der gültige Typ ist ein Name einer Eigenschaft.

PrimitiveItemType

Wenn der Wert des Type-Feldes List lautet, ist dies der Typ der Liste, die die Fn::GetAtt-Funktion für das Attribut zurückgibt, wenn die Liste primitive Datentypen enthält. Für Listen oder Zuweisungen mit nicht primitiven Datentypen gibt die ItemType-Eigenschaft den gültigen Wert an. Die gültigen primitiven Typen für Listen sind StringLong, Integer, Double, Boolean oder Timestamp.

Wenn der Typwert beispielsweise List und der primitive Elementtypwert String lautet, gibt die Fn::GetAtt-Funktion eine Liste mit Zeichenfolgen zurück.

PrimitiveType

Für primitive Rückgabewerte der Typ des primitiven Werts, den die Fn::GetAtt-Funktion für das Attribut zurückgibt. Ein primitiver Typ ist ein grundlegender Datentyp für die Eigenschaftswerte von Ressourcen. Die gültigen primitiven Typen sind String, Long, Integer, Double, Boolean, Timestamp oder Json.

Type

Für nicht primitive Rückgabewerte der Typ des primitiven Werts, den die Fn::GetAtt-Funktion für das Attribut zurückgibt. Die gültigen Typen sind ein Eigenschaftsname oder List.

Eine Liste ist eine durch Komma getrennte Liste der Werte. Der Werttyp für Listen wird durch das Feld ItemType oder PrimitiveItemType festgelegt.

Documentation

Ein Link zum AWS CloudFormation Benutzerhandbuch mit Informationen über die Ressource.

Properties

Eine Liste der Eigenschaftsspezifikationen für die Ressource. Details dazu finden Sie unter Eigenschaftsspezifikation.

Beispiel für eine Ressourcenspezifikation

Die folgenden Beispiele verdeutlichen und erläutern Teile der AWS::Elasticsearch::Domain-Ressourcenspezifikation.

Der AWS::Elasticsearch::Domain-Ressourcentyp enthält Untereigenschaften, sodass die Spezifikation einen Abschnitt PropertyTypes enthält. Diesem Abschnitt folgt der Abschnitt ResourceSpecificationVersion mit der Spezifikationsversion 1.0.0. Nach der Spezifikationsversion folgt der Abschnitt ResourceType, in dem der Ressourcentyp und ein Dokumentationslink sowie Details zu den Ressourceneigenschaften angegeben sind.

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

Das folgende Beispiel zeigt schwerpunktmäßig den Abschnitt ResourceType und zwei Eigenschaften des Ressourcentyps AWS::Elasticsearch::Domain. Die AdvancedOptions-Eigenschaft ist nicht erforderlich und akzeptiert eine Zeichenfolge-zu-Zeichenfolge-Zuweisung. Eine Zuweisung ist eine Sammlung von Schlüssel-Wert-Paaren, wobei die Schlüssel immer Zeichenfolgen sind. Der Werttyp wird durch das Feld ItemType angegeben, das String lautet. Daher ist der Typ eine Zeichenfolge-zu-Zeichenfolge-Zuweisung. Das Aktualisierungsverhalten für diese Eigenschaft ist veränderlich. Wenn diese Eigenschaft aktualisiert wird, behält AWS CloudFormation die Ressource bei, statt eine neue zu erstellen und die alte zu löschen (eine unveränderliche Aktualisierung).

Die SnapshotOptions-Eigenschaft ist nicht erforderlich und akzeptiert eine Untereigenschaft mit dem Namen SnapshotOptions. Details zur Untereigenschaft SnapshotOptions sind im Abschnitt PropertyTypes zu finden.

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

Im PropertyTypes listet die Spezifikation aller Untereigenschaften einer Ressource (einschließlich verschachtelter Untereigenschaften). Das folgende Beispiel zeigt die Details der Untereigenschaft AWS::Elasticsearch::Domain.SnapshotOptions. Es enthält eine einzelne Eigenschaft mit dem Namen AutomatedSnapshotStartHour, die nicht erforderlich ist, und Werte vom Typ Ganzzahl akzeptiert.

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

Zu Ihrer Referenz ist im folgenden Beispiel die gesamte AWS::Elasticsearch::Domain-Ressourcenspezifikation dargestellt.

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