CloudFormationテンプレートをLinterやグラフ表示を用いて快適に書ける環境を構築する

はじめに

今回はCloudFormationテンプレートを快適に書く環境について記載します
CloudFormationはAWSのインフラストラクチャをコードとしてテンプレートに定義し、テンプレートからAWSリソースを自動的にプロビジョニングおよび管理するためのサービスであり
そのCloudFormationテンプレートは頑張ればメモ帳でも書くことはできますが
VSCodeの拡張機能「CloudFormation Linter」を使って快適にテンプレートを書いていける環境をDockerを用いて構築していこうと思います

Windows上に直接Pythonを導入しても良い方はDocker無くとも動かせますが、あまりWindows環境を汚したくないのでDockerを使った方法で記載します

実現できること

• 論理IDにカーソルを合わせるとTypeからAWSのテンプレートリファレンスへのリンクが出る(わりと推しポイント)
  
• プロパティのtypoや指定ミスを指摘してくれる
  
• プロパティの補完機能
  
• 論理IDの補完機能
  
• テンプレート内に記載のリソースの依存関係をグラフ表示する
  
• 末尾のスペース除去やインデントの統一(Editorconfigの機能)

前提

• VSCode導入済み
• Dockerが動く環境(筆者はWSL Ubuntu24.04上で作業してます)

構築手順

まずは環境用のディレクトリを用意します

mkdir example-cfn-lint
cd example-cfn-lint

Dockerファイル作成

作成したディレクトリに以下のDockerfileを配置します
VSCodeに導入する拡張機能「CloudFormation Linter」は動作にPython環境が必要なため
Pythonコンテナにて作業ディレクトリを作成し、必要パッケージをインストールする定義となります

FROM python:3.12.5-alpine3.20

RUN mkdir /workspace
WORKDIR /workspace

COPY requirements.txt /workspace/requirements.txt
RUN pip install -r requirements.txt

必要パッケージ定義

Linterの動作およびグラフ表示にはPython環境の他Pythonパッケージが必要です
Dockerfileと同階層にrequirements.txtファイルを作成し、以下を記載します

cfn-lint==0.87.7
pydot==3.0.1

(バージョンはその時の最新を指定してもらえればと思います)

Dockerビルド・立ち上げ

以下コマンドでCloudFormationテンプレート用のPythonコンテナのビルドを行います
ビルド時するとPythonコンテナ内に必要パッケージが導入されていきます

docker build -t example-cfn-lint .

ビルド後にコンテナを立ち上げます
Dockerホストのファイルをコンテナ内の/workspaceにマウントしているため、コンテナ内でのファイル変更はDockerホストのファイルにも変更が反映されます

docker run -d -i -v $(pwd):/workspace --name example-cfn-lint example-cfn-lint

コンテナを停止・再度開始する時は以下コマンドで可能です

docker stop example-cfn-lint
docker start example-cfn-lint

VSCodeをコンテナにアタッチ

VSCodeを開いて左下の青い部分をクリックし、「実行中のコンテナーにアタッチ」をクリック

example-cfn-lintのコンテナをクリック

新しいウィンドウが開くので「フォルダを開く」から/workspaceを開く

以上でVSCodeをCloudFormationテンプレート用コンテナにアタッチできました

設定ファイル作成・拡張機能インストール

最終的にファイル構成が以下になるよう、設定ファイルを作成していきます

拡張機能のインストール

.vscode/extensions.jsonを作成し、必要な拡張機能となる以下を定義します

{
  "recommendations": [
    "kddejong.vscode-cfn-lint",
    "aws-scripting-guy.cform",
    "editorconfig.editorconfig"
  ]
}

VSCodeの拡張機能から検索窓に@recommendedと入力し検索すると、先ほど定義した3拡張機能が表示されるので片っ端からインストールを行います

VSCode設定ファイルの作成

.vscode/settings.jsonを作成します
CFnのテンプレートでは!Subや!Refなどのタグが存在しますが
VSCode上でそのタグが解決できるよう、カスタムタグをsettings.jsonに記載します

{
  "yaml.customTags": [
    "!Base64 scalar",
    "!Cidr scalar",
    "!And sequence",
    "!Equals sequence",
    "!If sequence",
    "!Not sequence",
    "!Or sequence",
    "!Condition scalar",
    "!FindInMap sequence",
    "!GetAtt sequence",
    "!GetAZs scalar",
    "!ImportValue scalar",
    "!Join sequence",
    "!Select sequence",
    "!Split sequence",
    "!Sub scalar",
    "!Sub sequence",
    "!Transform mapping",
    "!Ref scalar",
  ]
}

EditorConfig設定

.editorconfigファイルを作成し、以下を記入します
EditorConfigがあるとインデントや末尾のスペース除去などが統一されるため、複数人でテンプレートをGit管理している場合などに文末の空白などで余計な差分が出ないようになります

root = true

[*]
end_of_line = lf
insert_final_newline = true
indent_style = space
indent_size = 2
trim_trailing_whitespace = true

[*.md]
trim_trailing_whitespace = false

こちらでCloudFormationテンプレートが快適に書ける環境の構築は完了ですので、実際に使っていきましょう

使ってみる

example.yamlを作成、テンプレートを書いてみます

AWSTemplateFormatVersion: "2010-09-09"
Description: Example

Resources:
  VPC:
    Type: AWS::EC2::VPC
    Properties:
      CidrBlock: 10.0.0.0/16
      EnableDnsSupport: "true"
      EnableDnsHostnames: "true"
      Tags:
        - Key: Name
          Value: example-vpc
  InternetGateway:
    Type: AWS::EC2::InternetGateway
    Properties:
      Tags:
        - Key: Name
          Value: example-igw
  VPCGatewayAttachment:
    Type: AWS::EC2::VPCGatewayAttachment
    Properties:
      VpcId: !Ref VPC
      # ここを書いていく

• プロパティの補完
  プロパティの先頭を記載すると、プロパティの補完が効きます
  

• Refの補完
  カーソルを置いて!Ref Inと入力すると、参照できる論理IDの補完が効きます
  

• 有効な値が決まっている値のチェック
  例えばAWS::EC2::Instanceのクレジットオプションなど指定できる値が定義されている場合、異なるものを指定するとエラーになってくれます
  

• CFnテンプレートリファレンスへのリンク
  InternetGatewayのRefで取れる値ってなんだっけ…みたいな時にテンプレートリファレンスを確認するかと思いますが
  該当論理IDの上にカーソルを当てると、テンプレートリファレンスへのリンクが出てきます
  多量のリソースのテンプレートリファレンスの中から欲しいリソースの情報を手で探すと若干の手間ですが、これを使えば一発でそのリソースのテンプレートリファレンスが出てくるので便利ですね
  
  この機能は本当によく使います。それぞれのプロパティを覚えられるわけもないので、すぐにテンプレートリファレンスを参照できるのは地味に助かる機能です

Linterとしての機能は他にもありますが、LinterがあるとAWSにスタック展開→エラーでやり直し…の数がかなり減る印象です

• グラフ表示
  また、リソースに記載のRefやGetAtt等どのリソースがどのリソースと依存しているのかを視覚的に見やすくするものとして、グラフ表示機能が存在します
  グラフ表示についてはCtrl+Shift+Pを押して「CloudFormation」を入力すると出てくるため、Enterを押下
  
  ちょっと間を置いてグラフが表示されます(VPCにPublic/PrivateSubnetがありEC2が置いてある構成例)
  
  1テンプレートに記載するリソース量が増えてくると依存関係の把握が難しくなっていきますが、グラフで見ると一目瞭然です
  ただこのグラフ、CloudFormationテンプレートの記述にミスがあると永遠に待ってもグラフ表示が出ません
  正常に記載していても若干の間はありますが、あまりにも出ない場合は記述ミスを疑ったほうが良さそうです

さいごに

CloudFormationテンプレートを快適に書ける環境の構築やざっくりとした使い方は以上になります
Linterやグラフ表示を導入して、楽にテンプレートを書ける・管理できる生活を送りましょう！

株式会社BTMではエンジニアの採用をしております。
ご興味がある方はぜひコチラをご覧ください。