Formato della specifica

CloudFormation crea una specifica per ogni tipo di risorsa, ad esempio AWS::S3::Bucket oAWS::EC2::Instance. Le sezioni seguenti descrivono il formato e i singoli campi della specifica.

Sezioni della specifiche

La definizione formale per ogni tipo di risorsa è organizzata in tre sezioni principali: PropertyTypes, ResourceSpecificationVersion e ResourceTypes, come nell'esempio seguente:

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

PropertyTypes

Per le risorse con proprietà all'interno di un'altra proprietà (note anche come sottoproprietà), è l'elenco delle specifiche sottoproprietà, ad esempio quali proprietà sono necessarie, il tipo di valore consentito per ogni proprietà e il loro comportamento di aggiornamento. Per ulteriori informazioni, consulta Specifiche di proprietà.

Se una risorsa non dispone di sottoproprietà, questa sezione viene omessa.

ResourceSpecificationVersion

La versione della specifica delle risorse. Il formato della versione è majorVersion.minorVersion.patch, dove ogni release incrementa il numero di versione. Tutte le risorse hanno lo stesso numero di versione, indipendentemente dal fatto che la risorsa sia stata aggiornata.

CloudFormation incrementa il numero di patch quando il servizio corregge un bug compatibile con le versioni precedenti, ad esempio corregge un collegamento alla documentazione non funzionante. Quando CloudFormation aggiunge risorse o proprietà retrocompatibili, incrementa il numero della versione secondaria. Ad esempio, le versioni successive di una specifica potrebbero aggiungere proprietà di risorse aggiuntive per supportare nuove funzionalità di un AWS servizio.

Le modifiche non retrocompatibili incrementano il numero di versione principale. Una modifica non retrocompatibile può derivare da una modifica alla specifica delle risorse, ad esempio la modifica del nome di un campo oppure cambiamenti in una risorsa, ad esempio se si rende obbligatoria una proprietà della risorsa prima facoltativa.

ResourceTypes

L'elenco di risorse e le informazioni sulle proprietà di ogni risorsa, come i nomi di proprietà, quali proprietà sono necessarie e il relativo comportamento di aggiornamento. Per ulteriori informazioni, consulta Specifica delle risorse.

Nota

Se visualizzi un file che contiene la definizione di un tipo di risorsa, questo nome di proprietà è ResourceType (singolare).

Specifiche di proprietà

La specifica per ogni proprietà include i campi riportati di seguito. Per le sottoproprietà, il nome della proprietà segue il 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

Link alla Guida per l'utente di AWS CloudFormation che fornisce informazioni sulle proprietà.

DuplicatesAllowed

Se il valore del Type campo èList, indica se sono CloudFormation consentiti valori duplicati. Se il valore ètrue, CloudFormation ignora i valori duplicati. Se il valore èfalse, CloudFormation restituisce un errore se si inviano valori duplicati.

ItemType

Se il valore del campo Type è List o Map, indica il tipo di elenco o mappatura, qualora i tipi contenuti non siano primitivi. In caso contrario, il campo viene omesso. Per elenchi o mappe che contengono tipi primitivi, la proprietà PrimitiveItemType indica il tipo di valore valido.

Un nome di sottoproprietà è un tipo di voce valido. Ad esempio, se il valore di tipo è List e il valore di tipo della voce è PortMapping, puoi specificare un elenco di proprietà di mappatura delle porte.

PrimitiveItemType

Se il valore del campo Type è List o Map, indica il tipo di elenco o mappatura, qualora i tipi contenuti siano primitivi. In caso contrario, il campo viene omesso. Per elenchi o mappe che contengono tipi non primitivi, la proprietà ItemType indica il tipo di valore valido.

I tipi primitivi validi per elenchi e mappe sono String, Long, Integer, Double, Boolean o Timestamp.

Ad esempio, se il valore di tipo è List e il valore di tipo della voce è String, puoi specificare un elenco di stringhe per la proprietà. Se il valore di tipo è Map e il valore di tipo della voce è Boolean, puoi specificare una stringa di mappatura booleana per la proprietà.

PrimitiveType

Per i valori primitivi, il tipo primitivo valido per la proprietà. Un tipo primitivo è un tipo di dati di base per i valori di proprietà delle risorse. I tipi primitivi validi sono String, Long, Integer, Double, Boolean, Timestamp o Json. Se i valori validi sono di tipo non primitivo, questo campo non viene specificato e il campo Type indica il tipo di valore valido.

Required

Indica se la proprietà è obbligatoria.

Type

Per i tipi non primitivi, i valori validi per la proprietà. I tipi validi sono un nome di sottoproprietà, List oppure Map. Se i valori validi sono di tipo primitivo, questo campo non viene specificato e il campo PrimitiveType indica il tipo di valore valido.

Un elenco è un elenco di valori separati da virgola. Una mappatura è un set di coppie chiave-valore, dove le chiavi sono sempre stringhe. Il tipo di valore per elenchi e mappature è indicato dal campo ItemType o PrimitiveItemType.

UpdateType

Durante un aggiornamento dello stack, il comportamento di aggiornamento quando si aggiunge, si rimuove o si modifica la proprietà. CloudFormation sostituisce la risorsa quando si modificano le proprietà immutabili. CloudFormationnon sostituisce la risorsa quando si modificano le proprietà mutabili. Gli aggiornamenti condizionali possono essere del primo o del secondo tipo, in funzione, ad esempio, delle altre proprietà aggiornate. Per ulteriori informazioni, consulta la documentazione pertinente relativa al tipo di risorsa.

Specifica delle risorse

La specifica per tipo di risorsa include i campi riportati di seguito.

"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

Un elenco di attributi di risorse che è possibile utilizzare in una funzione Fn::GetAtt. Per ogni attributo, questa sezione fornisce il nome dell'attributo e il tipo di valore CloudFormation restituito.

ItemType

Se il valore del campo Type è List, indica il tipo di elenco restituito dalla funzione Fn::GetAtt per l'attributo se l'elenco contiene tipi non primitivi. Il tipo valido è il nome di una proprietà.

PrimitiveItemType

Se il valore del campo Type è List, indica il tipo di elenco restituito dalla funzione Fn::GetAtt per l'attributo se l'elenco contiene tipi primitivi. Per elenchi che contengono tipi non primitivi, la proprietà ItemType indica il tipo di valore valido. I tipi primitivi validi per gli elenchi sono String, Long, Integer, Double, Boolean o Timestamp.

Ad esempio, se il valore di tipo è List e il valore di tipo della voce primitiva è String, la funzione Fn::GetAtt restituisce un elenco di stringhe.

PrimitiveType

Per i valori restituiti primitivi, il tipo del valore primitivo che la funzione Fn::GetAtt restituisce per l'attributo. Un tipo primitivo è un tipo di dati di base per i valori di proprietà delle risorse. I tipi primitivi validi sono String, Long, Integer, Double, Boolean, Timestamp o Json.

Type

Per i valori restituiti non primitivi, il tipo del valore che la funzione Fn::GetAtt restituisce per l'attributo. I tipi validi sono il nome di una proprietà oppure List.

Un elenco è un elenco di valori separati da virgola. Il tipo di valore per gli elenchi è indicato dal campo ItemType o PrimitiveItemType.

Documentation

Link alla Guida per l'utente di AWS CloudFormation per informazioni sulla risorsa.

Properties

Un elenco di specifiche delle proprietà per la risorsa. Per informazioni dettagliate, consultare Specifiche di proprietà.

Esempi di specifica delle risorse

I seguenti esempi evidenziano e spiegano parti della specifica delle risorse AWS::Elasticsearch::Domain.

Il tipo di risorsa AWS::Elasticsearch::Domain contiene sottoproprietà, perciò la specifica include una sezione PropertyTypes. Questa sezione è seguita dalla sezione ResourceSpecificationVersion, che evidenzia come la versione della specifica sia la 1.0.0. Dopo la versione della specifica viene la sezione ResourceType, che specifica il tipo di risorsa, fornisce un link alla documentazione e illustra nei dettagli le proprietà della risorsa.

{
  "PropertyTypes": {
    ...

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

        }
      }
    }
  }
}

Focalizzandosi sulla sezione ResourceType, l'esempio seguente mostra due proprietà del tipo di risorsa AWS::Elasticsearch::Domain. La proprietà AdvancedOptions non è obbligatoria e accetta una mappatura da stringa a stringa. Una mappatura è una raccolta di coppie chiave-valore, dove le chiavi sono sempre stringhe. Il tipo di valore è indicato dal campo ItemType, che è String. Pertanto, il tipo è una mappatura da stringa a stringa. Il comportamento di aggiornamento per questa proprietà è modificabile. Se aggiorni questa proprietà, CloudFormation mantiene la risorsa invece di crearne una nuova e poi eliminare quella vecchia (un aggiornamento immutabile).

La proprietà SnapshotOptions non è obbligatoria e accetta una sottoproprietà denominata SnapshotOptions. I dettagli della sottoproprietà SnapshotOptions sono disponibili nella sezione 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"
        },
        ...

      }
    }
  }
}

In PropertyTypes, la specifica elenca tutte le sottoproprietà di una risorsa (incluse le sottoproprietà nidificate). L'esempio seguente illustra nei dettagli la sottoproprietà AWS::Elasticsearch::Domain.SnapshotOptions. Contiene una proprietà denominata AutomatedSnapshotStartHour, che non è obbligatoria e accetta tipi di valori interi.

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

Per riferimento, l'esempio seguente fornisce l'intera specifica della risorsa 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"
}