Formato de especificación

AWS CloudFormation crea una especificación para cada tipo de recurso, como, por ejemplo, AWS::S3::Bucket o AWS::EC2::Instance. En las secciones siguientes se describe el formato y cada campo dentro de la especificación.

Secciones de la especificación

La definición formal para cada tipo de recurso se organiza en tres secciones principales: PropertyTypes, ResourceSpecificationVersion y ResourceTypes, tal y como se muestra en el siguiente ejemplo:

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

PropertyTypes

Para recursos que tengan propiedades dentro de una propiedad (también conocido como subpropiedades), una lista de especificaciones de las subpropiedades, como, por ejemplo, que propiedades son necesarias, el tipo de valor permitido para cada propiedad y su comportamiento de actualización. Para obtener más información, consulte Especificación de propiedad.

Si un recurso no tiene subproperties, se omite esta sección.

ResourceSpecificationVersion

La versión de la especificación de recursos. El formato de la versión es majorVersion.minorVersion.patch, donde cada versión aumenta el número de versión. Todos los recursos que tienen el mismo número de versión independientemente de si el recurso se ha actualizado o no.

AWS CloudFormation incrementa el número de parche cuando el servicio corrige un error compatible con versiones anteriores, como arreglar un enlace de documentación roto. Cuando AWS CloudFormation añade recursos o propiedades que son compatible con versiones anteriores, incrementa el número de versión secundaria. Por ejemplo, las versiones posteriores de una especificación pueden agregar las propiedades de recursos adicionales para admitir nuevas características de un servicio de AWS.

Los cambios incompatibles con versiones anteriores incrementa el número de versión principal. Un cambio incompatible con versiones anteriores pueden ser el resultado de un cambio en la especificación de los recursos, como un cambio de nombre en un campo, o un cambio en un recurso, como hacer que una propiedad de recurso opcional sea obligatoria.

ResourceTypes

La lista de recursos y la información sobre las propiedades de cada uno de los recursos, como, por ejemplo, los nombres de propiedad de sus propiedades, qué propiedades son necesarias y su comportamiento de actualización. Para obtener más información, consulte Especificación de recursos.

nota

Si ve un archivo que contiene la definición de un tipo de recurso, el nombre de esta propiedad es ResourceType (singular).

Especificación de propiedad

La especificación para cada propiedad incluye los siguientes campos. Para subpropiedades, el nombre de la propiedad utiliza el 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

Un enlace a la Guía del usuario de AWS CloudFormation que proporciona información sobre la propiedad.

DuplicatesAllowed

Si el valor del campo Type es List, indica si AWS CloudFormation permite valores duplicados. Si el valor es true, AWS CloudFormation pasa por alto los valores duplicados. Si el valor es false, AWS CloudFormation devuelve un error si envía valores duplicados.

ItemType

Si el valor del campo Type es List o Map, indica el tipo de lista o mapa si contienen tipos no primitivos. De lo contrario, se omite este campo. Para listas o asignaciones que contienen tipos primitivos, la propiedad PrimitiveItemType indica el tipo de valor válido.

Un nombre de subpropiedad es un tipo de elemento válido. Por ejemplo, si el valor del tipo es List y el valor del tipo de elemento es PortMapping, puede especificar una lista de propiedades de mapeo de puertos.

PrimitiveItemType

Si el valor del campo Type es List o Map, indica el tipo de lista o asignación si contienen tipos primitivos. De lo contrario, se omite este campo. Para listas o asignaciones que contienen tipos no primitivos, la propiedad ItemType indica el tipo de valor válido.

Los tipos primitivos válidos para listas y asignaciones son String, Long, Integer, Double, Boolean o Timestamp.

Por ejemplo, si el valor del tipo es List y el valor del tipo de elemento es String, puede especificar una lista de cadenas para la propiedad. Si el valor del tipo es Map y el valor del tipo de elemento es Boolean, puede especificar una cadena para el mapeo booleano para la propiedad.

PrimitiveType

En el caso de valores primitivos, el tipo primitivo válido para la propiedad. Un tipo primitivo es un tipo de datos básico para valores de propiedades de recursos. Los tipos primitivos válidos son String, Long, Integer, Double, Boolean, Timestamp o Json. Si los valores válidos son de tipo no primitivo, este campo se omite y el campo Type indica el tipo de valor válido.

Required

Indica si la propiedad es necesaria.

Type

En el caso de tipos no primitivos, valores válidos para la propiedad. Los tipos válidos son un nombre de subpropiedad, List o Map. Si los valores válidos son de tipo primitivo, este campo se omite y el campo PrimitiveType indica el tipo de valor válido.

Una lista es una lista de valores separados por comas. Una asignación es un conjunto de pares clave-valor, donde las claves son siempre cadenas. El tipo de valor para listas y asignaciones se indica mediante el campo ItemType o PrimitiveItemType.

UpdateType

Durante una actualización de pila, el comportamiento de actualización cuando añade, elimina o modifica la propiedad. AWS CloudFormation sustituye el recurso cuando cambia las propiedades inmutables. AWS CloudFormation no sustituye el recurso cuando cambia las propiedades mutables. Las actualizaciones condicionales pueden ser mutables o inmutables, en función de, por ejemplo, qué otras propiedades actualizó. Para obtener más información, consulte la documentación de tipo de recurso relevante.

Especificación de recursos

La especificación para cada tipo de recurso incluye los siguientes campos.

"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

Una lista de atributos de recursos que puede utilizar en una función Fn::GetAtt. Para cada atributo, esta sección proporciona el nombre de atributo y el tipo de valor que AWS CloudFormation devuelve.

ItemType

Si el valor del campo Type es List, indica el tipo de lista que devuelve la función Fn::GetAtt para el atributo si la lista contiene tipos no primitivos. El tipo válido es un nombre de una propiedad.

PrimitiveItemType

Si el valor del campo Type es List, indica el tipo de lista que devuelve la función Fn::GetAtt para el atributo si la lista contiene tipos primitivos. Para listas que contienen tipos no primitivos, la propiedad ItemType indica el tipo de valor válido. Los tipos primitivos válidos para listas son String, Long, Integer, Double, Boolean o Timestamp.

Por ejemplo, si el valor del tipo es List y el valor del tipo de elemento primitivo es String, la función Fn::GetAtt devuelve una lista de cadenas.

PrimitiveType

Para valores devueltos primitivos, el tipo de valor que la función Fn::GetAtt devuelve para el atributo. Un tipo primitivo es un tipo de datos básico para valores de propiedades de recursos. Los tipos primitivos válidos son String, Long, Integer, Double, Boolean, Timestamp o Json.

Type

Para valores devueltos no primitivos, el tipo de valor que la función Fn::GetAtt devuelve para el atributo. Los tipos válidos son un nombre propiedad o List.

Una lista es una lista de valores separados por comas. El tipo de valor para listas se indica mediante el campo ItemType o PrimitiveItemType.

Documentation

Un enlace a la Guía del usuario de AWS CloudFormation que proporciona información sobre el recurso.

Properties

Una lista de especificaciones de la propiedad para el recurso. Para obtener más información, consulte Especificación de propiedad.

Especificación de recursos de ejemplo

Los siguientes ejemplos resaltan y explican partes de la especificación de recursos AWS::Elasticsearch::Domain.

El tipo de recurso AWS::Elasticsearch::Domain contiene subpropiedades, por lo que la especificación incluye una sección PropertyTypes. A esta sección le sigue la sección ResourceSpecificationVersion, que muestra la versión de la especificación como 1.0.0. Después de la versión de la especificación está la sección ResourceType que especifica el tipo de recurso, ofrece un enlace a la documentación y los detalles de las propiedades de los recursos.

{
  "PropertyTypes": {
    ...

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

        }
      }
    }
  }
}

Centrándonos ahora en la sección ResourceType, el siguiente ejemplo muestra dos propiedades del tipo de recurso AWS::Elasticsearch::Domain. La propiedad AdvancedOptions no es necesaria y acepta una asignación de cadena a cadena. Una asignación es un conjunto de pares clave-valor, donde las claves son siempre cadenas. El tipo de valor se indica mediante el campo ItemType, que es String. Por lo tanto, el tipo es una asignación de cadena a cadena. El comportamiento de actualización de esta propiedad es mutable. Si actualiza esta propiedad, AWS CloudFormation mantiene el recurso en lugar de crear uno nuevo y, a continuación, elimina el antiguo (una actualización inmutable).

La propiedad SnapshotOptions no es necesaria y acepta una subpropiedad denominada SnapshotOptions. Se proporcionan detalles de la subpropiedad SnapshotOptions en la sección 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"
        },
        ...

      }
    }
  }
}

En PropertyTypes, la especificación enumera todas las subpropiedades de un recurso (incluidas las subpropiedades anidadas). El siguiente ejemplo proporciona detalles de la subpropiedad AWS::Elasticsearch::Domain.SnapshotOptions. Contiene una propiedad denominada AutomatedSnapshotStartHour, que no es necesaria y acepta tipos de valores enteros.

"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 su referencia, el siguiente ejemplo proporciona la especificación del recurso AWS::Elasticsearch::Domain completa.

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