AWS CloudFormation のネストしたスタックのエラーを探索するツールの紹介

はじめに

AWS CloudFormation を使用してインフラを管理する際、エラー箇所を特定することが手間です。特にネストしたスタックでは、ブラウザ上の AWS コンソールから多くログを確認しつつスタックを辿っていくのでかなり煩雑になります。

今回は、このような問題を解決するために開発した「cfn-error-detector」というツールを紹介します。

cfn-error-detectorとは

cfn-error-detector は、AWS CloudFormationのデプロイメント失敗の根本原因を検出するためのコマンドラインツールです。複雑なネストされたスタック内でもエラーのあるリソースを特定でき、トラブルシューティングをより簡単かつ効率的にします。

セットアップ方法

cfn-error-detectorのインストールには、Rye という Python 用のパッケージマネージャーを使用します。

Ryeのインストール：公式のインストールガイドに従って Rye をインストールします。

cfn-error-detectorのインストール：

rye tools install --git 'https://github.com/techscore/cfn-error-detector' cfn-error-detector

使用方法

スタック名が foo-app-stack の場合の例です。

エラー原因の検出

指定したスタックのエラー原因を表示するには、detectサブコマンドの後にスタック名を指定します。

cfn-error-detector detect foo-app-stack

また、エラー元のテンプレートファイルのパスを表示するには、ルートのテンプレートファイルのパスを指定します。

cfn-error-detector detect foo-app-stack -t template.yaml

スタックのロールバック実行

スタックのロールバックを手動で開始するには、rollbackサブコマンドの後にスタック名を指定します。

cfn-error-detector rollback foo-app-stack

ロールバックを実行して、完了するまで待機します。

エラー検出方法の解説

cfn-error-detectorは、AWS CloudFormationのAPIを使用して、スタックのイベントを再帰的に探索し、エラーを検出します。主な検出方法は以下の通りです:

describe_stack_events APIの使用: describe_stack_events APIを使用して、指定されたスタックのイベント履歴を取得します。このAPIは、指定されたスタックに関連するすべてのイベントを逆順に返します。
エラーイベントのフィルタリング: 取得したイベントの中から、ResourceStatus が FAILED を含むものをエラーイベントとして抽出します。これにより、エラーの原因となった具体的なリソースとその理由を特定できます。
ネストされたスタックの検出と再帰的探索: イベントの中で ResourceType が AWS::CloudFormation::Stack であるものを検出し、そのリソースを新たなスタックとして再帰的に探索します。これにより、ネストされたスタック内のエラーも漏れなく検出できます。
エラー情報の集約: 検出されたエラーイベントの詳細情報(スタック名、リソースID、エラーメッセージなど)を集約し、全てのネストしたスタックのエラーを一度に確認できるようにします。
最後のデプロイのみに絞った検出: スタックイベントを時系列順に分析し、最新のデプロイメント操作を特定します。これにより、過去のデプロイメントで発生したエラーを除外し、現在の問題に焦点を当てることができます。

この方法により、複雑なネストされたスタック構造においても、全てのレベルのエラーを効率的に特定することができます。

出力例

[1] 2024-07-02 14:47:05.835000+09:00
  Status: UPDATE_FAILED
  ID: SNSTopic
  Type: AWS::SNS::Topic
  Reason: Resource handler returned message: "Invalid parameter: Topic Name (Service: Sns, Status Code: 400, Request ID: 4a...)" (RequestToken: 13...., HandlerErrorCode: InvalidRequest)
  Stack: FooStack / BarStack
  Path: foo/bar/template.yaml

ベストプラクティス

自動ロールバックの無効化

CloudFormationスタックの自動ロールバックを無効にすることをお勧めします。これにより、失敗の根本原因をより適切に調査できます。スタックのロールバックが発生すると、子スタックが削除され、イベントの取得（cloudformation:DescribeStackEvents）に失敗する可能性があります。

必要なAWS権限

cfn-error-detectorを使用するには、以下のAWS IAM権限が必要です：

cloudformation:DescribeStackResources
cloudformation:DescribeStacks
cloudformation:DescribeStackEvents
cloudformation:RollbackStack

まとめ

cfn-error-detectorを使用することで、AWS CloudFormationのネストしたスタックで発生するエラーを迅速に特定し、詳細な情報を取得することができます。これにより、トラブルシューティングの効率が向上し、スタックの管理がよりスムーズに行えるようになります。

複雑なCloudFormation構成を扱う開発者やインフラエンジニアにとって、このツールは非常に有用なものとなるでしょう。ぜひ、自身のプロジェクトで試してみてください。

参考リンク

鰺坂誠也（アジサカセイヤ）

猫に脳を食べられた人です。

シナジーマーケティング株式会社では一緒に働く仲間を募集しています。

TECHSCORE BLOG

クラウドCRMを提供するシナジーマーケティングのエンジニアブログです。