【IaC超入門】30日でAWS CloudFormationとTerraformをマスターするロードマップ - 5日目： CloudFormationテンプレートの書き方：YAMLとJSON

CloudFormationテンプレートの書き方：YAMLとJSON

はじめに

CloudFormationの基本概念を理解したところで、いよいよテンプレートの書き方に入ります。CloudFormationのテンプレートは、YAMLまたはJSONのいずれかの形式で記述します。今回は、それぞれの特徴と、なぜ多くのエンジニアがYAMLを選ぶのかについて解説します。

1. YAMLとJSONの基本

両者はデータ記述言語ですが、書き方や用途に違いがあります。

JSON（JavaScript Object Notation）

JSONはJavaScriptから派生した形式で、非常に厳格なルールを持っています。すべてのキーと値はダブルクォーテーションで囲み、カンマで区切る必要があります。

JSONで記述したテンプレートの例

以下は、S3バケット（リソース）を作成するテンプレートの例です：

{
  "AWSTemplateFormatVersion": "2010-09-09",
  "Description": "Simple S3 Bucket Template",
  "Resources": {
    "MyS3Bucket": {
      "Type": "AWS::S3::Bucket",
      "Properties": {
        "BucketName": "my-cloudformation-bucket-example",
        "VersioningConfiguration": {
          "Status": "Enabled"
        }
      }
    }
  },
  "Outputs": {
    "BucketName": {
      "Description": "Name of the S3 bucket",
      "Value": {
        "Ref": "MyS3Bucket"
      }
    }
  }
}

このテンプレートをデプロイすると、1つのスタックが作成され、その中にMyS3Bucketというリソースが含まれます。

JSONはコンピューターが読みやすく、多くのプログラミング言語で広くサポートされています。

YAML（YAML Ain't Markup Language）

YAMLは「人間が読みやすい」ことを重視して設計された形式です。ダブルクォーテーションやカンマを省略でき、インデント（字下げ）で階層構造を表現します。

YAMLで記述したテンプレートの例

同じS3バケットリソースをYAML形式で記述すると以下のようになります：

AWSTemplateFormatVersion: "2010-09-09"
Description: "Simple S3 Bucket Template"

Resources:
  MyS3Bucket:  # これがリソースの論理ID
    Type: AWS::S3::Bucket
    Properties:
      BucketName: !Sub "my-cloudformation-bucket-${AWS::AccountId}"
      VersioningConfiguration:
        Status: Enabled

Outputs:
  BucketName:
    Description: "Name of the S3 bucket"
    Value: !Ref MyS3Bucket

YAMLの方がより簡潔で読みやすいことがわかります。このテンプレートから作成されるスタックも、JSONの例と同じ構成になります。

YAMLは簡潔な構文のため、テンプレートのコード量を減らし、可読性を高めることができます。

2. なぜYAMLが選ばれるのか？

CloudFormationのテンプレートを作成する際、多くのエンジニアがYAMLを選択します。その理由は主に以下の通りです。

可読性の高さと簡潔な構文

JSONに比べて、YAMLはコードがすっきりと見えます。カンマや括弧が多用されるJSONは、テンプレートが大規模になると非常に読みにくくなります。一方、YAMLはインデントとシンプルな記法で構造が明確になり、レビューやメンテナンスが容易です。

コメントの記述が可能

YAMLはテンプレート内にコメントを記述できます。インフラのコードは、なぜその設定にしたのか、誰が変更したのかといった情報を残しておくことが重要です。JSONではコメントを書くことができません。

YAMLでのコメント例

# このテンプレートはS3バケットを作成します
Resources:
  MyS3Bucket:  # S3バケットリソースの定義
    Type: AWS::S3::Bucket
    Properties:
      # S3バケット名をユニークにするための設定
      # AWS::AccountIdを使用してアカウント固有の名前を生成
      BucketName: !Sub "my-cloudformation-bucket-${AWS::AccountId}"
      
      # バージョニングを有効化（データ保護のため）
      VersioningConfiguration:
        Status: Enabled
      
      # パブリックアクセスをブロック（セキュリティ強化）
      PublicAccessBlockConfiguration:
        BlockPublicAcls: true
        BlockPublicPolicy: true
        IgnorePublicAcls: true
        RestrictPublicBuckets: true

# このスタックからS3バケット名を出力します
Outputs:
  BucketName:
    Description: "作成されたS3バケットの名前"
    Value: !Ref MyS3Bucket

コメントがあることで、このテンプレートから作成されるスタックの目的や、各リソースの設定理由が明確になります。

コメントは、チームメンバーや将来の自分がコードを理解する上で非常に役立ちます。

CloudFormation組み込み関数の書きやすさ

YAMLでは、CloudFormationの組み込み関数を短縮形で書くことができ、より読みやすくなります。

組み込み関数の比較例

# YAML形式（短縮形が使用可能）
BucketName: !Sub "my-bucket-${AWS::AccountId}-${AWS::Region}"
SecurityGroups: 
  - !Ref MySecurityGroup

// JSON形式（完全な関数名が必要）
{
  "BucketName": {
    "Fn::Sub": "my-bucket-${AWS::AccountId}-${AWS::Region}"
  },
  "SecurityGroups": [
    {
      "Ref": "MySecurityGroup"
    }
  ]
}

3. CloudFormationでのYAMLとJSONの使い分け

AWS CloudFormationは、どちらの形式のテンプレートもサポートしています。テンプレートの選択は、そこから作成されるスタックの運用方法にも影響します。

• 新規作成: 特別な理由がない限り、YAMLでの作成を推奨します。可読性やメンテナンス性の高さは、長期的なプロジェクトにおいて大きなメリットになります。
• 既存テンプレートの編集: 既存のテンプレートがJSONで書かれている場合は、その形式に合わせて編集するか、必要に応じてYAMLに変換することを検討します。
• 自動生成: プログラムで自動生成する場合は、JSONの方が扱いやすい場合があります。

テンプレート、リソース、スタックの関係性

重要なのは、テンプレート形式がYAMLかJSONかに関わらず、作成されるスタック内のリソースは同じだということです。形式の違いは、あくまで開発者の記述やメンテナンスの効率性に影響するものです。

4. 実際の開発での注意点

YAMLの注意事項

• インデントの統一: スペースとタブの混在は避け、一般的には2スペースまたは4スペースで統一します
• 引用符の使い分け: 特殊文字を含む場合や組み込み関数を使用する場合は適切に引用符を使用します
• リスト表記: ハイフン（-）を使用したリスト表記に慣れる必要があります

開発環境での支援

現代の多くのエディターやIDEは、CloudFormationテンプレートの構文ハイライトや自動補完をサポートしています。Visual Studio CodeのAWS Toolkitなどを活用することで、より効率的にテンプレートを作成できます。

まとめ

項目	YAML	JSON
読みやすさ	高い	低い
構文	簡潔（インデントベース）	厳格（{}、[]、,）
コメント	記述可能	記述不可
ファイルサイズ	小さい	大きい
組み込み関数	短縮形使用可能	完全な関数名が必要
推奨シーン	ほとんどのCloudFormationテンプレート作成	プログラムでの自動生成、厳格な構文が求められる場面

CloudFormationのテンプレートは、人間が読み書きしやすいYAMLで記述するのが一般的です。今日からテンプレートを記述する際は、YAML形式で試してみましょう。

次回は、いよいよCloudFormationテンプレートを使ってAWSにS3バケットをデプロイする手順を、ハンズオン形式で解説します。お楽しみに！