template.yamlのAWSTemplateFormatVersionとは何か
はじめに
こんにちは、山本 翔大です。
AWS を学んでいて CloudFormation を使う機会が多くなりました。
テンプレートを作る際は AI に聞いたりすでにあるテンプレートを編集して作成するのですが、必ず先頭に存在する AWSTemplateFormatVersion について気になりました。
そこで今回は AWSTemplateFormatVersion について調べたことをまとめていこうと思います。
AWSTemplateFormatVersion とは
公式のドキュメントには以下のように記載されています。
AWSTemplateFormatVersion セクション (オプション) は、テンプレートが準拠するテンプレート形式バージョンを識別します。最新のテンプレートの形式バージョンは 2010-09-09 であり、現時点で唯一の有効な値です。
つまり、AWSTemplateFormatVersion は「このテンプレートは CloudFormation のどの書式ルールに従って書かれているか」を宣言するためのセクションです。
次の 2 つのポイントにまとめられます。
- 省略できる：オプションのセクションなので、書かなくてもテンプレートは動作します。省略した場合、CloudFormation は最新の形式バージョンが指定されたものとして扱います。
- 有効な値は 2010-09-09 の 1 つだけ：形式バージョンは 2010 年 9 月 9 日に定義されたものから一度も更新されていません。
つまり、書いても書かなくても動作は変わらず、書く場合は 2010-09-09 以外の値は使えません。
やってみた
実際に色々なパターンでスタックを作成し動作を試してみます。
セクションを省略
まずは、セクションを省略するパターンです。以下のテンプレートでスタックを作成します。
Description: AWSTemplateFormatVersion hands-on using S3 bucket
Resources:
HandsOnBucket:
Type: AWS::S3::Bucket
Properties:
BucketName: !Sub "cfn-format-version-${AWS::AccountId}-${AWS::StackName}"
Tags:
- Key: Name
Value: cfn-format-version-handson
- Key: Project
Value: format-version-handson
Outputs:
BucketName:
Description: Created S3 bucket name
Value: !Ref HandsOnBucket
このテンプレートを使用して作成するとドキュメント通りエラーはなく作成することができました。
無効な値を指定
次に自分で日付を決めて作成します。
テンプレートは以下のように指定しました。
AWSTemplateFormatVersion: '2026-01-01'
Description: AWSTemplateFormatVersion hands-on using S3 bucket
Resources:
HandsOnBucket:
Type: AWS::S3::Bucket
Properties:
BucketName: !Sub "cfn-format-version-${AWS::AccountId}-${AWS::StackName}"
Tags:
- Key: Name
Value: cfn-format-version-handson
- Key: Project
Value: format-version-handson
Outputs:
BucketName:
Description: Created S3 bucket name
Value: !Ref HandsOnBucket
すると今回は以下のようなエラーが発生しました。
Template format error: 2026-01-01 is not a supported value forAWSTemplateFormatVersion.
その日付のテンプレートはサポートされていません。といった内容になります。
引用符なし
最後におまけで引用符なしでも作成してみます。
AWSTemplateFormatVersion: 2010-09-09
Description: AWSTemplateFormatVersion hands-on using S3 bucket
Resources:
HandsOnBucket:
Type: AWS::S3::Bucket
Properties:
BucketName: !Sub "cfn-format-version-${AWS::AccountId}-${AWS::StackName}"
Tags:
- Key: Name
Value: cfn-format-version-handson
- Key: Project
Value: format-version-handson
Outputs:
BucketName:
Description: Created S3 bucket name
Value: !Ref HandsOnBucket
AWSTemplateFormatVersion: 2026-01-01
Description: AWSTemplateFormatVersion hands-on using S3 bucket
Resources:
HandsOnBucket:
Type: AWS::S3::Bucket
Properties:
BucketName: !Sub "cfn-format-version-${AWS::AccountId}-${AWS::StackName}"
Tags:
- Key: Name
Value: cfn-format-version-handson
- Key: Project
Value: format-version-handson
Outputs:
BucketName:
Description: Created S3 bucket name
Value: !Ref HandsOnBucket
こちらも結果は同じで日付が合っていないもののみエラーが発生しました。
AWSTemplateFormatVersion は書くべきか
ここまでの検証で、AWSTemplateFormatVersion は書いても書かなくても動作が変わらないことがわかりました。
では、実際にテンプレートを書くときは記載するべきなのでしょうか。
CloudFormation は 2011 年の一般公開以降、新しいセクションや組み込み関数など多くの機能が追加されています。
それにもかかわらず、形式バージョンは 2010-09-09 のまま一度も更新されていません。
公式ドキュメントに理由は明記されていませんが、これまでの新機能はいずれも既存のテンプレートをそのまま動かせる形で追加されてきたため、形式バージョンを上げる必要がなかったのだと考えられます。
そのため省略しても問題はありませんが、私は書いておくのがよいと思いました。
公式ドキュメントのサンプルをはじめ、ほとんどのテンプレートには AWSTemplateFormatVersion が記載されているため、書いておくことで他のテンプレートと形式を揃えることができます。
それに加えて、YAML ファイルを開いたときに先頭の 1 行で CloudFormation のテンプレートだと一目でわかるため、複数の YAML ファイルを扱う場面でも中身を読まずに判別しやすくなります。
おわりに
今回は CloudFormation の AWSTemplateFormatVersion について調べてみました。
これまで何となく書いていましたが、省略できることと、有効な値が 2010-09-09 の 1 つだけであることを実際に確認できました。
書いても書かなくても動作は変わりませんが、他のテンプレートとの統一や可読性の面から、私は今後も書いておこうと思います。
同じように気になっていた方の参考になれば幸いです。
参考資料
クラスメソッドオペレーションズ株式会社について
クラスメソッドグループのオペレーション企業です。
運用・保守開発・サポート・情シス・バックオフィスの専門チームが、IT・AIをフル活用した「しくみ」を通じて、お客様の業務代行から課題解決や高付加価値サービスまでを提供するエキスパート集団です。
当社は様々な職種でメンバーを募集しています。
「オペレーション・エクセレンス」と「らしく働く、らしく生きる」を共に実現するカルチャー・しくみ・働き方にご興味がある方は、クラスメソッドオペレーションズ株式会社 コーポレートサイト をぜひご覧ください。※2026年1月 アノテーション㈱から社名変更しました
