仕様の形式 - AWS CloudFormation
固有セクションプロパティの仕様リソース仕様リソース仕様の例

仕様の形式

CloudFormation は、AWS::S3::Bucket や AWS::EC2::Instance など、各リソースタイプ用の仕様を作成します。次のセクションで、仕様の形式と各フィールドについて説明します。

固有セクション

各リソースタイプの形式定義は、次の例に示すように、PropertyTypes、ResourceSpecificationVersion、および ResourceTypes という 3 つの主要セクションで構成されています。

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

プロパティ内にプロパティがある (サブプロパティともいいます) リソースの場合の、サブプロパティのリスト。どのプロパティが必須か、各プロパティで許可される値の型、それらの更新動作などです。詳細については、「プロパティの仕様」を参照してください。

リソースにサブプロパティが存在しない場合は、このセクションは省略されます。

ResourceSpecificationVersion

リソース仕様のバージョン。バージョン形式は majorVersion.minorVersion.patch であり、リリースごとにバージョン番号が増加します。リソースが更新されたかどうかにかかわらず、すべてのリソースのバージョン番号は同じです。

CloudFormation では、繋がっていなかったドキュメントリンクの修正など、サービスで後方互換性のあるバグ修正が行われた場合、パッチ番号が増加します。CloudFormation で後方互換性のあるリソースまたはプロパティが追加された場合は、マイナーバージョン番号が増加します。たとえば、仕様のより新しいバージョンによって、AWS のサービスの新機能をサポートするための追加リソースプロパティが追加されることがあります。

後方互換性が変更されるとメジャーバージョン番号が増加します。後方互換性の変更は、フィールドの名前変更などのリソース仕様の変更、またはオプションのリソースプロパティを必須にするなどのリソースへの変更により発生します。

ResourceTypes

リソースと、プロパティ名、どのプロパティが必須か、および更新動作など、各リソースプロパティに関する情報のリストです。詳細については、「リソース仕様」を参照してください。

注記

1 つのリソースタイプの定義を含むファイルを確認すると、このプロパティ名は ResourceType (単数) になっています。

プロパティの仕様

各プロパティの仕様には以下のフィールドが含まれています。サブプロパティでは、プロパティ名には 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

プロパティに関する情報が記載された「AWS CloudFormation ユーザーガイド」へのリンク。

DuplicatesAllowed

Type フィールドの値が List の場合、CloudFormation で重複した値が許可されるかどうかを示します。値が true の場合、CloudFormation は重複した値を無視します。値が false の場合、重複した値が送信されると CloudFormation はエラーを返します。

ItemType

Type フィールドの値が List または Map の場合、リストまたはマップにプリミティブ型以外が含まれていれば、その型を示します。それ以外の場合、このフィールドは省略されます。リストまたはマップにプリミティブ型が含まれる場合は、PrimitiveItemType プロパティに有効な値の型が示されます。

サブプロパティ名は有効な項目の型です。たとえば、型の値が List であり項目型の値が PortMapping である場合、ポートマッピングプロパティのリストを指定できます。

PrimitiveItemType

Type フィールドの値が List または Map の場合、リストまたはマップにプリミティブ型が含まれていれば、その型を示します。それ以外の場合、このフィールドは省略されます。リストまたはマップにプリミティブ型以外が含まれる場合は、ItemType プロパティに有効な値の型が示されます。

リストまたはマップの有効なプリミティブ型は、String、Long、Integer、Double、Boolean、または Timestamp です。

たとえば、型の値が List であり項目型の値が String である場合、プロパティに文字列のリストを指定できます。型の値が Map であり項目型の値が Boolean である場合、プロパティに文字列からブール型のマッピングを指定できます。

PrimitiveType

プリミティブ型の値の場合、プロパティの有効なプリミティブ型。プリミティブ型はリソースプロパティの値の基本的なデータ型です。有効なプリミティブ型は、String、Long、Integer、Double、Boolean、Timestamp または Json です。有効な値がプリミティブ型以外の場合は、このフィールドは省略され、Type フィールドに有効な値の型が表示されます。

Required

プロパティが必須かどうかを示します。

Type

プリミティブ型以外では、プロパティの有効値。有効な型はサブプロパティ名、List または Map です。有効な値がプリミティブ型の場合は、このフィールドは省略され、PrimitiveType フィールドに有効な値の型が表示されます。

リストは、コンマ区切りの値の一覧です。マップは、キーが常に文字列である一連のキーと値のペアです。リストおよびマップの値の型は、ItemType または PrimitiveItemType フィールドで示されます。

UpdateType

スタックの更新中に、プロパティを追加、削除、または変更したときの更新動作。変更不可能なプロパティを変更すると、CloudFormation はリソースを置き換えます。変更可能なプロパティを変更すると、CloudFormation はリソースを置き換えません。条件付き更新は、たとえば更新した他のプロパティによって、ミュータブルまたはイミュータブルになります。詳細については、関連するリソースタイプのドキュメントを参照してください。

リソース仕様

各リソースタイプの仕様には次のフィールドが含まれています。

"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

Fn::GetAtt 関数で使用できるリソース属性の一覧。このセクションでは、各属性について、属性名と CloudFormation から返される値の型を説明します。

ItemType

Type フィールドの値が List の場合、リストにプリミティブ型以外が含まれていれば、Fn::GetAtt 関数によって属性に返されるリストの型が示されます。有効な型はプロパティ名です。

PrimitiveItemType

Type フィールドの値が List の場合、リストにプリミティブ型が含まれていれば、Fn::GetAtt 関数によって属性に返されるリストの型が示されます。リストにプリミティブ型以外が含まれる場合は、ItemType プロパティに有効な値の型が示されます。リストの有効なプリミティブ型は、String、Long、Integer、Double、Boolean、または Timestamp です。

たとえば、型の値が List でありプリミティブ項目型の値が String である場合、Fn::GetAtt 関数によって文字列のリストが返されます。

PrimitiveType

プリミティブ型の戻り値の場合、Fn::GetAtt 関数によって属性に返されるプリミティブ値の型。プリミティブ型はリソースプロパティの値の基本的なデータ型です。有効なプリミティブ型は、String、Long、Integer、Double、Boolean、Timestamp または Json です。

Type

プリミティブ型以外の戻り値の場合、Fn::GetAtt 関数によって属性に返される値の型。有効な型はプロパティ名または List です。

リストは、コンマ区切りの値の一覧です。リストの値の型は、ItemType または PrimitiveItemType フィールドで示されます。

Documentation

リソースに関する情報が記載された「AWS CloudFormation ユーザーガイド」へのリンク。

Properties

リソースのプロパティ仕様のリスト。詳細については、「プロパティの仕様」を参照してください。

リソース仕様の例

次の例では、AWS::Elasticsearch::Domain リソース仕様の一部を取り上げて説明します。

AWS::Elasticsearch::Domain リソースタイプにはサブプロパティが含まれているため、仕様に PropertyTypes セクションが含まれます。このセクションに、仕様バージョンを ResourceSpecificationVersion と示す 1.0.0 セクションが続きます。仕様のバージョンの後は、リソースタイプを指定する ResourceType セクションであり、ドキュメントのリンクとリソースのプロパティの詳細が示されます。

{
  "PropertyTypes": {
    ...

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

        }
      }
    }
  }
}

ResourceType セクションに焦点を当てた次の例では、AWS::Elasticsearch::Domain リソースタイプの 2 つのプロパティが示されています。AdvancedOptions プロパティは必須ではなく、文字列間マップを使用します。マップは、キーが常に文字列であるキーと値のペアの集合です。値型は ItemType フィールドで示されます。String になります。したがって、型は文字列間マップです。このプロパティの更新動作はミュータブルです。このプロパティを更新すると、CloudFormation は新しいリソースを作成する代わりにこのリソースを保持して、古いものを削除します (イミュータブル更新)。

SnapshotOptions プロパティは必須ではなく、SnapshotOptions という名前のサブプロパティを使用します。SnapshotOptions サブプロパティの詳細は、「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"
        },
        ...

      }
    }
  }
}

PropertyTypes では、仕様内容はリソースのサブプロパティがすべて一覧表示します (ネストされたサブプロパティ含む)。次の例では、AWS::Elasticsearch::Domain.SnapshotOptions サブプロパティについて説明します。これには AutomatedSnapshotStartHour という名前のプロパティが 1 つ含まれますが必須ではなく、整数値タイプを使用します。

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

参考のために、次の例で 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"
}