CloudFormation マクロの概要 - AWS CloudFormation
スタックを直接作成する方法考慮事項マクロアカウントの範囲と許可

CloudFormation マクロの概要

マクロを使用してテンプレートを処理するには、2 つの主要なステップがあります。マクロ自体を作成すること、そして次にマクロを使用してテンプレートに対して処理を実行することです。

マクロ定義を作成するには、以下を作成する必要があります:

  • テンプレート処理を実行するための Lambda 関数。この Lambda 関数は、スニペットまたはテンプレート全体、およびユーザーが定義した追加のパラメーターを受け入れます。処理されたテンプレートスニペットまたはテンプレート全体をレスポンスとして返します。

  • AWS::CloudFormation::Macro タイプのリソース。これにより、ユーザーは CloudFormation テンプレート内から Lambda 関数を呼び出すことができます。このリソースは、このマクロを呼び出して Lambda 関数の ARN、およびデバッグを支援するための追加のオプションプロパティを指定します。このリソースをアカウント内に作成するには、AWS::CloudFormation::Macro リソースを記述したテンプレートを作成し、次にそのテンプレートからセルフマネージド型のアクセス許可を持つスタックまたはスタックセットを作成します。AWSCloudFormation StackSets では現在、マクロを参照するテンプレートから、サービスマネージド型アクセス許可を使用してスタックセットを作成または更新することができません。

マクロを使用するには、テンプレート内の次のマクロを参照してください。

  • テンプレートのセクション、つまりパートを処理するには、変換したいテンプレートのコンテンツを基準にして配置されている Fn::Transform 関数内のマクロを参照します。Fn::Transform を使うときは、必要とされる特定のパラメータを渡すこともできます。

  • テンプレート全体を処理するには、Transform セクションでマクロを参照してください。

次に、通常は変更セットを作成して実行します。(マクロを処理すると、気付かないうちに複数のリソースが追加されていることがあります。マクロに伴うすべての変更を確実に認識できるように、変更セットを使用することを強くお勧めします。) CloudFormation は、マクロリソースに指定された Lambda 関数に、指定されたテンプレートコンテンツとその他の指定されたパラメータを渡します。Lambda 関数は、スニペットまたはテンプレート全体で処理されたテンプレートコンテンツを返します。

テンプレート内のすべてのマクロが呼び出されたら、CloudFormation はテンプレートで処理したコンテンツを含めた変更セットを生成します。変更セットを確認したら、これを実行して変更を適用します。

Fn::Transform 組み込み関数またはテンプレートの Transform セクションを使用して、処理されたテンプレートの内容を返すマクロの基盤となる Lambda 関数にテンプレートの内容と関連付けられたパラメーターを渡します。

スタックを直接作成する方法

マクロを参照するテンプレートを使用してスタックを作成または更新するには、通常、変更セットを作成して実行します。変更セットは、処理されたテンプレートに基づいて CloudFormation が実行するアクションを記述します。マクロを処理すると、知らないうちに複数のリソースが追加される可能性があります。マクロに伴うすべての変更を確実に認識できるように、変更セットを使用することを強くお勧めします。変更セットを確認したら、これを実行して実際に変更を適用します。

マクロによってテンプレートに IAM リソースが追加されることがあります。これらのリソースの場合、それぞれどのような機能を備えているかを確認する必要があります。CloudFormation は、テンプレートを処理しなければ、どのリソースが追加されるのかを認識することができません。そのため、参照されたマクロに IAM リソースが含まれている場合は、IAM の機能を把握したうえで変更セットを作成する必要があります。こうすることで、変更セットを実行するときに、CloudFormation が IAM リソースを作成するために必要な機能を準備できます。

変更セット内の提案された変更を最初に確認せずに、処理済みのテンプレートから直接スタックを作成または更新するには、CreateStack または UpdateStack リクエスト中に CAPABILITY_AUTO_EXPAND 機能を指定します。マクロが含まれているスタックテンプレートから直接スタックを作成するのは、どのような処理がマクロで実行されるかを把握している場合に限ります。スタックセットマクロで変更セットを使用することはできません。スタックセットを直接更新してください。

詳細については、「AWS CloudFormation API リファレンス」の「CreateStack」または「UpdateStack」を参照してください。

重要

スタックセットテンプレートに 1 つ以上のマクロが参照されており、変更セットの結果を確認せずに、処理されたテンプレートから直接スタックセットを作成する必要があります。マクロを処理すると、知らないうちに複数のリソースが追加される可能性があります。マクロを参照するテンプレートから直接スタックを作成または更新する前に、どのような処理がマクロで実行されるかを確認してください。

マクロを参照するテンプレートからスタックを起動する際のステップ数を減らすには、package および deploy AWS CLI コマンドを使用できます。詳細については、AWS CLI を使用してローカルアーティファクトを S3 バケットにアップロードするおよび変換が含まれるスタックを作成するを参照してください。

考慮事項

マクロを使用する場合は、次の注意事項と制限事項に留意してください。

  • マクロは Lambda を使用できる AWS リージョン でのみサポートされます。Lambda を使用できるリージョンのリストについては、「AWS Lambda endpoints and quotas」( エンドポイントとクォータ) を参照してください。

  • 処理されたテンプレートスニペットはすべて有効な JSON である必要があります。

  • 処理されたテンプレートのスニペットは、スタックの作成、スタックの更新、スタックセットの作成、またはスタックセットの更新オペレーションの検証チェックに合格する必要があります。

  • CloudFormation は、まずマクロを解決し、次にテンプレートを処理します。生成されるテンプレートは有効な JSON である必要があり、テンプレートサイズ制限を超えることはできません。

  • CloudFormation がテンプレート内のエレメントを処理する順序のため、マクロは CloudFormation に返される処理済みテンプレートコンテンツにモジュールを含めることはできません。詳細については、「マクロ評価順」を参照してください。

  • 更新ロールバック機能を使用する場合、CloudFormation は元のテンプレートのコピーを使用します。含まれるスニペットが変更されていても、元のテンプレートにロールバックされます。

  • マクロは再帰的に処理されないため、マクロをマクロ内に含めることはできません。

  • Fn::ImportValue 組み込み関数は、現在マクロではサポートされていません。

  • テンプレートに含まれている組み込み関数は、マクロの後で評価されます。したがって、マクロが返す処理済みテンプレートコンテンツに組み込み関数の呼び出しを含めることができ、それらは通常どおりに評価されます。

  • StackSets では現在、マクロを参照するテンプレートから、サービスマネージド型アクセス許可を使用してスタックセットを作成または更新することができません。

マクロアカウントの範囲と許可

マクロは、リソースとして作成されたアカウントでのみ使用できます。マクロ名は指定のアカウント内で一意である必要があります。ただし、基盤となる Lambda 関数でクロスアカウントアクセスを有効にし、その後複数のアカウントでその機能を参照するマクロ定義を作成することで、同じ機能を複数のアカウントで使用できるようにすることができます。以下の例では、3 つのアカウントにそれぞれ同じ Lambda 関数を指すマクロ定義が含まれています。

Lambda 関数でクロスアカウントアクセスを許可することで、AWS はその関数を参照するマクロを複数のアカウントで作成することを可能にします。

マクロ定義を作成するには、ユーザーは指定されたアカウント内にスタックまたはスタックセットを作成するための許可を持っていなければなりません。

CloudFormation がテンプレートに含まれているマクロを正常に実行するには、ユーザーは基盤となる Lambda 関数に対する Invoke アクセス権限を持っている必要があります。アクセス権限がエスカレーションしないよう、マクロの実行中に CloudFormation はユーザーとして振る舞います。

詳細については、「AWS Lambda デベロッパーガイド]の「Managing permissions in AWS Lambda」および[サービス認可リファレンス」の「Actions, resources, and condition keys for AWS Lambda」を参照してください。